v2.31 Release Notes
email@example.com release (January 2021 #2)
Key highlights of this release:
- Performance improvements
- Support for Gatsby’s fragments in GraphiQL
- Use Fast Refresh by default for React 17
- Important gatsby-plugin-image updates
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.
An improvement to build speed for sites with many (10k+) markdown and images was made in this PR #28891. This change especially benefits very large sites—our 16k page markdown/image benchmark site’s build time dropped 37% and the 128k pages benchmark dropped 84%.
In #28957 an improvement to
gatsby develop was made by not using the
debug config for
bluebird. This can speed your
source nodes, especially for sites with larger numbers of pages.
graphiql package added support for registering fragments and Gatsby now leverages this new feature! You now get auto-completion for image fragments and any fragments that you added yourself inside GraphiQL:
With the PRs #28689 & #28930 merged, Gatsby will now automatically use Fast Refresh if you use React >= 17.0.0 for your site. As you can read in the release notes for 2.28 we’ve added support for Fast Refresh giving you a better (and custom) error overlay, quicker error recovery and in general a better
gatsby develop experience.
Two ESLint rules that will warn you against anti-patterns in your code were added now:
- No anonymous default exports
- Page templates must only export one default export (the page) and
queryas a named export
Please give us your feedback about the Fast Refresh integration in the umbrella issue. Thanks!
This release includes important changes to the API of the beta image plugin as well as some new features and some proper docs. These are breaking changes, but should be the final API used in the stable release.
We’ve listened to lots of feedback, we’ve used the components ourselves, and we’ve performed lots of tests. From that we’ve made a few changes.
- compat component removed: The compat component was a temporary fix to allow people to try out the component without needing to change their data. With the new API changes this was going to be hard to maintain, and the release of the codemod makes it easier to migrate instead. This release removes them entirely, so be aware that if you upgrade you will need to update your resolvers to use the new syntax.
fluidlayout renamed to
fullWidth: We’re renaming the
fullWidth, to better reflect what it’s used for. It was called
fluidbefore to match the equivalent layout in the old
gatsby-imagecomponent. However this was confusing, because for many of the cases where people used
fluidbefore they should be using the new
constrainedlayout. This displays the image at the specified width, but allows it to shrink to fit smaller screens. However
fullWidthimages always expand to the full width of their container, even if that means stretching beyond the maximum size of the source image. The main use for these is hero images and other full-width banners. To make that clearer, we changed the name.
- Don’t use
fullWidthimages: The old
fluidresolver allows you to pass a
maxWidthargument, which we carried-over to the new plugin. Unfortunately it doesn’t do what most people think it does. In fact, it’s quite hard to explain what it does at all! It doesn’t set the actual maximum width of the displayed image: you want constrained for that. It also doesn’t set the maximum size of the generated image! It actually sets the size of the
1xresolution image. The largest image generated would be this value, multiplied by the maximum pixel density! No wonder when we looked at open source projects that use it, almost everyone seems to be misusing the property. Because of this we removed it entirely, along with
maxHeight(also doesn’t do what you’d expect). Its replacement is:
- Use breakpoints for
fluidlayout generated image resolutions that were based on multiples and fractions of the
maxWidth, similar to how they are done for
constrained. This makes sense where they are mostly going to be used for higher-pixel density screens, rather than for displaying the image larger. However for a full width image, the size you want is the width of the screen. We can’t generate images for every size, but we can choose a good selection of sizes to cover everything from phones to large monitors. We have chosen a default set based on our usage research, but you can pass your own breakpoints in if you’d prefer.
width/heightThere was no good reason to have
maxWidth/maxHeight, while fixed took
width/height. We’ve changed it so they both take
aspectRatioprop: We realized that lots of people were using hacks to set the aspect ratio of images, because it was hard to do properly, particularly for
fluidimages. We’ve added a new
aspectRatioprop that forces the image to that aspect ratio, cropping if needed. If you pass it on its own, it will default to using the source image width, and then adjusting the height to the correct aspect ratio. Alternatively you can pass your own width or height and it will set the other dimension. This works in all layout types.
- Remote static images unflagged:
In the previous version you could pass remote URLs to
StaticImage, but only if you passed in an environment variable to enable it. In this release we’ve removed the flag, so try it out! If you use a remote URL it will download that image at build time and then process it in the same way as it would a local one. Bear in mind that because this is done at build time, any updates to the image on the remote server won’t show up until you next build. Make sure your server supports ETag headers (most do), otherwise it will need to download them every time.
object-fitpolyfill: This version includes an automatic polyfill for browsers that don’t support the CSS
object-positionproperties. It is lazy-loaded so has no overhead for browsers that don’t need it.
- New docs are live: Want to know more about the plugin, and dive deeper into the options? There are two new pages in the documentation that are all about this plugin:
This is likely to be the final minor version before the stable release, but please continue to share your feedback. Meanwhile, watch out for @laurieontech sharing the new image experience in Gatsby at Image Ready v2, hosted by Jamstack Toronto, alongside her counterparts from 11ty and NextJS.
- Extract non-CSS-in-JS CSS and add to
<head>when SSRing in develop mode (with
DEV_SSRflag), via #28471
- Show stack trace for non-GraphQL errors, via #28888
- Update vulnerable packages and include React 17 in peerDeps, via #28545
A big Thank You to our community who contributed to this release 💜
- chore(docs): add http to localhost PR #28896
- chore(docs): fix code block language to shell PR #28895
- docs(readme): add file extension, fix code block, fix link, fix code PR #28905
- fix(gatsby-plugin-netlify): fix typo PR #28907
- fix(gatsby-plugin-sass): fix brand name, code block around names PR #28908
- doc(node-creation): fix brand name PR #28912
- chore(docs): plugin contentful - fix brand name, code blocks for names PR #28915
- readme(gatsby-plugin-emotion): fix table PR #28906
- chore(docs): google plugin analytics - upgrade to gtag, fix code PR #28918
- chore(docs): release notes - code fences, code language PR #28936
- chore(docs): typography - brand name PR #28931
- chore(docs): routing - brand name, code language, code block PR #28929