v4.21 Release Notes
firstname.lastname@example.org release (August 2022 #2)
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.
We’re excited to announce
gatsby-plugin-mdx v4! 🎉 With the help of our contractor axe312ger we have rewritten the plugin from scratch to give you these new features:
- Full compatibility with MDX 2
- Per-file tree shaking and chunking (No more
app.jsbundle bloat or global scope problems)
- Simplified usage in pages
- Simplified plugin options
- You can configure the underyling
@mdx-js/mdxcompile, e.g. to add
Over the last couple of months we’ve been hard at work building a new version of
gatsby-plugin-mdx. The PRs #35650 and #35893 are the culmination of these efforts.
It also can’t be overstated that the complete rewrite from scratch allowed us to set up the plugin for easier maintenance in the future. While this isn’t a particular exciting user-facing feature, from a maintainer’s perspective this will be a huge benefit for any future upgrades we (or you, the community) want to make to
gatsby-plugin-mdx v4 is ready for primetime and you can start using it now.
There are multiple ways on how you can get started with
- Initialize a new project with
npm init gatsbyand choose the “Add Markdown and MDX support” option
- Follow the Adding MDX pages guide
- Follow our beginner friendly tutorial to learn how to create a blog with MDX
- Try out the using-mdx example
- Fork this CodeSandbox
gatsby-plugin-mdx README contains detailed instructions on any new options and APIs.
Migrating from v3 to v4
If you’re already using
gatsby-plugin-mdx v3 and want to migrate, you can follow the extensive migration guide to benefit from all new features.
We did our best to strike a balance between introducing meaningful breaking changes and keeping old behaviors. For example, while a lot of people use GraphQL nodes like
wordCount, over the years it has become increasingly hard to fulfill every feature request and behavior that users wanted (e.g. correctly providing
wordCount for every language is hard). One the one hand removing default fields like these means that you have to reimplement them on your own, but on the other hand this also means that you can more granularly customize them to your needs. Read Extending the GraphQL MDX nodes for guidance on how to migrate.
If you have any questions along the way, post them either into the umbrella discussion or into the
mdx-v2 channel on Discord.
The using-mdx example also showcases some of the necessary migration steps.
We are adding a new API that we are calling “Slices”. By using a new
<Slice /> React component in combination with a
src/slices directory or
createSlice API for common UI features, Gatsby will be able to build and deploy individual pieces of your site that had content changes, not entire pages.
To create a slice, simply:
Create the slice by adding a
slices/footer.jsfile, or using the
<Slice />component on your site, providing an
aliasstring prop, where
aliasis either name of the file (in our case,
footer). Any additional props passed will be handed down to the underlying component.
To read more, head over to RFC: Slices API. We appreciate any feedback there.
sort and aggregation fields in Gatsby GraphQL Schema
We are proposing Breaking Changes for the next major version of Gatsby to our GraphQL API. The goal of this change is increasing performance and reducing resource usage of builds. Proposed changes impact
sort and aggregation fields (
Basic example of proposed change:
To read more, head over to RFC: Change to sort and aggregation fields API. We appreciate any feedback there.
Notable bugfixes & improvements
sharpwas updated to
0.30.7(also in all other related packages). This deprecates the
failOnErroroption as it’s being replaced by the
failOnoption, via PR #35539
gatsby-source-contentful: Correctly overwrite field type on Assets, via PR #36337
gatsby-plugin-react-helment: Stop appending empty title tags, via PR #36303
gatsby-link: Correctly export default for CommonJS, via PR #36312
A big Thank You to our community who contributed to this release 💜
- Bi11: fix(gatsby-plugin-image): Add
- Kornil: chore(gatsby): convert babel-loader-helpers to typescript PR #36237
- Auspicus: chore(docs): Pre-encoded unicode characters can’t be used in paths PR #36325
- axe312ger: BREAKING CHANGE(gatsby-plugin-mdx): MDX v2 PR #35650