I'm a massive fan of Gatsby.

If you've not heard of it its a static site generator that uses React to make super fast sites. I really enjoy using React anyway so discovering Gatsby was a real treat.

It is however, relatively new and although the documentation is generally brilliant it doesn't have quite the same level of google-ability as other tools. The chances of finding someone on StackOverflow with your exact issue (conveniently solved of course) isn't that high.

I've therefore come across a few snagging issues that have taken a fair bit of time to solve. And as a new recruit I don't yet have that list in my head of things to check everytime I run into an issue.

Caching issues...

This is something I always forget. There have been a fair few occasions where I've been tearing my hair out because a change I've made doesn't seem to have worked only to have my husband walk in, casually say "Have you done a hard refresh?" and walk out again. Inevitably I hadn't done a hard refresh and everything had worked the first time it had just cached.

When you're developing with Gatsby a cache is created to save you time. Now I really don't know half the inner workings of Gatsby but I think it deletes the cache if you make changes to certain files where you're likely to need it deleted (e.g. your gatsby-config file).

I still find that I run into mysterious problems sometimes though. Often after editing a markdown file (or adding a new one) I will start getting unexpected errors in my dev build that suggest graphQL is struggling to find my data. After many wasted hours I've discovered that so many of these problems can be fixed by clearing the cache and public folder.

Gatsby provide an easy way to do this now so simply close the dev server, then type this command.

gatsby clean

This deletes the cache and public folders for you. They will be remade once you rebuild (dev or prod) so just run the dev server again.

gatsby develop

If your problem was a caching issue the error will be gone and hopefully everything will be rosy. Its not always going to be a fix of course, but if you come across an unexpected error when you changed very little its always worth running this command and restarting the server before you start any proper debugging.

This may be super obvious to lots of people but as a newbie it was not to me!

A little example...

I actually ran across this exact issue while creating this blog post. Before I started to write the post I had created a test post to check that a change I had made to my gatsby-node file was working. I then deleted that post and created this one. All looked good on the dev server, the test post had gone and the new one was sitting where it should be.

This blog has 'older' and 'newer' links at the bottom of every post that use gatsby's pageContext. I discovered that when I clicked the 'older' link it threw a 404 error because it was still trying to link to the non-existent test page. A quick gatsby clean and restart of the dev server and everything was working as it should!