gatsby-image: difference between childImageSharp vs imageSharp

Question

I'm using gatsby-image to handle automatically handle different image sizes. It works great.

However, in the docs of gatsby-image, one example uses imageSharp in graphql to get different image sizes, while another example uses childImageSharp. I was curious what the difference between the two are?

I assume it has to do with either gatsby-transformer-sharp or gatsby-plugin-sharp, but the docs for those plugins don't have any info on that either.

Answer 1

It's been a while since this question was asked, but I hope to give a direct answer to the question 'what's the different between imageSharp and childImageSharp':

Different between imageSharp & childImageSharp

They are always the same type of node, which is ImageSharp. The difference is the reference point.

In a typical gatsby blog, all files will be first processed with gatsby-transformer-file-system. Each file will get a node with information such as what type of file it is, then, a plugin like gatsby-transformer-sharp will pick up the node with the relevant type/extension, then process it further and create a new node:

File                                image.png

                                        |

                                   create a node with
gatsby-transformer-file-system ->  "type": "File",
                                   "extension": "png"

                                        |

                                   whenever see a node 
                                   with a valid image extension,
gatsby-transformer-sharp       ->  create a node with
                                   "type": "ImageSharp"
                                   that contains info of images
                                   processed by `gatsby-plugin-sharp`

Whenever this happens, a parent-child relationship is created between the original File node and the ImageSharp node. The child ImageSharp node will be queriable on the File node with the name childImageSharp.

File                                ImageSharp
  |--id: 1                              |--id: 2
  |--children                           |--parent
  |     `--[ id: 2 ]                    |    `--id: 1
  `--childImageSharp                    |--fluid
        |--id: 2                       ...
        |--fluid
       ...

It means you can query the same ImageSharp node in at least 2 ways:

1. From the File node

ImageSharp node doesn't contain any info about its location in the file system, so if you want to get an image from folder src/X, you'd need to query it like:

query {
  // relativePath is relative to the folder set in `gatsby-transformer-file-system`
  file ( relativePath: { eq: "src/X"} ) {
    childImageSharp {
      id
      fluid {
        src
      }
    }
  }
}

2.Directly get the ImageSharp

Perhaps somehow you know the exact id of the ImageSharp node. You can get it by:

{
  imageSharp (id: {eq: "2"}) { // not a real id
    id
    fluid {
      src
    }
  }
}

You can also query multiple images from allFile, or allImageSharp.

This will return with an error:

// error
{
  childImageSharp {
    id
  }
}

Other plugins share the same kind of relationship as well. You can also find a childMardownRemark node on the File type, that resolve to a MarkdownRemark node.

It doesn't have anything to do with gatsby-image -- it's just different way to resolve to the same node.