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.ΒΉ 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.

The Startup

Medium's largest active publication, followed by +773K people. Follow to join our community.

𝐁𝐚𝐲𝐚𝐧 𝐁𝐞𝐧𝐧𝐞𝐭𝐭

Written by

My goal is to serve humanity and to bring happiness to others. I want to understand the problems around us and help find solutions. https://www.bayanbennett.com

The Startup

Medium's largest active publication, followed by +773K people. Follow to join our community.

𝐁𝐚𝐲𝐚𝐧 𝐁𝐞𝐧𝐧𝐞𝐭𝐭

Written by

My goal is to serve humanity and to bring happiness to others. I want to understand the problems around us and help find solutions. https://www.bayanbennett.com

The Startup

Medium's largest active publication, followed by +773K people. Follow to join our community.

Medium is an open platform where 170 million readers come to find insightful and dynamic thinking. Here, expert and undiscovered voices alike dive into the heart of any topic and bring new ideas to the surface. Learn more

Follow the writers, publications, and topics that matter to you, and you’ll see them on your homepage and in your inbox. Explore

If you have a story to tell, knowledge to share, or a perspective to offer β€” welcome home. It’s easy and free to post your thinking on any topic. Write on Medium

Get the Medium app

A button that says 'Download on the App Store', and if clicked it will lead you to the iOS App store
A button that says 'Get it on, Google Play', and if clicked it will lead you to the Google Play store