Gatsby, gatsby-image, and Netlify CMS
July 10th, 2019
In my previous podcast, I talked about how I have been trying to add Netlify CMS to interglobalmedianetwork.com, my business website. Well, guess, what? I just completed implementing it a little while ago today, and everything works beautifully.
It took a few workarounds, trial and error, asking for help from the Netlfy Community (specifically and especially NetlifyCMS lead developer Shawn Erquhart, @erquhart on Twitter) and experimentation, but I finally brought it together!
The terser issue: still in the picture
The terser issue is still in the picture. Every time I make a change to my
package.json, either adding or removing an npm package, I have to
repeat the following steps afterwards:
rm -rf node_modules npx npm-force-resolutions npm i
Why? Because whenever I either add or remove a package related to Gatsby, I receive warnings that various peerDependencies are not installed, and that I have to install them myself. This behavior has been part of npm since version npm@3.
According to npmjs,
Trying to install another plugin with a conflicting requirement will cause an error. For this reason, make sure your plugin requirement is as broad as possible, and not to lock it down to specific patch versions.
Well, as you may remember if you listened to my previous podcast, I added
terser 4.1.2 to my
resolutions object in
package.json. As I also
mentioned, this took care of the
source-maps issue and made sure that all
terser were compatible with this version which I added to
package.json. And that is why I have to repeat my
npm-force-resolutions ritual every time I make Gatsby related
changes to my
package.json. This is also why I decided to go with using
gatsby-cli, because I got so many warnings about missing
peerDependencies when I tried to install it globally. So until Gatsby has
resolved its dependency/peerDependency issues across the board, and
more specifically the terser/source-maps issue, I will continue executing
this pattern whenever I make changes to my
package.json. It’s a pain, but it
Source-maps still cause a break on build
In order to prevent a break on build due to the
source-maps issue, I
still have a custom webpack config added to the bottom of my
gatsby-node.js file. Please refer to the post transcript of this podcast
on interglobalmedianetwork.com to
view the code snippet.
Things did not stop there, however. I had another issue to address. That of
image upload via Netlify CMS and the resulting Netlify CMS
gatsby-image and Gatsby
grapql. The original
structure of my website was definitely NOT compatible with Netlify
CMS. Each post had its own folder. The name of the folder was the post slug,
and the markdown file was named
index.md. That was so that I would only
have one slug to deal with and not two. Naming
index.md anything but
index.md would result in something like:
By naming the markdown file
index.md, the second post slug would be
But as I said, Netlify CMS does not work with posts contained in their own
individual folders containing the
index.md markdown file and any images
used in the post.
I had to rename my post markdown files by replacing
index with the
slug. It ended up looking something like this:
And I removed all the post folders.
content/blog ended up only
containing the markdown files and nothing else. I moved the
images into the static folder within a subfolder called img.
Then I made the necessary adjustments to the Netlify CMS
related to post images, and made whatever image related
adjustments needed in
Gatsby assumes that images are in the same location as the posts. However, Netlify CMS places all images in one place. In the static folder, and then possibly in a subfolder. In my case, a subfolder called img. It is very important that you be consistent across files about the path to your blog post image(s). Double, triple check, and even quadruple check if you have to. I think that ended up being part of my problem and why I threw certain errors.
For example, at one point towards the end of my Netlify CMS journey, I was continuously getting the following error in Terminal on build:
"Field "image" must not have a selection since type "String" has no subfields."
This can be a real bug, and I found in my research that some developers
used a Gatsby plugin called
gatsby-remark-relative-images to fix the
issue. However, in my case, I found out that it was just an inconsistency
in my Netlify CMS image related paths across configuration files.
Once I made sure that all my markdown image paths were the same across
gatsby-config.js, and all the
post markdown files, everything worked as it should and resulted in a
successful build locally and remotely.
Then there is the
gatsby-plugin-netlify-cms-paths. Why this plugin?
gatsby-plugin-netlify-cms-paths changes the file paths in your markdown files
to Gatsby friendly paths when using Netlify CMS to edit them.
When this plugin is used, I can embed an image in a markdown file in markdown syntax:
and still be able to access
gatsby-image's “blur-up” behavior.
Suffice it to say, I am using Netlify CMS along with
in production. It is working well thus far, and no problems on remote build. I
must say that I was not familiar with the process of forcing
resolutions in npm, but once I researched it further, and tested it on
interglobalmedianetwork.com, I felt
comfortable to use it in production. Just be sure to go through the necessary
resolution steps each time you make a change to your package.json. And as I
mentioned in my
depending on what (other) packages you are using, it might not work equally across projects.
I will be embedding this episode of Plugging in The Holes along with a transcript in the form of a post on interglobalmedianetwork.com for your hearing and reading pleasure. I will be including the related resource links mentioned in the podcast of course. Always do. Bye for now!
Created by Maria D. Campbell who lives and works in New York City building and teaching useful things. You should follow her on Twitter.