Ben Borgers

How to set up netlify.toml for Gatsby

December 18, 2019

Netlify’s configuration file, netlify.toml, allows you to define various settings for how your site will be deployed on Netlify.

A basic netlify.toml file (placed at the root directory of your project) for a Gatsby site looks like this:

    command = "gatsby build"
    publish = "public"
    command = "gatsby develop"

The first [build] block tells Netlify that they should run gatsby build on their servers whenever you publish a new version of the site, and then publish whatever Gatsby puts in the public folder.

The second [dev] block tells Netlify that it should run gatsby develop whenever you run netlify dev on the command line to develop locally. Why use netlify dev instead of gatsby develop, the normal way of starting Gatsby’s development server? Running Gatsby’s command through Netlify Dev allows you to emulate the final Netlify site more closely. This includes:

  • Pulling in environment variables defined in your Netlify site dashboard
  • Performing Netlify redirects you’ve defined
  • Compiling and locally running Netlify Functions

There’s a lot more you can configure in your netlify.toml file, such as environment variables, redirects, headers, and image compression. More information is in Netlify’s documentation.

Subscribe to my newsletter!

A weekly round-up of new blog posts and updates to projects I’m working on.