v5.3 Release Notes
Welcome to gatsby@5.3.0
release (December 2022 #1)
Key highlights of this release:
Also check out notable bugfixes.
Bleeding Edge: Want to try new features as soon as possible? Install gatsby@next
and let us know if you have any issues.
ES Modules (ESM) in Gatsby files
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. Before now, gatsby-config
and gatsby-node
had to be written in CJS. Earlier this year, we also included support for TypeScript, allowing you to author your gatsby-*
files in TypeScript.
Support for ESM in gatsby-config
and gatsby-node
files has been a highly requested feature in the community, and ecosystems that Gatsby interacts with like MDX and unified have switched to ESM, dropping CJS in their latest major releases. In this release, we’ve included support for ESM in gatsby-node.mjs
and gatsby-config.mjs
. This means that you can now use ESM-only packages without any workarounds. Here’s an example gatsby-config.mjs
file:
Please note: 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.
The ESM in Gatsby files umbrella discussion is also the right place for any questions about the .mjs
usage.
Improved error messages
Show original stack trace from workers
You might have run into an error like this while using Gatsby:
Gatsby uses child processes to execute its GraphQL queries in parallel (with its own package gatsby-worker
). When Parallel Query Running was introduced these child processes were already instructed to propagate their errors to the main process so that you can see what actually happened. Unfortunately, at a certain workload the child processes didn’t have enough time to relay those messages and you were left alone with the above mentioned worker error.
In the PR feat(gatsby-worker): Show original stack trace we have now given gatsby-worker
the ability to save its errors to a local, temporary file and then the main process can playback any messages that otherwise might have been lost. We have further plans to improve this functionality but the main pain point was fixed with the above PR. You should now successfully see the original error, with any amount of workload.
Improve readability of errors & warnings
When you saw the error “Building static HTML failed for path …” or the warning “This query took more than 15s to run…” Gatsby printed the complete contents of the page data to the terminal. The intentation behind that was to give you enough context to fix the error yourself. But since this also included the GraphQL results those logs could get verbose really quickly. In the PR #37220 this was fixed by removing properties from the page data, including the GraphQL results before printing them out. In normal circumstances the errors thrown by GraphQL or Gatsby itself will give you enough details to solve your error.
Improved error during Gatsby Preview
When you use Gatsby Preview and your site errors out on rendering the HTML, you’ll now see an improved overlay. The PR #37195 improved the CSS styling, made it clearer what the error is and how to fix it, and added clearer structure to the overlay itself.
Notable bugfixes & improvements
gatsby-plugin-image
: Ensure cache hash is unique, via PR #37087gatsby
:gatsby-plugin-utils
: AddpathPrefix
to Image CDN URLs, via PR #36772- Miscellaneous dependency updates:
Contributors
A big Thank You to our community who contributed to this release 💜
- mudge: fix(gatsby): Use path prefix when loading slice data PR #37202
- heimoshuiyu: feat(gatsby-transformer-sharp): Add
avif
to supportedExtensions PR #37112 - openscript: feat(gatsby): Add
documentSearchPaths
option tographqlTypegen
PR #37120