This post is about the problem with trying to learn (or trying to teach) a new framework that is constantly evolving. Here’s what I have experience with:
- Deploying a Gatsby site from GitHub using Netlify to a example.netlify.com address
- As of this install that I am documenting now, setting up a headless WordPress installation locally. That site is also (as mentioned) on GitHub already.
With those two realities, I figured that setting up Netlify to deploy this new site would be as simple as connecting to this existing GitHub Repo and deploying.
Narrator voice: it was not simple.
I don’t know for sure, but my hunch is that the reason the build is failing has to do with the fact that this starter site was last updated (with the exception of a recent bugfix) a while ago. The same reason that I had to run yarn upgrade in order to make the GraphiQL explorer work is likely the reason that something is not jiving with Netlify.
For one, I was getting an error/warning related to the __experimentalThemes tag in the config file being deprecated. A quick search online revealed that I should be using plugins instead.
I made that change, and things are still building with no problem on my local machine, and showing up great on localhost, but still builds are failing on Netlify.
I’ve been around the self-guided training block (and the documentation writing block, while I’m at it) enough to know that what’s going on is either that the sample repo I am using is not updated, or that the version of one of the tools I have on my local machine is not updated. Yarn, NPM, gatsby cli, or something else that is working locally is most likely a different version on Netlify’s side, and that’s breaking things.
Normally I wouldn’t spend a whole post on a failed deploy, but I want this resource to be helpful to others who might run into issues here.
Also, it’s issues like this that the Gatsby community needs to figure out clear workarounds for (or maybe just publicize them better… my expert level Google-fu did not uncover the issue or fix) in order to build a clear on-ramp for wider adoption of the platform by folks like me (or folks less stubborn than I who might give up at this point).
Updated a few days later: the issue is that on my Mac, calls to filenames are case insensitive, so when it was looking for SEO or Seo, it went to look for anything in the js files that would work. That is not the case on linux, which is the environment Netlify is looking to in order to build things. Changing all calls to SEO over to Seo resolved this issue, and now things are deploying to Netlify correctly.
