Adding Static Files to a Gatsby Site

Wherever possible, it is preferable to use Gatsby itself for your website assets: these are then automatically optimised, minified, and renamed to include a cache‑busting hash. However, there are inevitably situations where you do need to add static files to your site and don't want them to be processed by webpack or Gatsby.

In my experience, this is often for things like verification files from Google or Bing, or obscure icon formats or naming conventions which otherwise throw 404 errors in the server log. A PHP endpoint can also be copied this way for a deployment server that already supports PHP, perhaps to receive a contact form or capture an error. Gatsby only copies such files; any inclusion or execution happens at request time on the deployment server, not during the Gatsby build.

The answer could not be simpler: just put these files in the static folder in the root of your project. Some of the Gatsby starters do not include this by default, so you may need to create the folder first.

Anything within that static folder will be automatically copied across to the root of public on‑build. Any folders you have within static will also be copied across as‑is.

Not that you should ever do this, but if you then wanted to reference a static file from this folder within React, you would do so by starting with /.

render() {  return <img src={'/folder-inside-static/image.png'} alt="Lorem ipsum" />;}

Read more about using the static folder in the Gatsby documentation here.

Read more about Gatsby's overall project structure in the documentation here.