Gatsby has many features to win the developers' love and prevails over other mainstream static site generators. One of those features is gatsby-image component. It solved the image optimization problem with the specified dimension scope you defined, progressively and responsively presenting to the webpage gives user a comfortable browsing experience.
Steps to use gatsby-image
Like the official doc said, there are three steps needed to implement a gatsby image in Gatsby website:
- install gatsby-image component and two other build dependency plugins: gatsby-transformer-sharp and gatsby-plugin-sharp
- define image source directory in gatsby-source-filesystem plugin as well as above two plugin in
gatsby-config.jsplugins section - import
gatsby-imagecomponent to your gatsby page component and declare a image tag/instance with afixedorfluidproperty whose value derived from graphql query.
In the step 2, you tell the Gatsby build tool, where to find the root directory of all the image files. Just like the doc example, the root directory here is src/images/ of current Gatsby project:
{
resolve: `gatsby-source-filesystem`,
options: {
name: `images`,
path: path.join(__dirname, `src`, `images`),
},
},
In the step 3, you tell gatsby-image component instance where to get the file: graphql query result.
export const query = graphql`
query {
file(relativePath: { eq: "blog/avatars/kyle-mathews.jpeg" }) {
childImageSharp {
# Specify the image processing specifications right in the query.
# Makes it trivial to update as your page's design changes.
fixed(width: 125, height: 125) {
...GatsbyImageSharpFixed
}
}
}
}
`
Which directory to put image?
After seeing this graphql code snippet, you may wonder where's the blog/avatars/kyle-mathews.jpeg? Is it under project root or src/images? let's take a test from a blank gatsby project.
create gatsby project:
$ gatsby new using-image-in-gatsby
place kyle-mathews.jpeg image under src/images/blog/avatars/.
replace original index.js content with the following code:
Note: Dont forget the
dataproperty in IndexPage properties.
Now, we can start the website without the need to modify the other stuff:
$ gatsby develop
Visit the http://localhost:8000/ in your browser, you'll see the correct result.
This experiment verified our speculation, that is:
gatsy-image query(graphql) using relative path under the path defined in gatsby-source-filesystem as query condition!
How about the dynamic image source value?
Above example use static value blog/avatars/kyle-mathews.jpeg to query in graphql expression. Then, what if the query condition is from markdown file meta data?
Official doc about Working with image in Markdown posts and pages told us the placing the featuredImage in the same position of markdown file:
file structure:
├── src
├── pages
├── example-post.md
├── awesome-image.png
example-post.md:
---
title: My Amazing Post
featuredImage: ./awesome-image.png
---
Content goes here!
In this solution, it works though, but, if you have many posts which include many images in each post, the directory structure will grow big dramatically and end up with chaos.
How to restructure the images path in a reasonable way?
- Step one: deine a new content source in
gatsby-config.js
plugins: [
{
resolve: `gatsby-source-filesystem`,
options: {
path: `${__dirname}/content`,
name: `content`,
},
},
...
]
- Step two: place all the images under
content/assets
separate image files and .md files to different folder
├── content
├── posts
├── example-post.md
├── ....md
├── assets
├── fantastic-image.png
├── awesome-image.png
|── ...
├── src
- Step three: reference the image using relative path in markdown file metadata.
example-post.md:
---
title: My Amazing Post
featuredImage: ../assets/awesome-image.png
---
Business intro is missing...
How to use html img tag in a Gatsby application
In a normal web application, html img element can use relative or absolute path to assign src property. We use image in a native and static way like the official doc said, place image under static folder, display image in webpage as we expected. But, when we build and deploy the gatsby site the GitHub Pages, visit it under an URL pattern like this:
https://username.github.io/your-gatsby-website/
The images declared by img tag broken all!
Although all the gatsby-images built by $ gatsby build --prefx-paths works, but those native imgs don't work.
What's the solution?
- One solution is refactor all the
imgs togatsby-imagecomponents - Another solution is add context prefix the img
srcproperty.
For example:
<img src="/ueofcweb/images/project-home.jpg" className="img-fluid" alt="ultronele screenshot" />
ueofcweb is the github project name, images/project-home.jpg is actually under ueofcweb/static.
If you're refactoring a traditional website which use a large amount of img tags, the second option would be a cheap option. My production officail site is migrated from bootstrap/jquey stack, while I was adding it to the Gatsby showcase, I spend hours to figure out that the second approach is the best way to me.
Last note I can give in this post is:
Do not include folders under static folder, it's a BAD practice ending up with build error `childImageSharp' of null.
Gatsby image is the best responsive image solution which I have met. It frees you from the tedious optimization work in the build phase, add good performance and excellent user experience to your website. It deserves you to spend time to delve into and use proficiently.
Top comments (1)
Have you ever seen a Gatsby Image wrapper (think that's what you'd call it) used to dynamically make the graph ql queries. Gatsby Image is great and all, but when you're using it for multiple images in a component the graphql really can get messy bloating the component.
Would be nice if you could for example:
<ImageWrapper fluid='filename.jpg' /> or <ImageWrapper fixed='filename.jpg' />With all the graphql static queries internalized in the wrapper component.