Production GatsbyJS: API Files

Suggested reading: Production GatsbyJS: Plugins

What's the problem?

Sometimes the GatsbyJS API files can get massive. gatbsy-node.js can get big if there are a lot of page generation, gatsby-config.js can get big when you're using a lot of plugins. Big files mean that it can be more difficult to diagnose problems with configuration.

Make a Folder for Each API File

For example:

root/
| gatsby-config/
| | index.js
| | site-metadata.js
| | plugins.js

Converting each API file into a folder unlocks the possibility to make the API files more modular and manageable.

The Gatsby API allows for certain keys to be exported from the API files. For example, the gatsby-config API allows for the plugins key to be exported.

A common example can be found in gatsby-starter-default. An abridged version is provided below:

/* /gatsby-config.js */
module.exports = {
  siteMetadata: {
    title: `Example of a short config file`,
    author: `@bayanbennett`,
  },
  plugins: [
    `gatsby-plugin-react-helmet`,
    {
      resolve: `gatsby-source-filesystem`,
      options: {
        name: `images`,
        path: `${__dirname}/src/images`,
      },
    },
  ],
}

plugins.js

module.exports = [
  `gatsby-plugin-react-helmet`,
  {
    resolve: `gatsby-source-filesystem`,
    options: {
      name: `images`,
      path: `${__dirname}/src/images`,
    },
  },
]

site-metadata.js

module.exports = {
  title: `Gatsby Default Starter`,
  author: `@gatsbyjs`,
}

index.js

module.exports.siteMetadata = require("./site-metadata");
module.exports.plugins = require("./plugins");

Background info

Requiring NodeJS modules

In NodeJS, there are four ways to load a module. NodeJS tries to find the module that you require in this order:

1. files
2. folders
3. node_modules
4. global folders (please don't do this)

Gatsby uses NodeJS to require the API files in the home directory.^1 If the .js files are not available, the next step that it looks for folders that match. There's a few more steps that Node takes to find the right file, but the method we're going to be taking advantage of is the index.js method.

In other words, if you require("./something"), Node will be satisfied if a "./something/index.js" file exists.

Here's where we can make things interesting.

What are the GatsbyJS API Files?

Gatsby uses 4 files in the root of your project to configure your site and control its behavior. All of these files are optional.

• gatsby-browser.js
• gatsby-config.js
• gatsby-node.js
• gatsby-ssr.js

Conclusion

Depending on the project, one or more of the API files mentioned above tends to get large. This makes it more difficult to diagnose problems with configuration.

If each API configuration key has its own file, I've found Gatsby API files more manageable. In particular gatsby-node tends to get bloated over time. As far as modularization goes, this is probably the simplest. However, I haven't yet seen a single Gatsby project that uses this method. I think more should.

Caveat

If the GatsbyJS development team decides to require the file using the extension, this approach will break and you'll have to require the files in the API file and not in a folder.