Skip to content

Commit 14792cf

Browse files
marvinjudeLekoArtsimjoshin
authored
chore(docs): Release Notes for 4.21 (#36372)
* add release note template * update changelog url * add mdx * add example * add some bugfixes & improvements * add contributors log * Add RFC callout * format * add jsx to return block Co-authored-by: LekoArts <[email protected]> Co-authored-by: Josh Johnson <[email protected]>
1 parent de153b6 commit 14792cf

File tree

1 file changed

+145
-0
lines changed
  • docs/docs/reference/release-notes/v4.21

1 file changed

+145
-0
lines changed

‎docs/docs/reference/release-notes/v4.21/index.md

+145
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,145 @@
1+
---
2+
date: "2022-08-16"
3+
version: "4.21.0"
4+
title: "v4.21 Release Notes"
5+
---
6+
7+
Welcome to `[email protected]` release (August 2022 #2)
8+
9+
Key highlights of this release:
10+
11+
- [`gatsby-plugin-mdx` v4](#gatsby-plugin-mdx-v4)
12+
- [Open RFCs](#open-rfcs)
13+
14+
Also check out [notable bugfixes](#notable-bugfixes--improvements).
15+
16+
**Bleeding Edge:** Want to try new features as soon as possible? Install `gatsby@next` and let us know if you have any [issues](https://github.com/gatsbyjs/gatsby/issues).
17+
18+
[Previous release notes](/docs/reference/release-notes/v4.20)
19+
20+
[Full changelog][full-changelog]
21+
22+
---
23+
24+
## `gatsby-plugin-mdx` v4
25+
26+
We're excited to announce [`gatsby-plugin-mdx`](/plugins/gatsby-plugin-mdx) v4! 🎉 With the help of our contractor [axe312ger](https://github.com/axe312ger) we have rewritten the plugin from scratch to give you these new features:
27+
28+
- Full compatibility with [MDX 2](https://mdxjs.com/blog/v2/)
29+
- Per-file tree shaking and chunking (No more `app.js` bundle bloat or global scope problems)
30+
- Simplified usage in pages
31+
- Simplified plugin options
32+
- You can configure the underyling [`@mdx-js/mdx` compile](https://mdxjs.com/packages/mdx/#compilefile-options), e.g. to add `remark` or `rehype` plugins
33+
34+
Over the last couple of months we've been hard at work building a new version of `gatsby-plugin-mdx`. The PRs [#35650](https://github.com/gatsbyjs/gatsby/pull/35650) and [#35893](https://github.com/gatsbyjs/gatsby/pull/35893) are the culmination of these efforts.
35+
36+
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](https://www.gatsbyjs.com/contributing)) want to make to `gatsby-plugin-mdx`.
37+
38+
`gatsby-plugin-mdx` v4 is ready for primetime and you can start using it now.
39+
40+
### Getting started
41+
42+
There are multiple ways on how you can get started with `gatsby-plugin-mdx` v4:
43+
44+
- Initialize a new project with `npm init gatsby` and choose the **"Add Markdown and MDX support"** option
45+
- Follow the [Adding MDX pages](/docs/how-to/routing/mdx/) guide
46+
- Follow our [beginner friendly tutorial](/docs/tutorial/) to learn how to create a blog with MDX
47+
- Try out the [using-mdx example](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-mdx)
48+
- Fork this [CodeSandbox](https://codesandbox.io/s/github/gatsbyjs/gatsby/tree/master/examples/using-mdx)
49+
50+
The updated [`gatsby-plugin-mdx` README](/plugins/gatsby-plugin-mdx/) contains detailed instructions on any new options and APIs.
51+
52+
### Migrating from v3 to v4
53+
54+
If you're already using `gatsby-plugin-mdx` v3 and want to migrate, you can follow the [extensive migration guide](/plugins/gatsby-plugin-mdx#migrating-from-v3-to-v4) to benefit from all new features.
55+
56+
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 `timeToRead` or `wordCount`, over the years it has become increasingly hard to fulfill every feature request and behavior that users wanted (e.g. correctly providing `timeToRead`/`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](/plugins/gatsby-plugin-mdx#extending-the-graphql-mdx-nodes) for guidance on how to migrate.
57+
58+
If you have any questions along the way, post them either into the [umbrella discussion](https://github.com/gatsbyjs/gatsby/discussions/25068) or into the [`mdx-v2` channel on Discord](https://gatsby.dev/discord).
59+
60+
The [using-mdx example](https://github.com/gatsbyjs/gatsby/tree/master/examples/using-mdx) also showcases some of the necessary migration steps.
61+
62+
## Open RFCs
63+
64+
### Slices API
65+
66+
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.
67+
68+
To create a slice, simply:
69+
70+
1. Create the slice by adding a `slices/footer.js` file, or using the `createPages` API action:
71+
72+
```js
73+
actions.createSlice({
74+
id: `footer`,
75+
component: require.resolve(`./src/components/footer.js`),
76+
})
77+
```
78+
79+
2. Add a `<Slice />` component on your site, providing an `alias` string prop, where `alias` is either name of the file (in our case, `footer`). Any additional props passed will be handed down to the underlying component.
80+
81+
```jsx
82+
return (
83+
<>
84+
<Header className="my-header" />
85+
{children}
86+
<Slice alias="footer" />
87+
</>
88+
)
89+
```
90+
91+
To read more, head over to [RFC: Slices API](https://github.com/gatsbyjs/gatsby/discussions/36339). We appreciate any feedback there.
92+
93+
### Changes in `sort` and aggregation fields in Gatsby GraphQL Schema
94+
95+
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 (`group`, `min`, `max`, `sum`, `distinct`).
96+
97+
Basic example of proposed change:
98+
99+
Current:
100+
101+
```graphql
102+
{
103+
allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
104+
nodes {
105+
...fields
106+
}
107+
}
108+
}
109+
```
110+
111+
Proposed:
112+
113+
```jsx
114+
{
115+
allMarkdownRemark(sort: { frontmatter: { date: DESC } }) {
116+
nodes {
117+
...fields
118+
}
119+
}
120+
}
121+
```
122+
123+
To read more, head over to [RFC: Change to sort and aggregation fields API](https://github.com/gatsbyjs/gatsby/discussions/36242). We appreciate any feedback there.
124+
125+
## Notable bugfixes & improvements
126+
127+
- `gatsby-plugin-sharp`: `sharp` was updated to `0.30.7` (also in all other related packages). This deprecates the `failOnError` option as it's being replaced by the `failOn` option, via [PR #35539](https://github.com/gatsbyjs/gatsby/pull/35539)
128+
- `gatsby`:
129+
- Fix `e.remove()` is not a function error when using Gatsby Head API, via [PR #36338](https://github.com/gatsbyjs/gatsby/pull/36338)
130+
- Make inline scripts run in develop, via [PR #36372](https://github.com/gatsbyjs/gatsby/pull/36372)
131+
- Make runtime error overlay work in non-v8 browsers, via [PR #36365](https://github.com/gatsbyjs/gatsby/pull/36365)
132+
- `gatsby-source-contentful`: Correctly overwrite field type on Assets, via [PR #36337](https://github.com/gatsbyjs/gatsby/pull/36337)
133+
- `gatsby-plugin-react-helment`: Stop appending empty title tags, via [PR #36303](https://github.com/gatsbyjs/gatsby/pull/36303)
134+
- `gatsby-link`: Correctly export default for CommonJS, via [PR #36312](https://github.com/gatsbyjs/gatsby/pull/36312)
135+
136+
## Contributors
137+
138+
A big **Thank You** to [our community who contributed][full-changelog] to this release 💜
139+
140+
- [Bi11](https://github.com/Bi11): fix(gatsby-plugin-image): Add `outputPixelDensities` to `SHARP_ATTRIBUTES` [PR #36203](https://github.com/gatsbyjs/gatsby/pull/36203)
141+
- [Kornil](https://github.com/Kornil): chore(gatsby): convert babel-loader-helpers to typescript [PR #36237](https://github.com/gatsbyjs/gatsby/pull/36237)
142+
- [Auspicus](https://github.com/Auspicus): chore(docs): Pre-encoded unicode characters can't be used in paths [PR #36325](https://github.com/gatsbyjs/gatsby/pull/36325)
143+
- [axe312ger](https://github.com/axe312ger): BREAKING CHANGE(gatsby-plugin-mdx): MDX v2 [PR #35650](https://github.com/gatsbyjs/gatsby/pull/35650)
144+
145+
[full-changelog]: https://github.com/gatsbyjs/gatsby/compare/[email protected]@4.21.0

0 commit comments

Comments
 (0)