Migrate to Netlify Today

Netlify announces the next evolution of Gatsby Cloud. Learn more

ES Modules (ESM) and Gatsby


  • Using MDX


The ECMAScript module (ESM) format is the official TC39 standard for packaging JavaScript. For many years, CommonJS (CJS) was the de facto standard in Node.js. You can author gatsby-config and gatsby-node in ESM syntax.

This feature was added in gatsby@5.3.0.


  • A Gatsby project set up with gatsby@5.3.0 or later. (Need help creating one? Follow the Quick Start)

Usage in Gatsby

Generally speaking you need to follow the official standard as explained in the Node.js documentation.


Create a gatsby-config.mjs file. Here’s an example gatsby-config using ESM syntax:


Create a gatsby-node.mjs file and use any of the Node APIs as usual. Here’s an example gatsby-node using ESM syntax:

Migrating from CommonJS to ES Modules

  • Use import/export syntax instead of require/module.exports

  • File extensions in imports are mandatory

  • You can replicate the __dirname call with import.meta.url:

  • You can replicate require.resolve with createRequire:

The documents Interopability with CommonJS and Differences between ES Modules and CommonJS also apply to ESM in Gatsby.

Here’s how you’d migrate a gatsby-config.js file to gatsby-config.mjs.



Current limitations

  • The TypeScript variants of gatsby-config and gatsby-node do not support ESM yet. We plan on adding support in a future minor release by using the .mts extension. If you have questions or suggestions about this, please go to our ESM in Gatsby files umbrella discussion.

    However, you can use Type Hinting in the meantime.

The ESM in Gatsby files umbrella discussion is also the right place for any questions about the .mjs usage.

Start building today on Netlify!
Edit this page on GitHub
© 2023 Gatsby, Inc.