Hi ๐
Welcome to the Gatsby Changelog. This is a prototype created for the GitHub Actions Hackathon 21 by @PaulieScanlon. You can read more about the project on dev.to
April 18 2023
Welcome to gatsby@5.9.0
release (April 2023 #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.
Performance improvements
We have shipped some great performance improvements to gatsby
and gatsby-source-contentful
.
- With PR #37780 we no longer block the event loop during schema inference and allow garbage collection to work better. This dropped the "building schema" step of a large test site by 27%.
- In PR #37782 we've added a new public action called
enableStatefulSourceNodes
. This will stop Gatsby from checking for stale nodes created by the source plugin that called the action. When enabling stateful sourcing plugin authors need to be sure their plugins properly handle deleting nodes when they need to be deleted. Since Gatsby is no longer checking for node staleness, data which should no longer exist could stick around. Be sure to read the opting out of stale node deletion documentation. - Lastly, in PR #37910 the memory usage of
gatsby-source-contentful
was further decreased. This was achieved by further unblocking the event loop through a queue, allowing more garbage collection, and an improved way of storing intermediate information for backreferences.
All in all these improvements enabled a Contentful test site of ours (with 4.9 million nodes) to build with 24GB of RAM (instead of 64GB), 27% decrease in "building schema" step, and around 70% faster data updates.
New "Creating a Source Plugin" tutorial
A new tutorial for Creating a Source Plugin from scratch is available now!
Gatsbyโs data layer is one of the key features and an enabler for composable architectures. One of the key driving forces of Gatsby since its beginning has been its 800+ source plugins. These plugins make it easy to connect and source from every data source you could imagine.
While our documentation always had a guide on how to create a source plugin, the content was dense and at times difficult to follow. It didnโt show how easy it is to create a barebones source plugin and how many additional features you could add. We wanted to make it easier for users and customers alike to create their own source plugins.
Read the launch blog post to learn more.
Notable bugfixes & improvements
- We merged over 60 renovate PRs to update dependencies across various packages. If you're curious about the changes, you can use this GitHub search.
gatsby-plugin-sharp
: Security update. Don't serve static assets through lazy images, via PR #37796. CVE.gatsby
:- Make
___NODE
convention warning less noisy, via PR #37781 - Add new
enableStatefulSourceNodes
action, via PR #37782. Learn more. - Correct argument order for
onPreRouteUpdate
, via PR #30339 - Reduce size of SSR/DSG engine, via PR #37764
- Make
Contributors
A big Thank You to our community who contributed to this release ๐
- StephenCleary: fix(gatsby): Fix argument order for
onPreRouteUpdate
PR #30339 - Talaxy009: fix(gatsby): Validate sub plugins options PR #37804
- axe312ger: fix(gatsby): move typing for
enableStatefulSourceNodes
intoActions
PR #37933 - benomatis
- geocine: chore(gatsby-plugin-feed): Update README with clearer instructions PR #37930
- jgjgill: chore(gatsby-remark-autolink-headers): Fix typo in README PR #37812
- rogermparent: fix(gatsby-plugin-page-creator): Find nested files for knownCollections PR #37762
- tmastrom: chore(docs): update broken relay compiler link PR #37813
March 21 2023
Welcome to gatsby@5.8.0
release (March 2023 #1)
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.
Notable bugfixes & improvements
gatsby
:gatsby-plugin-page-creator
: Correctly recreate deleted pages duringgatsby develop
, via PR #37745gatsby-plugin-mdx
: Account for links and inline code in table of contents, via PR #37789gatsby-source-wordpress
: Add compatibility withWPGraphQL
version1.14.0
, via PR #37749
Contributors
A big Thank You to our community who contributed to this release ๐
- MarcusCole518: chore(docs): fix dead link on gatsby-cli doc PR #37675
- Saideepak01: feat(gatsby-source-shopify): Add
apiVersion
option PR #37605 - cadamini: chore(docs): Improve "Choosing a CMS" article structure PR #37741
- ch264: chore(docs): Update "Adding search" PR #37703
- chadwcarlson: chore(docs): Update "Building a theme" tutorial PR #37728
- grgcnnr: chore(docs): Update
path.resolve
example to include leading./
PR #37685 - jancama2: fix(gatsby): Use optional chaining in
onHeadRendered
PR #37669 - oskari: chore(gatsby): Remove obsolete
st
package PR #37726 - rogermparent: fix(gatsby-plugin-page-creator): Track correct
knownPagePaths
PR #37745 - xSyki: fix(gatsby): Change backdrop position to
fixed
PR #37698 - yunsuklee: fix(gatsby-plugin-mdx): Account for links/inline code in ToC PR #37739
February 21 2023
Welcome to gatsby@5.7.0
release (February 2023 #2)
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.
Notable bugfixes & improvements
gatsby
: Improve memory usage ingatsby develop
command, via PR #37619gatsby-source-contentful
: Fix engine validation, via PR #37660
Contributors
A big Thank You to our community who contributed to this release ๐
- MarcusCole518: chore(docs): update cloud docs PR #37652
- adnjoo: chore(docs): Update MDX layout template instructions PR #37615
- gh640: chore(docs): Fix typo in Head API reference PR #37630
- leerob: chore(docs): Update Vercel hosting information PR #37551
- marvinjude: chore(docs): Docs for
wrapRootElement
+Head
PR #37519
February 07 2023
Welcome to gatsby@5.6.0
release (February 2023 #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.
Gatsby is joining Netlify
In case you have missed the news, Gatsby is joining Netlify ๐
Gatsby as a framework will continue to evolve and grow. Weโve always shared with Netlify a mutual commitment to open-source and have never been more excited about Gatsbyโs future. Many of Gatsbyโs core contributors will join Netlify and continue to maintain the Gatsby framework.
Be sure to join our Discord, follow Gatsby and Netlify on Twitter or continue to read these release notes to know when we share our plans for the future.
wrapRootElement
Head API supports context providers from Head
now has access to React context provided by wrapRootElement
API. Example setup:
import * as React from "react";
import { AppProviders } from "./src/components/app-providers";
export const wrapRootElement = ({ element }) => (
<AppProviders>{element}</AppProviders>
);
import React from "react";
import { useStaticQuery, graphql } from "gatsby";
const SiteMetadataContext = React.createContext();
export const AppProviders = ({ children }) => {
const data = useStaticQuery(graphql`
{
site {
siteMetadata {
title
}
}
}
`);
return (
<SiteMetadataContext.Provider value={data.site.siteMetadata}>
{children}
</SiteMetadataContext.Provider>
);
};
export function useSiteMetadataContext() {
return React.useContext(SiteMetadataContext);
}
import * as React from "react";
// highlight-next-line
import { useSiteMetadataContext } from "../components/app-providers";
export function Head() {
// highlight-next-line
const { title } = useSiteMetadataContext();
return (
<>
<title>{title}</title>
</>
);
}
export default function DefaultPageTemplate() {
// template details.
}
If wrapRootElement
API is used to wrap templates with UI components those will be skipped and you will see warnings in browser console about invalid head elements. In this case it's recommended to move UI elements to wrapPageElement
API.
Notable bugfixes & improvements
gatsby
:gatsby-plugin-utils
: Export twoIRemoteFile
utility types, via PR #37532
Contributors
A big Thank You to our community who contributed to this release ๐
- IvanKiral: chore(docs): Update "Sourcing from Kontent.ai" PR #37484
- Khaledgarbaya: chore(docs): Update gatsby-slice.md to reference styled components non-support PR #37525
- MEddarhri: chore(docs): Fix typo in adding common features PR #37611
- OddDev: chore: Update using-remark example PR #37546
- marvinjude
- feat(gatsby): Safely wrap
Head
withwrapRootElement
PR #37439
- feat(gatsby): Safely wrap
- panzacoder: fix(gatsby): Render to pipeable stream in dev SSR PR #37534
- robations: chore(gatsby-source-wordpress): Fix apostrophe typos PR #37486
- tqureshi-uog: fix(gatsby-source-drupal): Make Image CDN error only
panicOnBuild
PR #37601
January 24 2023
Welcome to gatsby@5.5.0
release (January 2023 #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.
gatsby-source-filesytem
Faster Hashing for GitHub user FraserThompson put up a feature request to optionally disable MD5 hashing inside gatsby-source-filesystem
. Their site has around ~1000 MP3s (up to 120MB) and 16000 JPGs (around 2-3 MB), so gatsby-source-fileystem
has to ingest a lot of data! While reading the data an MD5 hash is generated for each file to attach the contentDigest
to the File
node. Or in other words: This MD5 hash is used to determine if a file has changed and is used in Gatsby's caching system.
We'd recommend reading the discussion inside the feature request as it shows a great case of collaboration and how productive open source work can look like. After exploring and debating about the best approach, the PR #37464 was put up. Here's what has changed:
-
gatsby-source-filesystem
now uses hash-wasm to calculate the MD5 hash for each file -
Cache the
inode
andmtime
file stats and only re-generate the MD5 hash if those changed -
Introduce a new
fastHash
option to skip the MD5 hashing altogether. Instead, use theinode
andmtime
. On a modern OS this can be considered a robust solution to determine if a file has changed, however on older systems it can be unreliable. Therefore it's not enabled by default.module.exports = { plugins: [ { resolve: `gatsby-source-filesystem`, options: { name: `data`, path: `${__dirname}/src/data/`, // highlight-next-line fastHash: true, }, }, ], }
FraserThompson also put these changes to the test with this test environment: 4774 files, 3363 images (1-3MB each), 284 MP3s (20-120MB each).
And here are the performance numbers ๐
Configuration | source and transform nodes (cold) |
---|---|
gatsby-source-filesytem@5.4.0 |
781 seconds |
gatsby-source-filesytem@5.5.0 |
494 seconds (36% decrease) |
gatsby-source-filesytem@5.5.0 with fastHash |
10 seconds (98% decrease) |
As you can see, already the enhancements achieved through hash-wasm
are great! However, take these numbers with a grain of salt as your site will be different from the test environment. You'll see bigger absolute improvements with a lot of big files.
Last but not least, it's important to note that the upgrades were made to the createFileNode
function. So if you're using this utility in your site/plugin, you can also benefit from this.
<html>
and <body>
attributes
Setting You can now set the attributes of the <html>
and <body>
tags using the Head API. Gatsby will automatically incorporate these attributes into the page, with any attributes specified in the Head API taking precedence over those set through Gatsby Server Rendering APIs.
export function Head() {
return (
<>
<html lang="en">
<body className="my-body-class">
<title>Hello World</title>
</>
)
}
Notable bugfixes & improvements
gatsby
:- pass
serverData
into Gatsby Head, via PR #37500 - fix regression with
file-loader
imports whenpathPrefix
and/orassetPrefix
is used, via PR #37423 - fix
pluginOptionsSchema
not being called for local plugins withgatsby-node.ts
, via PR #37443 - support updated
sort
argument syntax innodeModel.findAll
function, via PR #37477
- pass
gatsby-source-contentful
:- fix back reference fields disapearing after some content updates, via PR #37442
Contributors
A big Thank You to our community who contributed to this release ๐
- FraserThompson: feat(gatsby-source-filesystem): Only generate hashes when a file has changed, and add an option for skipping hashing PR #37464
- palmiak: chore(docs): Adds Kinsta Application hosting to other services PR #37476
- beadlespouse: fix(gatsby-source-shopify): Use
id
as cacheKey for base64 image PR #37397 - chrissantamaria: fix(gatsby): Multi-environment browserslist configs PR #35081
- labifrancis: chore(docs): Update "Minimal Reproduction" instructions PR #37231
- markacola: fix(gatsby): Update
loader.loadPage
to return a Promise on error PR #37337 - chawes13: docs: fix v5 release notes slice example PR #37465
- sapiensfio: fix(gatsby-react-router-scroll): fix issues with anchor links PR #37498
- jonrutter: chore(docs): Fix
ts-jest
import statement in Unit Testing Guide PR #37411
January 10 2023
Welcome to gatsby@5.4.0
release (January 2023 #1)
The whole team took time off for a much deserved winter break and we hope you had relaxing holidays, too! Before the break we spent time doing maintenance work such as updating internal dependencies or fixing some smaller bugs here and there. In case you missed it, we shipped ES Modules (ESM) in Gatsby files in the last release.
So check out the notable bugfixes section to learn more.
Bleeding Edge: Want to try new features as soon as possible? Install gatsby@next
and let us know if you have any issues.
Notable bugfixes & improvements
- We merged over 40 renovate PRs to update dependencies across various packages. If you're curious about the changes, you can use this GitHub search.
gatsby
:- Bump
socket.io
to address CVE-2022-41940, via PR #37272 - Bump
yaml-loader
from0.6.0
to0.8.0
to address security warning, via PR #37401 - Improve
SlicePlaceholderProps
TypeScript type, via PR #37409 - Allow
gatsby-node
in folder names (e.g.<root>/gatsby-node/on-pre-init.ts
), via PR #36712 - Restore asset, path prefix for file-loader handled files (fixing a regression in
gatsby@5.3.3
), via PR #37429
- Bump
Contributors
A big Thank You to our community who contributed to this release ๐
- Simply007: chore(gatsby): Adjust information about
trailingSlash
forcreateRedirect
PR #37259 - bicstone: chore(docs): fix typo in reference guide PR #37347
- demondragong: chore(gatsby-plugin-google-analytics): Fix typo in README PR #37276
- markacola: chore: Update
.gitpod
to use correct Node version PR #37336 - openscript: docs(how-to): remove unecessary decomposition PR #37341
- trentschnee: chore(docs): Update Storybook instructions PR #37321
- xavivars: fix(gatsby-source-contentful): Add contentTypeFilter to Joi schema PR #37403
December 13 2022
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:
// The latest version of "slugify" is ESM-only
import slugify from "@sindresorhus/slugify"
const title = `Gatsby Default Starter`
const config = {
siteMetadata: {
title,
slugifiedTitle: slugify(title),
},
plugins: [],
}
export default config
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:
ERROR #85928
An error occurred during parallel query running.
Error: Worker exited before finishing task
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
November 25 2022
Welcome to gatsby@5.2.0
release (November 2022 #3)
This is an out of band release due to the removal of the Potrace library in Gatsby. We'll continue with our biweekly schedule as normal.
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.
Removal of Potrace
Due to licensing requirements, we are removing the Potrace library usage from Gatsby. Potrace is used in Gatsby's image transformations, specifically for creating a SVG placeholder. For example, in gatsby-plugin-image
you were able to use it with tracedSvg
and TRACED_SVG
respectively.
These are the affected libraries/plugins:
- gatsby-plugin-sharp
- gatsby-transformer-sharp
- gatsby-plugin-utils
- gatsby-remark-images
There will be no API-breaking changes, your builds will continue to work. However, whenever you use the tracedSvg
feature Gatsby automatically falls back to the default placeholder style now. In most instances this is DOMINANT_COLOR
. You'll see a detailed warning message in your CLI about this, too.
If youโd like to know more or have any questions, head over to our Github Discussion.
Notable bugfixes & improvements
gatsby-source-wordpress
:MediaItem.excludeFieldNames
/ auto exclude interface types that have no fields, via PR #37062gatsby-source-drupal
: ProvideproxyUrl
in addition to baseUrl to allow using CDN, API gateway, etc., via PR #36819gatsby-cli
: We changed our error messages a little bit. You should see a more detailedtype
beside the error ID nowgatsby
: Sanitizelength
on objects, via PR #34253
Contributors
A big Thank You to our community who contributed to this release ๐
- MichaelDeBoey: tests: Update pluginOptionsSchema tests PR #27904
- sampittko: docs: add onCreateNode params and example PR #27503
- benomatis: fix(gatsby-plugin-google-gtag): correct script to match google's current PR #36993
- vse-volod: chore(docs): Update "Working with Images in Markdown" PR #34621
- Nischal2015: chore(docs): add missing argument PR #37063
- aaronadamsCA: chore(gatsby-plugin-image): Add
peerDependenciesMeta
PR #35146 - hexpunk: fix(gatsby-remark-graphviz) Fix attribute application PR #36391
- PeterDekkers: chore(gatsby-plugin-sitemap): Clarify filterPages' reliance on the excludes array PR #37065
- aryans1319: chore(docs): Example
@link
directive with array (by elemMatch) PR #36632 - Vacilando: feat(gatsby-source-drupal): Provide proxyUrl in addition to baseUrl to allow using CDN, API gateway, etc. PR #36819
- iChenLei: fix(gatsby): Sanitize
length
on objects PR #34253 - DarthFloopy: chore(gatsby-source-contentful): Add note about RichTextField to README PR #36102
November 22 2022
Welcome to gatsby@5.1.0
release (November 2022 #2)
This is the first minor release after the recent major release of Gatsby 5! We are focused on your feedback and implementing fixes as needed.
If you haven't migrated yet, please refer to the migration guide. We've done our best to make the transition smooth!
Some brief notes about what Gatsby 5 brings to the table:
- Slices API unlocks up to 90% reduction in build duration for content changes in highly shared components
- Partial Hydration allows you to ship only the necessary JavaScript to the browser
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.
Notable bugfixes & improvements
gatsby
:gatsby-core-utils
:- Fix handling of non-ASCII characters in remote file download, via PR #35637
gatsby-plugin-google-gtag
:- Add
delayOnRouteUpdate
option, via PR #37017
- Add
gatsby-graphiql-explorer
- Fix refresh endpoint env var logic in GraphiQL v2 explorer, via PR #37032
gatsby-source-wordpress
:- Fix store not containing auth credentials, via PR #37006
gatsby-transformer-csv
:- Fix high memory consumption when loading large CSV file, via PR #36610
Contributors
A big Thank You to our community who contributed to this release ๐
- GhassenRjab: chore(gatsby-plugin-google-analytics): Update
minimatch
PR #37029 - one-ness: chore(docs): Add IE 11 note to v2 to v3 migration guide PR #37022
- bicstone: chore(docs): Fix broken link in v5 Release Notes PR #37000
- cometkim: fix(gatsby-core-utils): decode uri-encode filename for remote file PR #35637
- shogohida: chore(docs): Add
--
to quick start flags PR #37041 - ascott97: fix(gatsby-transformer-csv): Fix high memory consumption PR #36610
- augustweinbren: chore(docs): Clarify language in v4 to v5 migration guide PR #37007
- benomatis: chore(docs): Google Analytics: use gtag.js plugin PR #36984
- btzs: chore(docs): Add import to Seo component in part 6 PR #36990
- Nischal2015
- Simon-Tang: feat(gatsby-plugin-google-gtag): Add
delayOnRouteUpdate
option PR #37017 - axe312ger: build: include e2e tests in renovate config PR #37005
November 08 2022
Welcome to gatsby@5.0.0
release (November 2022 #1).
Gatsby 5 introduces the Slices API and Partial Hydration (Beta). Slices unlock up to 90% reduction in build duration for content changes in highly shared components, Partial Hydration allows you to ship only the necessary JavaScript to the browser. Weโve tried to make migration smooth. Please refer to the migration guide and let us know if you encounter any issues when migrating.
Key highlights of this release:
- Slice API - Only re-build individual slices of your page
- Partial Hydration (Beta) - Improve frontend performance by shipping less JavaScript
- GraphiQL v2 - An all new UI with features like dark mode, tabs, and persisted state
Major dependency updates:
Bleeding Edge: Want to try new features as soon as possible? Install gatsby@next
and let us know
if you have any issues.
Breaking Changes
If you're looking for an overview of all breaking changes and how to migrate, please see the migrating from v4 to v5 guide.
If you're curious about our release schedules and which versions are officially supported, head to the Gatsby Framework Version Support document. As of Gatsby 5 we're no longer supporting Gatsby 2 and Gatsby 3.
Overview Video
Prefer video over text? No problem! Learn more about all the new features in the video below:
Slice API
The Slice API allows you to define highly-shared components in your site, which will then inform Gatsby to build those shared components only once. After the files are built, Gatsby will then stitch the resulting markup and JavaScript to the pages that include that shared component. This means that changes to highly-shared components (such as headers, footers, and common layouts) no longer require a rebuild of all pages that use that shared component.
The Slice API introduces two critical pieces, the createSlice
action from the createPages
API and the <Slice>
placeholder. To create a Slice, you must first call createSlice
within gatsby-node
:
exports.createPages = async ({ actions }) => {
actions.createSlice({
id: `header`,
component: require.resolve(`./src/components/header.js`),
})
}
Then, use the <Slice>
placeholder where the <Header>
component was previously:
import { Slice } from "gatsby"
import { Footer } from "./footer"
export const DefaultLayout = ({ children, headerClassName }) => {
return (
<div className={styles.defaultLayout} />
<Slice alias="header" className={headerClassName} />
{children}
<Footer />
</div>
)
}
Here's an overview of how it works:
Now, when a code update or data update is made for the <Header>
component, only the HTML for the Slice will be updated, and later stitched into the pre-existing HTML for the pages that use it.
We want to make sure the Slice API is worthwhile for all Gatsby sites, so the implementation is built into Gatsby's open source product. To validate the improvements of the Slice API, we created a 10,000 page Contentful site with a shared header. We then benchmarked two types of changes, code updates to the git repository and data updates to Contentful. Here are the results:
Code Update | Data Update | |
---|---|---|
No Slices (Self-Hosted) | 1253s | 1276s |
With Slices (Self-Hosted) | 1011s | 958s |
No Slices on Gatsby Cloud | 155s | 22s |
With Slices on Gatsby Cloud | 129s | 15s |
With Slices on Gatsby Cloud + Optimizations | 34s | 10s |
Across the board we can see at least a 20% decrease in build time when using Slices. When using the Slices Optimization on Gatsby Cloud, build time decreases by 78% for code updates compared to No Slices on Gatsby Cloud. As the site grows, the benefit of the Gatsby Slice API will only increase.
For more information, read the Using Slices How-To Guide or the Slice API Reference Documentation.
If you have any questions about the Slice API, you can comment on the Gatsby 5 Umbrella Discussion or gatsby-5
Discord channel.
Partial Hydration (Beta)
Partial Hydration enables you to selectively add interactivity to your otherwise completly static app. This results in improved frontend performance while keeping the benefits of client-side apps. Gatsby uses React server components to achieve this.
Hydration (or often referred to as re-hydration) is the process of using client-side JavaScript to add application state and interactivity to server-rendered HTML. Since the initial release of Gatsby, apps built with Gatsby were always fully hydrated on the client. With Gatsby 5 you now can also use Partial Hydration inside Gatsby. Here's a visualization showing how Full Hydration and Partial Hydration differ conceptually:
Partial Hydration is in Beta and not enabled by default. You have to opt-in to try it out. The reason for this is that React server components are still quite new (the ecosystem as a whole hasn't caught up, e.g. CSS-in-JS libraries) and you are currently required to use an experimental version of react
/react-dom
. Therefore we don't recommend using Partial Hydration in production just yet. Once things have stabilized we'll announce the general availablity release of Partial Hydration and adjust the documentation.
Read the Partial Hydration How-To Guide for detailed instructions. We also recommend reading the Partial Hydration Conceptual Guide to understand why Gatsby chose React server components and how Partial Hydration works on a high-level.
As a quick start, here's how you can use Partial Hydration in Gatsby 5 today:
- Install experimental version of
react
andreact-dom
:npm install --save-exact react@experimental react-dom@experimental
- Enable the feature flag inside
gatsby-config
:module.exports = { flags: { PARTIAL_HYDRATION: true } }
- Add the
"use client"
directive to any component that needs to be a client component. You can see an example in the gatsby-partial-hydration-starter
If you have any questions about Partial Hydration, you can comment on the RFC: Partial Hydration or partial-hydration
Discord channel.
GraphiQL v2
GraphiQL is Gatsby's integrated GraphQL development environment (IDE). Itโs a powerful (and all-around awesome) tool youโll use often while building Gatsby websites. We've updated GraphiQL from v1 to v2 to bring you these cool new features:
- Dark Mode
- Tabs
- Persisted State/Tabs using
localStorage
- Better documentation explorer through search and markdown support
- Plugin ecosystem
Want to learn more? Head to the Introducing GraphiQL docs.
The plugin ecosystem also will allow us to more easily add functionality to GraphiQL in the future. In preparation for this release we've created @graphiql/plugin-code-exporter
for example.
Many thanks go to acao and the Stellate team for shipping GraphiQL v2! More props in this tweet thread.
Node 18
We are dropping support for Node 14 and 16 as our currently supported Node 14 version will reach EOL during the Gatsby 5 lifecycle. Since the timing of the "Active LTS" status of Node 18 is nearly the same as Gatsby 5 we're jumping directly to Node 18. See the main changes in Node 18 release notes.
Check Nodeโs releases document for version statuses.
React 18
We are dropping official support for React 16 and 17. The new minimal required version is React 18. This is a requirement for the Partial Hydration feature.
Performance improvements
-
The GraphQL schema: Changes to sort and aggregation fields change enables lower resource usage (significantly reduced memory usage) and faster โBuilding schemaโ step.
-
The Non-ESM browsers are not polyfilled by default change speeds up the "Building production JavaScript and CSS bundles" step dramatically since webpack doesn't have to polyfill a lot of code anymore.
Highlights from v4
While we have your attention we want to showcase all the awesome features we shipped during the Gatsby 4 lifecycle. Give them a try!
- Script Component: Gatsbyโs Script component offers a convenient way to declare different loading strategies, and a default loading strategy that gives Gatsby users strong performance out of the box.
- Head API: Gatsby includes a built-in
Head
export that allows you to add elements to the document head of your pages. Compared to react-helmet or other similar solutions, Gatsby Head is easier to use, more performant, has a smaller bundle size, and supports the latest React features. - MDX v2:
gatsby-plugin-mdx
was updated to support MDX v2. All of the speed, bundle size, and syntax improvements for MDX v2 can be taken advantage of in Gatsby. - TypeScript & GraphQL Typegen: You can write your
gatsby-config
andgatsby-node
in TypeScript now. Together with GraphQL Typegen which automatically generates TypeScript types for your GraphQL queries you can author all your Gatsby code in TypeScript. - Image CDN: Images are typically the largest files on a site and delay page load significantly while they are pulled over the network. With Image CDN, image processing can be done outside of your builds so you can ship your content even faster.
Contributors
A big Thank You to our community who contributed to this release ๐
- mattmuroya: chore(gatsby-source-contentful): Correct image embed code sample PR #36670
- yasell: fix(gatsby): remove unused console.log PR #36713
- ashhitch: chore(docs): Update storybook main.js examples to be consistant PR #36702
- joshterrill: chore: Update old placehold.it URLs PR #36731
- Toxillo: chore(docs): Update tutorial part 5 with a better fitting screenshot PR #36741
- ShaunDychko: chore(gatsby-plugin-sitemap): Document
excludes
glob matching PR #36690 - Lightwight: fix(gatsby-page-utils): path creation on windows filesystem PR #36766
- kentmz: chore(docs): added Dialoguewise to headless cms list PR #36651
- muescha
- brysongilbert: chore(gatsby-core-utils): Update README with correct cpuCoreCount args PR #36838
- mac2000: feat(gatsby-remark-embed-snippet): added csproj to language map so it will be recognized as xml PR #36919
- BreGoNunez: chore(docs): Add clarification for Pro Tip on Part 4 of tutorial PR #36918
- roryclaasen: chore(gatsby-link): Correct type export PR #36968
September 27 2022
Welcome to gatsby@4.24.0
release (September 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.
Gatsby 5 Alpha
You probably noticed that in the last couple of releases we mostly focused on bug fixes, smaller improvements, and pointing to our RFCs rather than shipping big new features. There's a simple reason for that: We're working hard on Gatsby 5! And we're super excited to share that you can try the Gatsby 5 Alpha today ๐
For the Alpha the big new feature you'll be able to test out is Partial Hydration. With Partial Hydration you gain the ability to mark specific parts of your site/application as โinteractiveโ, while the rest of your site is static by default. This will result in shipping less JavaScript to your users and improved Lighthouse scores. For a quick preview of these great features, you can watch the showcase on YouTube
Please take part in the Gatsby 5 Umbrella Discussion, try it out, and let us know what works and doesn't work. If Discord is more your jam, you can also join the gatsby-5
Discord channel.
Updating File System Routes on data changes
When creating routes using the File System Route API they were correctly created on initial run with gatsby develop
. However, on subsequent changes to the underlying sourced data (e.g. Markdown files have their slug
field changed) those changes weren't reflected in the routes. A restart of gatsby develop
was necessary.
In PR #36623 we fixed this behavior and any node changes (either by changing local files or through webhook updates) will be reflected in your routes.
Notable bugfixes & improvements
gatsby-plugin-mdx
: Fix theReact is not defined
error, via PR #36595gatsby-remark-copy-linked-files
: AddabsolutePath
todir
function, via PR #36213gatsby
&gatsby-plugin-mdx
: Fix "Multiple root query" error when using a name for your MDX template, via PR #36525gatsby-parcel-config
: The underlying Parcel config (used for compilinggatsby-config.ts
andgatsby-node.ts
files) was changed to only handle JavaScript/TypeScript. This aligns the behavior with current Node.js capabilities ofgatsby-config.js
/gatsby-node.js
(e.g. you can't just import YAML files), via PR #36583gatsby
: Source maps are available forgatsby-config.ts
/gatsby-node.ts
files, via PR #36450
Contributors
A big Thank You to our community who contributed to this release ๐
- kxxt: fix(gatsby-core-utils): Use
grep -E
instead ofegrep
PR #36648 - Osiris8: chore(docs): Fix
Seo
imports in tutorial PR #36587 - evanwinter: chore(docs): Update "Layout components" related links PR #36572
- chrisj-skinner: chore(docs): Update storybook main.js docs PR #36627
- alesma: chore(gatsby-plugin-sitemap): Add info about
page
object to README PR #36582 - benomatis: fix(docs): tiny grammatical correction PR #36630
- Auspicus: feat(gatsby): Enable source maps when compiling Gatsby files in development PR #36450
- kvnang: chore(docs): Fix Partytown forward events examples PR #36613
- karlhorky: feat(gatsby-remark-copy-linked-files): Add
absolutePath
to dir function PR #36213 - openscript: chore(gatsby): Add
loadPageDataSync
property toonRenderBody
TS type PR #36492 - ebuildy: fix(gatsby-parcel-config): Adjust dependencies PR #36583
- AndrPetrov: fix(gatsby-link): Correct handling of trailingSlash & pathPrefix PR #36542
- treboryx: fix(gatsby): Pass hostname to detect-port PR #36496
- colbywhite: chore(docs): Swap mobile url for regular url PR #36618
- MarcusCole518: chore(docs): Add "Payments Managing" & "Deploying to Fastly" PR #36546
- SilencerWeb: chore(gatsby-source-wordpress): Fix license link PR #36621
September 13 2022
Welcome to gatsby@4.23.0
release (September 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.
Open RFCs
Slices API
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.js
file, or using thecreatePages
API action:actions.createSlice({ id: `footer`, component: require.resolve(`./src/components/footer.js`), })
-
Add a
<Slice />
component on your site, providing analias
string prop, wherealias
is either name of the file (in our case,footer
). Any additional props passed will be handed down to the underlying component.return ( <> <Header className="my-header" /> {children} <Slice alias="footer" /> </> )
To read more, head over to RFC: Slices API. We appreciate any feedback there.
sort
and aggregation fields in Gatsby GraphQL Schema
Changes in 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
).
Basic example of proposed change:
Current:
{
allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
nodes {
...fields
}
}
}
Proposed:
{
allMarkdownRemark(sort: { frontmatter: { date: DESC } }) {
nodes {
...fields
}
}
}
To read more, head over to RFC: Change to sort and aggregation fields API. We appreciate any feedback there.
Notable bugfixes & improvements
gatsby
:gatsby-source-wordpress
:gatsby-plugin-sharp
:- Upgrade
svgo
dependency to fix vulnerability, via #36445
- Upgrade
gatsby-dev-cli
:- Make package work with npm 8.5, via #36498
create-gatsby
:- Ensure plugins are installed correctly, via #36566
Contributors
A big Thank You to our community who contributed to this release ๐
- nnmax
- CobyPear: chore(gatsby): Update
react-refresh
to^0.14.0
PR #36553 - IObert: chore(docs): Fix path to components in part 6 PR #36463
- subhoghoshX: fix(docs): fix creating routes code snippet PR #36479
- dreibona: chore(docs): Fix
gatsby-source-filesystem
typo PR #36471 - MarcusCole518
August 30 2022
Welcome to gatsby@4.22.0
release (August 2022 #3)
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.
Open RFCs
Slices API
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.js
file, or using thecreatePages
API action:actions.createSlice({ id: `footer`, component: require.resolve(`./src/components/footer.js`), })
-
Add a
<Slice />
component on your site, providing analias
string prop, wherealias
is either name of the file (in our case,footer
). Any additional props passed will be handed down to the underlying component.return ( <> <Header className="my-header" /> {children} <Slice alias="footer" /> </> )
To read more, head over to RFC: Slices API. We appreciate any feedback there.
sort
and aggregation fields in Gatsby GraphQL Schema
Changes in 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
).
Basic example of proposed change:
Current:
{
allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
nodes {
...fields
}
}
}
Proposed:
{
allMarkdownRemark(sort: { frontmatter: { date: DESC } }) {
nodes {
...fields
}
}
}
To read more, head over to RFC: Change to sort and aggregation fields API. We appreciate any feedback there.
Notable bugfixes, improvements, & changes
gatsby
gatsby-cli
: Preserve verbosity in spawn child processes, via PR #36399gatsby-source-graphql
: we have "soft deprecated" this package in favor of other, CMS-specific source plugins- Note: You can continue to use this plugin for small sites or proof-of-concepts, but for larger sites backed by one or multiple CMSs we recommend using the official source plugin
- Read more on the README about the decision as well as the pull request
gatsby-plugin-mdx
gatsby-plugin-image
: Fix bug that preventsonLoad
being called on first load, via PR #36375
Contributors
A big Thank You to our community who contributed to this release ๐
- alexlouden: fix(gatsby-plugin-react-helmet): Typo in
onPreInit
warning PR #36419 - axe312ger: chore(docs): MDX v2 PR #35893
- mashehu: chore(docs): fix incorrect closing tag in tutorial PR #36459
- endymion1818: feat(docs): add webiny to headless cms list PR #36388
- that1matt: fix(gatsby-source-graphql): add dataLoaderOptions validation to gatsby-source-graphql PR #36112
- taiga39: chore(docs): Fix some typos PR #36431
- TalAter: chore(docs): Update plugin count in part 3 of the tutorial PR #36455
- Kornil
- ChefYeum: chore(docs): Fix page link to page 6 of remark tutorial PR #36437
August 16 2022
Welcome to gatsby@4.21.0
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.
gatsby-plugin-mdx
v4
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.js
bundle bloat or global scope problems) - Simplified usage in pages
- Simplified plugin options
- You can configure the underyling
@mdx-js/mdx
compile, e.g. to addremark
orrehype
plugins
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
.
gatsby-plugin-mdx
v4 is ready for primetime and you can start using it now.
Getting started
There are multiple ways on how you can get started with gatsby-plugin-mdx
v4:
- Initialize a new project with
npm init gatsby
and 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
The updated 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 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 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.
Open RFCs
Slices API
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.js
file, or using thecreatePages
API action:actions.createSlice({ id: `footer`, component: require.resolve(`./src/components/footer.js`), })
-
Add a
<Slice />
component on your site, providing analias
string prop, wherealias
is either name of the file (in our case,footer
). Any additional props passed will be handed down to the underlying component.return ( <> <Header className="my-header" /> {children} <Slice alias="footer" /> </> )
To read more, head over to RFC: Slices API. We appreciate any feedback there.
sort
and aggregation fields in Gatsby GraphQL Schema
Changes in 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
).
Basic example of proposed change:
Current:
{
allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
nodes {
...fields
}
}
}
Proposed:
{
allMarkdownRemark(sort: { frontmatter: { date: DESC } }) {
nodes {
...fields
}
}
}
To read more, head over to RFC: Change to sort and aggregation fields API. We appreciate any feedback there.
Notable bugfixes & improvements
gatsby-plugin-sharp
:sharp
was updated to0.30.7
(also in all other related packages). This deprecates thefailOnError
option as it's being replaced by thefailOn
option, via PR #35539gatsby
:gatsby-source-contentful
: Correctly overwrite field type on Assets, via PR #36337gatsby-plugin-react-helment
: Stop appending empty title tags, via PR #36303gatsby-link
: Correctly export default for CommonJS, via PR #36312
Contributors
A big Thank You to our community who contributed to this release ๐
- Bi11: fix(gatsby-plugin-image): Add
outputPixelDensities
toSHARP_ATTRIBUTES
PR #36203 - 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
August 02 2022
Welcome to gatsby@4.20.0
release (August 2022 #1)
Key highlights of this release:
- RFC for changes in
sort
and aggregation fields in Gatsby GraphQL Schema - Release Candidate for gatsby-plugin-mdx v4 - Support for MDX v2 and more!
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.
sort
and aggregation fields in Gatsby GraphQL Schema
RFC for changes in 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
).
Basic example of proposed change:
Current:
{
allMarkdownRemark(sort: { fields: [frontmatter___date], order: DESC }) {
nodes {
...fields
}
}
}
Proposed:
{
allMarkdownRemark(sort: { frontmatter: { date: DESC } }) {
nodes {
...fields
}
}
}
To read more, head over to RFC: Change to sort and aggregation fields API. We appreciate any feedback there.
gatsby-plugin-mdx
v4
Release Candidate for In case you missed it: We're working on a new major version of gatsby-plugin-mdx
to support MDX v2, improve build & frontend performance, and simplify the API.
You can now try out a release candidate version, head to the MDX v2 RFC to learn more.
Notable bugfixes & improvements
gatsby
- Preserve relative order of
<head>
meta tags, via PR #36158 - Fixed
--host
and--https
options forgatsby develop
, via PR #36186 and PR #36248 - Improved ContentSync mapping to also check Static Queries and type connections, via PR #36132
- Allow
export { default }
syntax to export page template, via PR #29553 - Fixed
pathPrefix
handling for DSG/SSR ingatsby serve
, via PR #36231 - Improved performance of sorting, filtering and aggregation on fields with custom resolvers, via PR #36253
- Preserve relative order of
gatsby-plugin-sass
- Added support for
additionalData
option, via PR #36086
- Added support for
gatsby-plugin-sharp
- Ensure min 1px height for
BLURRED
placeholder, via PR #35914
- Ensure min 1px height for
gatsby-plugin-utils
- fixed
IMAGE_CDN
andFILE_CDN
handling for urls requiring encoding, via PR #36179
- fixed
gatsby-source-wordpress
- Added option to disable automatic use of
gatsby-plugin-catch-link
through settingcatchLinks: false
ingatsby-source-wordpress
plugin options, via PR #36141
- Added option to disable automatic use of
gatsby-source-drupal
- Added support for translated content in Content Sync, via PR #35514
Contributors
A big Thank You to our community who contributed to this release ๐
- bytrangle: chore(docs): Instruct to install v2 of
unist-util-visit
in remark tutorial PR #36221 - laneparton: fix(gatsby-plugin-sass): Add support for additionalData option PR #36086
- edlucas: chore(docs): Clarify note in "local font" how-to PR #36224
- Shubhdeep12: chore(docs): Typo fix in debugging-html-builds PR #36228
- RajputUsman: chore(docs): Update to Basic Hardware and Software Requirements PR #36153
- chrispecoraro: chore(docs): Typo in 4.19 release notes PR #36176
- tordans: chore(docs): Add section about
navigate(-1)
PR #36184 - yanneves: fix(gatsby): Allow
export { default }
named exports in page templates PR #29553 - openscript: chore(docs): Add dependency for TypeScript testing PR #36050
- ThomasVandenhede: fix(gatsby-plugin-sharp): Ensure min 1px height for
BLURRED
placeholder PR #35914 - Hunta88: Grammar typo fixed PR #36219
- billybrown-iii: chore(docs): fix outdated link PR #36145
- dan-mba: chore(docs): Add
react-helmet
note in Gatsby Head reference PR #36216 - Auspicus: fix(gatsby-source-drupal): Add langcode to manifest ID PR #35514
- merceyz: fix: add missing dependencies PR #36230
- axe312ger: chore(gatsby-source-contentful): migrate to latest Contentful SDK PR #35501
July 19 2022
Welcome to gatsby@4.19.0
release (July 2022 #2)
Key highlights of this release:
- Gatsby Head API - Better performance & more future-proof than
react-helmet
- Release Candidate for gatsby-plugin-mdx v4 - Support for MDX v2 and more!
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.
Gatsby Head API
Gatsby now includes a built-in Head
export that allows you to add elements to the document head of your pages.
Compared to react-helmet or other similar solutions, Gatsby Head is easier to use, more performant, has a smaller bundle size, and supports the latest React features. You no longer need a third-party library to handle meta tags in Gatsby. Gatsby Head also automatically places your meta tags into the generated HTML so you also no longer need a Gatsby plugin in your gatsby-config.js
.
import * as React from "react"
const Page = () => <div>Hello World</div>
export default Page
export function Head() {
return (
<title>Hello World</title>
)
}
The Head
function has to return valid JSX which also means that you can use React's composition model and define a reusable React component to more easily handle default values for your pages. You can learn more about this in the Adding an SEO component guide.
One thing to note is that every page that need to add some tags to document head needs to export or re-export a Head function. You may only do a re-export if the new page needs to have same tags as the previous.
One important difference between Gatsby Head API and solutions like react-helmet
is that (at the moment) you lose the ability to define global defaults (e.g. in a layout component) and have them automatically applied everywhere. With Gatsby Head API your pages have to export a Head
function to define meta tags for this specific page. To help with that you can use an SEO component or re-export the Head
function from somewhere else:
import * as React from "react"
const Page = () => <div>Hello World</div>
export default Page
// highlight-next-line
export { Head } from "../another/location"
For full details, see the Gatsby Head API reference guide. To learn how to use Gatsby Head API with TypeScript, head to the TypeScript and Gatsby guide.
This feature followed our RFC process, you can read RFC: Gatsby Head API to understand how the API was created.
gatsby-plugin-mdx
v4
Release Candidate for In case you missed it: We're working on a new major version of gatsby-plugin-mdx
to support MDX v2, improve build & frontend performance, and simplify the API.
You can now try out a release candidate version, head to the MDX v2 RFC to learn more.
Notable bugfixes & improvements
- Publish
gatsby-script
,gatsby-link
, andgatsby-core-utils
both as CJS & ESM, via PR #36012 and PR #36020 gatsby
Contributors
A big Thank You to our community who contributed to this release ๐
- Timxyx: fix(gatsby-source-contentful): Add
proxy.protocol
to Joi schema PR #36011 - ericapisani: chore(gatsby): upgrade lmdb to 2.5.3 PR #36087
- openscript
July 05 2022
Welcome to gatsby@4.18.0
release (July 2022 #1)
Key highlights of this release:
typesOutputPath
option for GraphQL Typegen - Configure the location of the generated TypeScript types- Server Side Rendering (SSR) in development - Find bugs & hydration errors more easily during
gatsby develop
- Open RFCs - MDX v2 & Metadata management
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.
typesOutputPath
option for GraphQL Typegen
We saw great adoption of the GraphQL Typegen feature we've added in the 4.15 Release. We've heard that the location of the automatically generated TypeScript definitions file should be configurable. By default, it's generated in the src/gatsby-types.d.ts
location.
You're now able to specify the location of the generated types using the typesOutputPath
option. The graphqlTypegen
option accepts both a boolean and an object now. If you don't pass an object (but graphqlTypegen: true
), the default value for each option will be used.
module.exports = {
graphqlTypegen: {
typesOutputPath: `gatsby-types.d.ts`,
},
}
The path is relative to the site root, in the example above the file would be generated at <root>/gatsby-types.d.ts
. For more details and any future options, see the Gatsby Config API.
Server Side Rendering (SSR) in development
Shortly before v4 release, we disabled DEV_SSR flag because getServerData
was not properly handled. In this release, we handled getServerData
properly and restored the flag. Now you can add the DEV_SSR
flag to your gatsby-config
file so you can spot and fix SSR errors (like trying to access the window object) during development.
Open RFCs
We continue to have ongoing RFCs that weโd like your input on. Please give it a read, if applicable a try, and leave feedback!
- Support for MDX v2: We are updating
gatsby-plugin-mdx
to be compatible with MDX v2. Keep a look out in the discussion for a canary to try! - Metadata Management API: We will be adding a built-in metadata management solution to Gatsby. Work is in progress and you can try out the canary now!
Notable bugfixes & improvements
gatsby
gatsby-cli
: SetNODE_ENV
earlier to fix Jest failing withCouldn't find temp query result
error, via PR #35968gatsby-source-wordpress
: Always hydrate images and use the right parent element, via PR #36002- Properly compile all packages for Node and browser environment, via PR #35948
- Use
babel-plugin-lodash
to reducelodash
size published packages, via PR #35947
Contributors
A big Thank You to our community who contributed to this release ๐
- glitton: chore(docs): Remove trailing slashes section in creating-and-modifying-pages PR #35843
- rutterjt: chore(docs): fix query type name in Typegen guide PR #35961
- slaleye: chore(docs): Update copy in tutorial part 1 PR #35992
- cameronbraid: fix(gatsby): Partytown URI encoding of redirect parameters PR #35990
- axe312ger: chore(gatsby): Remove MDX
resolutions
PR #36010
June 21 2022
Welcome to gatsby@4.17.0
release (June 2022 #2)
Key highlights of this release:
- JavaScript and CSS bundling performance improvements
- Incremental builds performance improvements
- Open RFCs
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.
JavaScript and CSS bundling performance improvements
We are constantly on the hunt for ways to make Gatsby faster and more reliable, and in this release we made a change that saw a 39% speed increase in building production JavaScript and CSS bundles.
This was possible by ensuring that we only polyfill required modules based on your browserlist. For full details see PR #35702.
Incremental builds performance improvements
Continuing the performance trend, we also adjusted the way we generate our content digest, resulting in fewer changed nodes and invalidated queries.
In our test case we found invalidated queries were reduced from 40k to 6k, dramatically speeding up incremental builds. See PR #33671 for complete details.
Open RFCs
We continue to have ongoing RFCs that weโd like your input on. Please give it a read, if applicable a try, and leave feedback!
- Support for MDX v2: We are updating
gatsby-plugin-mdx
to be compatible with MDX v2. Keep a look out in the discussion for a canary to try! - Metadata Management API: We will be adding a built-in metadata management solution to Gatsby. Work is in progress and you can try out the canary now!
Notable bugfixes & improvements
gatsby
:gatsby-source-drupal
: Fix not found image urls failing builds, via PR #35855gatsby-source-wordpress
: Refactor option check, via PR #35827gatsby-transformer-documentationjs
: Add support for JSX files, via PR #35899
Contributors
A big Thank You to our community who contributed to this release ๐
- chrispecoraro: Update gatsby-script.md PR #35903
- rutterjt: chore(docs): Add Jest 28
jest-environment-jsdom
information PR #35904 - rudevdr: chore(docs): fix export.createPages to exports.CreatePages in documentation PR #35874
- febeling: chore(gatsby-source-drupal): Document fix for 406 PR #35927
- labifrancis: chore(docs): Add Gatsby Script component to "Adding Analytics" PR #35839
- tsdexter: refactor(gatsby-source-wordpress): move option check within relevant function to ensure enforcement PR #35827
- ElegantStack: chore(docs): add options command to cli reference PR #35815
June 06 2022
Welcome to gatsby@4.16.0
release (June 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.
Speed Improvements for Image Processing
After updating gatsby-plugin-image
and gatsby-plugin-sharp
, you should see a considerate amount of time saved during image processing as two improvements were shipped. In PR #35791 the image metadata to calculcate things like dominant color was moved to a cache that persists between builds leading to increased speed on subsequent builds. In PR #35814 the image is getting resized before calculating the dominant color as this can get slow for really large images. This may be a less accurate representation, but for a placeholder it is good enough. Thanks to ascorbic for contributing both PRs.
useContentfulImage
hook
With useContentfulImage
and the URL to the image on the Contentful Image API you can create dynamic images on the fly:
import { GatsbyImage } from "gatsby-plugin-image"
import * as React from "react"
import { useContentfulImage } from "gatsby-source-contentful/hooks"
const MyComponent = () => {
const dynamicImage = useContentfulImage({
image: {
url: "//images.ctfassets.net/k8iqpp6u0ior/3BSI9CgDdAn1JchXmY5IJi/f97a2185b3395591b98008647ad6fd3c/camylla-battani-AoqgGAqrLpU-unsplash.jpg",
width: 2000,
height: 1000,
},
})
return <GatsbyImage image={dynamicImage} />
}
export default MyComponent
Learn more in the useContentfulImage
documentation.
Node 18 Compatibility
In a series of PRs we've ensured that Gatsby and its dependencies are compatible with Node 18:
- In PR #35585
lmdb
was updated as in never versions it ships with prebuilt binaries for Node 18. - In PR #35621 we migrated from
source-map
to@jridgewell/trace-mapping
assource-map
in incompatible with Node 18. - In PR #35782 we updated Parcel to 2.6.0 to update its internal
lmdb
dependency.
Notable bugfixes & improvements
gatsby
:gatsby-plugin-preload-fonts
: Disable Puppeteer cache, via PR #34633gatsby-source-drupal
: Allow sites to configure the request timeout, via PR #35794gatsby-plugin-utils
: Add newsetRequestHeaders
API, via PR #35655gatsby-plugin-utils
: AddcontentDigest
to image cdn args, via PR #35816gatsby-plugin-mdx
: Don't allow JS frontmatter by default, via PR #35830
Contributors
A big Thank You to our community who contributed to this release ๐
- trevorblades: fix(docs): Lowercase typename PR #35821
- Danishkhurshid: fix(gatsby-source-drupal): Add a check for data prop PR #35719
- rutterjt: chore(docs): Fix
videoSourceURL
markdown key mismatch PR #35755 - benogle: chore(docs): Add articles to awesome gatsby resources PR #35738
- Apprentice76: fix(gatsby-source-filesystem): Update
createRemoteFileNode
args PR #35422 - tsdexter: fix(gatsby-source-wordpress): bug patch for issue 35460 PR #35817
- AbdallahAbis: chore(docs): Remove typo in Script guide PR #35826
- axe312ger
- tordans: chore(docs): Update using-web-fonts for fontsource PR #35579
- ascorbic
- just-boris: fix(gatsby): Remove
removeOffCanvasPaths
svgo option PR #35788 - varunsh-coder: chore(stale-action): Add GitHub token permissions PR #35713
- Foo-x: fix(gatsby-plugin-preload-fonts): disable cache PR #34633
- joshuacox: chore(docs): Update outdated building a theme tutorial snippets PR #35792
May 24 2022
Welcome to gatsby@4.15.0
release (May 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.
Script Component
We're releasing a built-in <Script>
component that aids in loading third-party scripts performantly.
As a familiar React component, migration to the <Script>
component is as simple as importing and capitalizing your existing script tags in most cases:
import { Script } from "gatsby";
-<script src="https://my-example-script" />
+<Script src="https://my-example-script" />
This will load your script after your page has hydrated by default, offering performance benefits over the native <script>
tag (even with async
or defer
applied).
In our testing so far, we've noted a 20% reduction in Total Blocking Time for Gatsbyjs.com by moving 3 third party scripts to use the off-main-thread
strategy via the new component. With the benefit of gradually migrating scripts to the new component, we'll be able to continue to fine tune scripts to the appropriate strategies, and provide the very best frontend speed to visitors of Gatsbyjs.com.
The Gatsby <Script>
component includes three loading strategies that you can define, allowing a great deal of flexibility via a single strategy
attribute:
post-hydrate
- Loads after the page has hydratedidle
- Loads after the page has become idleoff-main-thread
(experimental) - Loads off the main thread in a web worker via Partytown
In addition, these features are supported out of the box:
- Inline scripts via template literals and the
dangerouslySetInnerHTML
property onLoad
andonError
callbacks forpost-hydrate
andidle
scripts with sources
For full details, see the Gatsby Script reference documentation.
Note - If you are using Jest, you will need to include
gatsby-script
in yourtransformIgnorePatterns
key in your Jest config sincegatsby-script
is an ES module. See the unit testing documentation on Jest configuration for more details.
GraphQL Typegen
In the last v4.14 release we've added GraphQL Typegen as an experimental feature. After some bugfixing and improving its documentation the feature is now generally available behind a gatsby-config
option.
module.exports = {
graphqlTypegen: true,
}
Read the GraphQL Typegen guide to learn how you can use it today and continue to give us your feedback in the RFC discussion.
Notable bugfixes & improvements
gatsby
:gatsby-cli
: Default toproduction
NODE_ENV forgatsby serve
to be consistent withgatsby build
, via PR #35693gatsby-source-wordpress
: handle media edit (for example rotation or rename) properly for IMAGE_CDN, via PR #35687gatsby-source-drupal
:
Contributors
A big Thank You to our community who contributed to this release ๐
- chuckreynolds: sitemap plugin readme has incorrect array name reference PR #35659
- admir4l: chore(gatsby, gatsby-cli, gatsby-plugin-sharp): remove old unused UUID dependency PR #35657
- feedm3: fix(gatsby): use correct types for the response headers PR #35633
- alvis: fix(gatsby): correct the types of
createNode
action return PR #32522
May 10 2022
Welcome to gatsby@4.14.0
release (May 2022 #1)
Key highlights of this release:
- Experimental: GraphQL Typgen
- Improvements in Image and Font Loading Times
- Gatsby Functions Body Parsing Configuration
gatsby-source-drupal
: Image CDN Support- Updated Default Starter
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.
Experimental: GraphQL Typegen
We're adding a built-in way for automatic TypeScript type generation and better GraphQL IntelliSense in Gatsby. If you've used gatsby-plugin-typegen or gatsby-plugin-ts in the past you'll be familiar with this feature and we really value your feedback on this feature!
Here's a short video of what you'll be able to do:
As noted already, this feature is still experimental and the API surface might change until the feature is in general availability. Please give us your feedback in the RFC: GraphQL Typegen discussion after you have tried it out.
Trying it out
Make sure that you're on gatsby@latest
or gatsby@next
. Next, edit your gatsby-config.js
to include a flag called GRAPHQL_TYPEGEN
.
module.exports = {
flags: {
GRAPHQL_TYPEGEN: true,
}
}
Then you can run gatsby develop
and files will be created inside .cache/typegen
. You can reference .cache/typegen/graphql.config.json
inside a graphql.config.js
at the root of your site to configure the GraphQL language server/VSCode extension.
Then inside your pages you can access the global namespace Queries
to get your type information. Make sure that your queries have a name!
The project graphql-typegen-testing shows all this if you want to get started quickly.
Intellisense
The video shown above gives autocompletion for your queries. This is achieved by using VSCode, the GraphQL Plugin, and defining a graphql.config.js
with the following contents:
module.exports = require("./.cache/typegen/graphql.config.json")
We intend to document as many ways to use a GraphQL language server to benefits from this information, so we'd also love your input here.
Improvements in Image and Font Loading Times
Previously, Gatsby preloaded a large amount of JavaScript and JSON assets which may lead to Network Congestion, especially for large sites with a lot of split chunks. This didn't allow images and fonts to load as early as possible.
With this release we changed Gatsby's behavior and now lazily load non-essential scripts and assets. You can see a before and after of two waterfall diagrams on gatsbyjs.com here:
In total this lead to a 50% improvement in loading speed for gatsbyjs.com which you can see in this short video:
The website finished loading after 1.2s compared 2.2s on previous Gatsby versions. This is achieved by using the improvements in Gatsby's core, gatsby-plugin-gatsby-cloud
's default settings, and Gatsby Cloud.
Gatsby Functions Body Parsing Configuration
Gatsby now supports adjusting body parsing middleware for API functions. This allows users to increase request body size limit and/or support 3rd party webhook signature verification. For details and examples check Custom body parsing
documentation.
gatsby-source-drupal
: Image CDN Support
Drupal now has Image CDN support. Enable it in your site by following the official gatsby-source-drupal
documentation.
Updated Default Starter
We updated our default Starter template gatsby-starter-default
to contain references to documentation, tutorial, our monorepo examples folder, and more โ and aligned its look-and-feel to that of our gatsby new
/npm init gatsby
experience. It shows you how to use TypeScript, Server Side Rendering, and Deferred Static Generation in your Gatsby application.
Notable bugfixes & improvements
gatsby-source-contentful
:gatsby
: FixesUNHANDLED EXCEPTION write EPIPE
on Netlify, via PR #35513gatsby-plugin-image
:gatsby-source-wordpress
:
Contributors
A big Thank You to our community who contributed to this release ๐
- chrisq21: chore(gatsby): Expose
serverDataStatus
field in SSR type declaration file PR #35505 - rodet: chore(docs): Add note about optimizing GitHub publish PR #35465
- renbaoshuo: chore(docs): remove git.io urls PR #35497
- rburgst: fix(gatsby-remark-images): support resolving markdown images from child nodes PR #28093
- orinokai: fix(gatsby-plugin-preload-fonts): defer checking for write access PR #35381
- GaryPWhite: chore(gatsby): Bump
react-dev-utils
to v12 PR #35468 - axe312ger: feat(contentful): add support for tables in Rich Text PR #33870
- ascorbic: fix(gatsby): wait for worker jobs to complete PR #35513
- xavivars
- me4502: perf(gatsby): Minify page-data PR #35578
April 26 2022
Welcome to gatsby@4.13.0
release (April 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.
Traced SVG option for Image CDN
The popular traced SVG option is now available for use with Image CDN on Gatsby Cloud.
The change spans four separate packages:
gatsby-plugin-sharp
gatsby-transformer-sharp
gatsby-plugin-utils
gatsby-remark-images
See PR #35328 for full details.
Open RFCs
We continue to have ongoing RFCs that we'd like your input on. Give it a read, if applicable a try, and leave feedback. Thanks!
- New Bundler in Gatsby: We're looking at changing the underlying bundler at Gatsby. See the "How can I help?" section to see what we're looking to get from you, our community!
- Script Component: We would like to introduce a new API in Gatsby that aids in loading third-party scripts performantly.
- GraphQL TypeScript Generation: A built-in way for automatic TypeScript type generation and better GraphQL IntelliSense.
Notable bugfixes & improvements
gatsby
- Limit node manifest file creation via PR #35359
gatsby-plugin-gatsby-cloud
gatsby-plugin-netlify-cms
- Fix compatibility with React 18 via PR #35365
gatsby-source-wordpress
gatsby-link
- Modify relative links based on trailing slash option via PR #35444
gatsby-transformer-screenshot
- Complete migration from better-queue to fastq via PR #35425
gatsby-source-contentful
- Prevents null pointers when creating asset nodes that are not configured on some languages via PR #35244
Contributors
A big Thank You to our community who contributed to this release ๐
- critesjm: fix(gatsby): add missing
ownerNodeId
prop to Page type PR #35367 - inbreaks: chore(docs): Update
.gitlab-ci.yml
deploy PR #35371 - doxsch: fix(gatsby-transformer-screenshot): finished migration from better-queue to fastq PR #35425
- axe312ger: chore: renovate - add cypress PR #35375
- tackc: chore(docs):Update Link URL PR #35462
- dofbi: chore(gatsby-source-wordpress): Fix typo in
presets[].options
PR #35455 - kspeyanski: fix(gatsby-plugin-netlify-cms): react18-compatible require resolve PR #35365
April 12 2022
Welcome to gatsby@4.12.0
release (April 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.
New RFCs
The Gatsby core team is running a collection of RFC's for new features coming to Gatsby. Please review the open RFC's and share your perspective to help us deliver the best possible experience for Gatsby developers, like you!
- RFC for new Script component in Gatsby - the script component will make it easier to incorporate 3rd party scripts without negatively impacting site performance
- RFC for new Bundler in Gatsby - Gatsby is evaluating other bundlers in order to deliver faster local development and production build speeds
Notable bugfixes & improvements
gatsby
- Fix React 18 hydration with offline plugin via PR #35319
- Use gatsby root instead of
process.cwd()
when initializing cache via PR #35263 - Fix intermittent wrong sort results when sorting on materialized field via PR #35271
- Fix URL encoding issue with DSG urls via PR #35336
- Fix URL encoding issue with SSR urls via PR #35346
create-gatsby
: Fix missing site title prompt via PR #35272gatsby-core-utils
: Fix exports map for importing fromdist
via PR #35274gatsby-plugin-sharp
: Handle slashes and..
within paths for Windows via PR #35246gatsby-plugin-utils
: Fix path pieces being too long in image URLs and make url safely encoded via PR #35160gatsby-source-contentful
: Handle backreferences on data updates properly via PR #35214gatsby-source-wordpress
: Fix logic for matching image nodes via PR #35324
Contributors
A big Thank You to our community who contributed to this release ๐
- oneknucklehead: chore(babel-preset-gatsby): Updated README to include babel presets PR #35069
- me4502: fix(gatsby): ignore crawlers when prefetching PR #35260
- g00glen00b: fix(gatsby-source-filesystem): use correct hash when using createFileNodeFromBuffer PR #35243
- jasonbosco: chore(docs): Add Typesense as a search engine option PR #35257
- gmourier: chore(docs): Fix Meilisearch spelling PR #35275
- BrunoAderaldo: chore(docs): typo in 4.11 release notes PR #35349
March 29 2022
Welcome to gatsby@4.11.0
release (March 2022 #3)
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.
gatsby-source-shopify
v7
We released a new major version of gatsby-source-shopify
๐ Thanks to the work of our community member Byron Hill the new version features a bunch of improvements:
- You can now query product videos or 3D models, in addition to product images.
- Variants, Images, etc. now keep the order in which you define them in the Shopify backend.
- Multiple metafield types were merged to one single metafield type (more alignment with Shopify's admin API schema).
- You can now query presentment prices.
- Explicit type definitions with disabled type inference. Or in other words: You can have no products in your store or a bunch of fields that are
null
without breaking your schema or builds. - The API schema nearly matches the Shopify admin API schema which means that for the most part you can refer to Shopify's documentation.
Check out the V6 to V7 Migration Guide to learn more. Interested in contributing to Gatsby? Our contributing section has all the information you need.
React 18
The latest RC of React 18 introduced a breaking change in the SSR API. In this release we're at 100% compatibility again. Right on time for the official React 18 release. Make sure to read How to Try React 18 in Gatsby to get started.
With React 18, you can start using Suspense, React.lazy and get your hands on the new concurrent mode to speed up your Gatsby website. More information can be found on the React blog
Notable bugfixes & improvements
gatsby
gatsby-plugin-utils
: Support aspect ratio for Image Service, via PR #35087gatsby-source-mongodb
: Add optionaltypePrefix
option to override dbName, via PR #33820gatsby-cli
: Resolve babel preset ts explicitly, via PR #35153gatsby-plugin-preact
: Fix preact alias via PR #35196
Contributors
A big Thank You to our community who contributed to this release ๐
- seanparmelee: feat(gatsby-source-graphql): upgrade apollo & graphql-tools deps PR #34772
- seanho96: chore(docs): Update prismic source graphql tutorial docs PR #35218
- CommanderRoot: refactor: replace deprecated String.prototype.substr() PR #35205
- benackles: chore(docs): Add Deferred Static Generation to glossary PR #35172
- EdPike365: chore(docs): Add context to useScrollRestoration usage PR #35163
- byronlanehill: BREAKING CHANGE(gatsby-source-shopify): Rewrite for media, presentment, schema, etc. PR #34049
- Aviatorscode2: chore(docs): Move
loadable-components
instructions PR #35116 - michael-proulx: feat(gatsby-source-mongodb): Add option name to overwrite node middleโฆ PR #33820
- urre: Update broken link PR #35184
March 15 2022
Welcome to gatsby@4.10.0
release (March 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.
Image CDN
Free your site from slow images forever. With the new Image CDN, we've added better support for remote files and images when building source plugins. The source plugins for WordPress & Contentful are already using the new RemoteFile
GraphQL interface to enable the new GatsbyImage
resolver (so you can try it out today). Other popular CMS and support for local files will follow. The new GatsbyImage
resolver downloads images on demand and processes them during the build. This results in reduced build times and better user experience. You can even remove image processing as a whole during the build step! With Image CDN on Gatsby Cloud, we defer all image processing at the edge, getting even faster builds!
If you have feedback, please post it to the umbrella discussion. Thanks!
If you're a source plugin author or written your custom source plugin, check out the enabling Image CDN support guide. You can also read the announcement blogpost Image CDN: Lightning Fast Image Processing for Gatsby Cloud to learn more.
Here's how you can use it in your queries:
query {
speakerPage {
socialImage {
gatsbyImage(layout: FIXED, width: 440)
}
image {
gatsbyImage(layout: CONSTRAINED, width: 280, height: 280)
}
}
}
So gatsbyImage
replaces gatsbyImageData
that you know from gatsby-plugin-image
already. Feature parity for its arguments is not 100%, but the most common operations behave the same. Read How to enable Image CDN to start using Image CDN today.
Once Image CDN is enabled, images will be served from a relative URL similar to this:
/_gatsby/image/<base64-string>/<base64-string>/<original-file-name>.<file-extension>
Notable bugfixes & improvements
gatsby
gatsby-plugin-sharp
Contributors
A big Thank You to our community who contributed to this release ๐
- njbmartin: chore(docs): typo in typescript documentation PR #35040
- baranbbr: chore(docs): Conditionally sourcing files using environment variables PR #35056
- hasthamalp: chore(docs): Update query-execution.md PR #35115
- tcoopman: fix(gatsby): null check for context PR #35096
- Dusch4593: chore(docs): Revising scope of
wrapPageElement()
andwrapRootElement()
PR #35057 - mckelveygreg: chore(gatsby): add generic to GatsbyFunctionRequest PR #35029
- benackles: chore(docs): Fix broken link PR #35071
- tianheg: chore(docs): Fix link to TS doc in tutorial PR #35014
- reviewher: fix(gatsby-transformer-excel): Use
readFile
Buffer PR #35050 - jonohewitt: fix(gatsby-plugin-sharp): Upgrade
probe-image-size
to fix memory leak warning PR #35009 - cheru-dev: chore(docs): Fix typos PR #35119
- josephjosedev
- keevan: docs(gh-pages): improve separate repository instructions PR #35118
- adambaratz: fix(gatsby): Misspelled cacheIdentifier key PR #35070
- natalyjazzviolin: chore(docs): Update migration guide to add more info about image resolvers PR #35105
March 01 2022
Welcome to gatsby@4.9.0
release (March 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.
gatsby-config
and gatsby-node
Support for TypeScript in In the last release we added support for TypeScript in gatsby-browser
and gatsby-ssr
and as a follow-up we're introducing a much requested feature: Support for TypeScript in gatsby-config
and gatsby-node
๐
When you try it out in your project, please give us feedback in the accompanying RFC on what you like, what doesn't work, and what you like to see in the future. Note: There are currently some limitations that you'll need to be aware of. In the RFC you can also read why we chose Parcel for this feature and how we did it.
You can learn everything about this new feature on the TypeScript and Gatsby documentation page but here are two small examples of gatsby-config
and gatsby-node
with TypeScript:
import type { GatsbyConfig } from "gatsby"
const config: GatsbyConfig = {
siteMetadata: {
title: "Your Title",
},
plugins: [],
}
export default config
import type { GatsbyNode } from "gatsby"
type Person = {
id: number
name: string
age: number
}
export const sourceNodes: GatsbyNode["sourceNodes"] = async ({
actions,
createNodeId,
createContentDigest,
}) => {
const { createNode } = actions
const data = await getSomeData()
data.forEach((person: Person) => {
const node = {
...person,
parent: null,
children: [],
id: createNodeId(`person__${person.id}`),
internal: {
type: "Person",
content: JSON.stringify(person),
contentDigest: createContentDigest(person),
},
}
createNode(node)
})
}
You can also check out the using-typescript and using-vanilla-extract examples!
Migrating away from old workarounds
This list is probably incomplete. If you've used another workaround in the past, add it to this document by using the "Edit on GitHub" button at the bottom.
ts-node
: By having both agatsby-config.js
andgatsby-config.ts
(wheregatsby-config.js
registersts-node
) you were able to use TypeScript. You'll need to remove thegatsby-config.js
file,ts-node
dependency, and address any of the current limitations. When both agatsby-config.js
andgatsby-config.ts
exist the.ts
file will now always take precedence.
Notable bugfixes & improvements
gatsby
Contributors
A big Thank You to our community who contributed to this release ๐
February 22 2022
Welcome to gatsby@4.8.0
release (February 2022 #2)
Key highlights of this release:
- Support for TypeScript in
gatsby-browser
andgatsby-ssr
- New TypeScript option when creating Gatsby projects from the CLI
- Significant memory usage reduction when filtering and sorting nodes
- New APIs in
gatsby-core-utils
andgatsby-plugin-utils
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.
gatsby-browser
and gatsby-ssr
Support for TypeScript in In addition to Gatsby's current TypeScript support for your site's .ts
/.tsx
files, you can now use TypeScript with your gatsby-browser
and gatsby-ssr
files.
The GatsbyBrowser
and GatsbySSR
types can now be used in gatsby-browser.tsx
and gatsby-ssr.tsx
respectively.
import * as React from "react"
import { GatsbyBrowser } from "gatsby"
export const wrapPageElement: GatsbyBrowser["wrapPageElement"] = ({ element }) => {
return (
<div>
<h1>Hello World</h1>
{element}
</div>
)
}
import * as React from "react"
import { GatsbySSR } from "gatsby"
export const wrapPageElement: GatsbySSR["wrapPageElement"] = ({ element }) => {
return (
<div>
<h1>Hello World</h1>
{element}
</div>
)
}
Work is in progress for TypeScript support for gatsby-config
and gatsby-node
files. Check out the RFC to learn how to test it out today.
New TypeScript option when creating Gatsby projects from the CLI
When initializing new Gatsby projects with gatsby new
, npm init gatsby
, or npx create-gatsby
, you can now select JavaScript or TypeScript as an option to start your project with.
After calling one of the above commands with no flags, the third question will now be: "Will you be using JavaScript or TypeScript?". Selecting JavaScript will start your project with gatsby-starter-minimal
, and selecting TypeScript will start your project with gatsby-starter-minimal-ts
.
A new -ts
flag has been added for use with npm init gatsby
and npx create-gatsby
. Executing npm init gatsby -ts
or npx create-gatsby -ts
will skip the language question and start your project with gatsby-starter-minimal-ts
.
Lastly, arguments for Gatsby initializer commands are now not positional. Any order of your desired site name and flags will work as expected (e.g. npm init gatsby -ts hello-world -y
).
Significant memory usage reduction when filtering and sorting nodes
Gatsby no longer stores whole nodes in memory when executing filtering and sorting processes on your site. Now, Gatsby uses weak references and node partials, resulting in significant memory usage reduction for sites with many large nodes.
See PR #34747 for more information.
gatsby-core-utils
and gatsby-plugin-utils
New APIs in Two new APIs have been added:
Calling createMutex
gives you a mutex that you can use to safely perform processes concurrently in places where that matters, such as in workers.
For example in the code below, one worker can execute while all others wait for it to finish. This is handy in scenarios like writing to the same file to disk.
const { createMutex } = require("gatsby-core-utils/mutex")
const mutex = createMutex("my-custom-mutex-key")
await mutex.acquire()
await fs.writeFile("pathToFile", "my custom content")
await mutex.release()
Calling hasFeature
allows you to check if the current version of Gatsby has a certain feature. This is particularly useful for plugin authors.
const { hasFeature } = require(`gatsby-plugin-utils`)
if (!hasFeature(`image-service`)) {
// You can do things like polyfill image-service here so older versions have support as well
}
Note - The list of features available will be added in future PRs, the above is an example of how it will be used.
Notable bugfixes & improvements
gatsby-plugin-gatsby-cloud
: Improved UX for preview success and error notifications, via PR #34725gatsby
:- Removal of
v8-compile-cache
for better ESM support, via PR #34672 - Support use of
node.slug
to match node manifests to pages for Gatsby Preview, via PR #34790 - Fix Content Sync when using DSG, via PR #34799
- Allow referencing derived types in schema customization, via PR #34787
- Refactor load plugin modules, via PR #34813
- Upgrade from lmdb-store to lmdb, via PR #34576
- Removal of
gatsby-source-wordpress
: Fix Safari image loading bug, via PR #34727gatsby-core-utils
: Improvements tofetch-remote-file
, via PR #34758
Contributors
A big Thank You to our community who contributed to this release ๐
- kyleslie2: Typo fix PR #34749
- angeloashmore: chore(docs): Add Prismic to
using-gatsby-plugin-image
PR #34751 - paulduszak: chore(docs): Update "building a theme" tutorial PR #34732
- jhcao23: docs: update typo Forestry PR #34805
- VividhPandey003: documentation: Add Third Party Schema PR #34820
- axe312ger
February 08 2022
Welcome to gatsby@4.7.0
release (February 2022 #1)
Key highlights of this release:
trailingSlash
Option (Beta) - Now built into the Framework itself- Faster Schema Creation &
createPages
- Speed improvements of at least 30%
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.
trailingSlash
Option
Currently in Public Beta
Through the RFC Integrated handling of trailing slashes in Gatsby we've worked on making the trailing slashes feature a first-class citizen in Gatsby. We're happy to announce that gatsby-config
now supports a trailingSlash
configuration with these three main options:
always
: Always add trailing slashes to each URL, e.g./x
to/x/
.never
: Remove all trailing slashes on each URL, e.g./x/
to/x
.ignore
: Don't automatically modify the URL
You can set it like this:
module.exports = {
trailingSlash: "always"
}
Throughout Gatsby 4 the default setting for trailingSlash
will be legacy
(to keep the current behavior) but with Gatsby 5 we'll remove the legacy
setting and make always
the default. Please note that these plugins are considered deprecated now: gatsby-plugin-force-trailing-slashes and gatsby-plugin-remove-trailing-slashes.
Gatsby Cloud supports this new setting out of the box and also uses 301
redirects to bring visitors to the right location. Locally you can use gatsby serve
to see the behavior. Any other hosting provider (or if youโre managing this on your own) should follow the โRedirects, and expected behavior from the hosting providerโ section on the initial RFC.
If you're unit testing gatsby-link
you'll need to update the moduleNameMapper
option to include gatsby-page-utils
, see Unit Testing documentation for more details.
The information presented here is also available in the gatsby-config docs page and in the PR #34268 that implemented this.
Please share your feedback and any issues you encounter directly into the corresponding discussion.
createPages
Faster Schema Creation & We've seen a handful of sites struggling with long schema building
and createPages
steps. In this release, we've upgraded our external graphql-compose
dependency to v9 to improve these steps by at least 30-50% for schemas/queries with many relationships. For example, one of our customers has seen improvements for createPages
of 786s to 20s. This update is recommended to everyone and doesn't necessitate any changes on your end.
More information can be found in the PR #34504.
Notable Bugfixes & Improvements
gatsby
:gatsby-plugin-fullstory
: Updated snippet, via PR #34583gatsby-core-utils
: Remote file downloads are now queued properly for all cases, via PR #34414gatsby-plugin-preact
: Fix alias forreact-dom/server
, via PR #34694- Added a
vanilla-extract
example project, via PR #34667
Contributors
A big Thank You to our community who contributed to this release ๐
- josephjosedev
- axe312ger
- seanparmelee
- millette: chore(gatsby-source-wordpress): Add WPGraphQL WPML PR #34609
- jeffreyvdhondel: feat(gatsby-plugin-google-gtag): add selfHostedOrigin option PR #34352
- Rutam21: fix(gatsby): fixes stacktraces from async functions break error reporting PR #33712
- rschristian: fix(gatsby-plugin-preact): Adding missing alias for
react/jsx-runtime
PR #34666 - tamaosa: fix(gatsby-plugin-preact): Fix alias for react-dom/server PR #34694- ollybenson: chore(docs): Update gatsby-plugin-image to mention local data source PR #34426
- rileyjshaw: chore(docs): update PurgeCSS instructions for Tailwind 3 PR #34726
- xaviemirmon: chore(docs): Update "Debugging HTML builds" to include
getServerData
PR #34631 - marceloverdijk: chore(docs): Added required
type
attribute to resolver PR #34716 - cameronbraid: chore(docs): Update
transformOptions
defaults PR #34713%
January 25 2022
Welcome to gatsby@4.6.0
release (January 2022 #2)
Key highlights of this release:
- Speeding Up Subsequent Queries
- Tracking Image Changes in Markdown Files
- New Major Version for
gatsby-plugin-utils
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.
Speeding Up Subsequent Queries
Subsequent queries now get a ~10-15% performance boost! You'll see this improvement after your first gatsby build
for all following runs (unless the cache is cleared). These percentage may defer depending on the complexity of nodes. We were able to achieve this by caching rootNode
& trackedRootNodes
across instances of graphqlRunner
via PR #33695
Tracking Image Changes in Markdown Files
When using an image inside markdown files together with gatsby-remark-images
(e.g. 
) there were cases when a change to the image wasn't reflected in the site. Changes like resizing or directly editing the image required a gatsby clean
in the past. This broken functionality is now fixed with PR #34433 and changed images will now directly show during gatsby develop
and gatsby build
.
gatsby-plugin-utils
New Major Version for You can configure plugin options for your plugins and unit test the options schema using helper functions from gatsby-plugin-utils
. The schema validation for the options schema now does not throw errors anymore on warnings like unknown keys (see PR that implemented this for more information). This fixed an issue where default values where not passed through to the plugin if e.g. unknown keys were used.
Here's a short list of changes you'll need to make or be aware of:
pluginOptionsSchema
returns warnings instead of errors now for unknown keystestPluginOptionsSchema
now returnswarnings
andhasWarnings
in addition to the existing values- Default options you set in your plugin option schema are now correctly passed through to the plugin, even when a user sets unknown keys
Migration
Here's a short before/after example on how to migrate your test when you're checking for unknown keys.
Before:
// The plugin doesn't take any options
exports.pluginOptionsSchema = ({ Joi }) => Joi.object({})
import { testPluginOptionsSchema } from "gatsby-plugin-utils"
import { pluginOptionsSchema } from "../gatsby-node"
it(`should not accept any options`, async () => {
const expectedErrors = [`"optionA" is not allowed`]
const { errors } = await testPluginOptionsSchema(
pluginOptionsSchema,
{
optionA: `This options shouldn't exist`,
}
)
expect(errors).toEqual(expectedErrors)
})
After:
import { testPluginOptionsSchema } from "gatsby-plugin-utils"
import { pluginOptionsSchema } from "../gatsby-node"
it(`should not accept any options`, async () => {
const expectedWarnings = [`"optionA" is not allowed`]
const { warnings, isValid, hasWarnings } = await testPluginOptionsSchema(
pluginOptionsSchema,
{
optionA: `This options shouldn't exist`,
}
)
expect(isValid).toBe(true)
expect(hasWarnings).toBe(true)
expect(warnings).toEqual(expectedWarnings)
})
Notable Bugfixes & Improvements
gatsby-plugin-manifest
: Generate icons sequentially, via PR #34331create-gatsby
: Fixed an issue where user-providedGATSBY_TELEMETRY_DISABLED
environment variable did not disable telemetry, via PR #34495gatsby-sharp
: Create more resilient wrapper around sharp, via PR #34339gatsby-source-contentful
: Enable tag support for assets, via PR #34480gatsby
: Optimized queries that filter just onid
, via PR #34520
Contributors
A big Thank You to our community who contributed to this release ๐
-
newhouse: Update plugins.md to have correct URL for gatsby-plugin-segment-js PR #34397
-
janaagaard75: Upgrade to strip-ansi ^6.0.1 PR #34383
-
jazanne: Fix misspelling of "precedence" in log message PR #34428
-
axe312ger: fix(contentful): enable tag support for assets PR #34480
-
herecydev: fix(gatsby): handle session storage not being available PR #34525
-
njbmartin: fix(plugin-schema-snapshot): unlink file on init PR #34527
-
ShaunDychko: chore(docs): Update client-only self-hosting instructions PR #34537
January 11 2022
Welcome to gatsby@4.5.0
release (January 2022 #1)
Key highlights of this release:
- Gracefully Handling Browser Cache Issues
- TypeScript Types for
getServerData
- Deprecation of
gatsby-recipes
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.
Gracefully Handling Browser Cache Issues
If you've seen the error The result of this StaticQuery could not be fetched
, Loading (StaticQuery)
, or We couldn't find the correct component chunk with the name
you might have run into issues regarding useStaticQuery
and some form of browser cache. More details are laid out in these two issues: #33956 and #33112.
The way we could reproduce this problem was using cached HTML from previous build (which would use previous JavaScript bundles), that would fetch new data (from newer builds). In those cases wrong static queries were fetched as the cached HTML expected other bundles.
In #34225 we've added an integrity check to Gatsby's runtime to see if the loaded HTML & JavaScript is matching the new data, and if not a single (forced) reload tries to fetch the updated assets.
If you've run into problems like these, please upgrade and let us know (in the two issues mentioned above) if your problem is resolved.
getServerData
TypeScript Types for Gatsby now ships with TypeScript types for the getServerData
function. You can use the GetServerDataProps
and GetServerDataReturn
as following:
import * as React from "react"
import { GetServerDataProps, GetServerDataReturn } from "gatsby"
type ServerDataProps = {
hello: string
}
const Page = () => <div>Hello World</div>
export default Page
export async function getServerData(
props: GetServerDataProps
): GetServerDataReturn<ServerDataProps> {
return {
status: 200,
headers: {},
props: {
hello: "world",
},
}
}
If you're using an anonymous function, you can also use the shorthand GetServerData
type like this:
const getServerData: GetServerData<ServerDataProps> = async props => {
// your function body
}
gatsby-recipes
Deprecation of In early 2020 we've introduced Gatsby Recipes to automate common site building tasks. Since then our priorities and plans on that front for Gatsby have shifted, thus gatsby-recipes
itself didn't ever go from alpha status to general availability. We're deprecating gatsby-recipes
now to signal that we'll no longer will continue work on this specific package and to also remove some heavy dependencies from gatsby-cli
. Some deprecation warnings or audit messages about packages from gatsby-recipes
should be gone now.
You can continue to use it via gatsby-cli@4.4.0
and the source itself will live inside the deprecated-packages
folder in the monorepo.
If you've liked the features in gatsby-recipes
and would like to have something similar in the future, feel free to open a feature request in our discussions forum. Thanks!
Notable Bugfixes & Improvements
- A lot of internal dependency updates to some packages. You can check the
CHANGELOG.md
file in each packageโs folder for the details. - If you want to know how to enable Content Sync in your source plugin, you can read the updated guide now.
gatsby
- When using the File System Route API and SSR rendering mode, the routing between individual pages and a catch-all splat route was not correctly resolved. The
findPageByPath
function was updated to use another algorithm to find the correct page, via PR #34070 - Remove unused exports from query engine, via PR #33484
- Resolve
createNode
promise when LMDB datastore is ready to fix issues where nodes were not created, via PR #34277 - Reorder
<head>
tags so that e.g. large stylesheets don't block parsers from getting meta tags, via PR #34030
- When using the File System Route API and SSR rendering mode, the routing between individual pages and a catch-all splat route was not correctly resolved. The
gatsby-plugin-preact
: Fix exports resolution to get it working with Gatsby 4, via PR #34337gatsby-source-contentful
:gatsby-cli
: Make--inspect-brk
work with specified port, via PR #34242gatsby-source-filesystem
: Replace special filename characters, via PR #34249
Contributors
A big Thank You to our community who contributed to this release ๐
- iChenLei
- axe312ger: fix(gatsby-source-contentful): fix base64 aspect ratio PR #33533
- cassiebeckley: chore(gatsby-transformer-screenshot): Update old name PR #34285
- ollybenson: docs: fix typo in gatsby-image PR #34300
- fagiani: docs: Match egghead.io video instructions PR #34315
- AnilSeervi
- varghesejose2020: chore(docs): Update localization doc PR #34378
- SMony-L: chore: Fix typo PR #34349
- seanparmelee: chore(docs): Fix links to shared layout component PR #34330
- tlgimenes: fix(gatsby): Wrong route resolved by findPageByPath function PR #34070
December 14 2021
Welcome to gatsby@4.4.0
release (December 2021 #1)
Key highlights of this release:
- Detect Node Mutations - Opt-in Diagnostic Mode
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.
Detect Node Mutations
In Gatsby 4 LMDB became the default data store. It allows Gatsby to execute data layer related processing outside of the main build process and enables Gatsby to run queries in multiple processes as well as support additional rendering strategies (DSG and SSR).
In a lot of cases that change is completely invisible to users, but if you're a source plugin author or have your own custom source plugin you might be affected by this.
Direct node mutations in various API lifecycles are not persisted anymore. In previous Gatsby versions it did work because source of truth for the data layer was directly in Node.js memory, so mutating node was in fact mutating source of truth. Common errors when doing swap to LMDB
will be that some fields don't exist anymore or are null
/undefined
when trying to execute GraphQL queries.
With this release you're now able to detect node mutations and debug the aforementioned cases of null
/undefined
. Learn more about this at Debugging Missing or Stale Data Fields on Nodes.
Notable bugfixes & improvements
- A lot of internal dependency updates to each package. You can check the
CHANGELOG.md
file in each packageโs folder for the details gatsby-plugin-emotion
: Use correct babel preset withjsxRuntime
option (gatsby-config.js
), via PR #34085gatsby
: Allow external systems to setup tracing for builds, via PR #34204gatsby-source-filesystem
: Ensure that thefastq
concurrency
parameter is of the correct type, via PR #34186gatsby-plugin-manifest
: Consider path prefix when getting localized manifest, via PR #34174gatsby-cli
: Fix for--inspect-brk
, via PR #34242
Contributors
A big Thank You to our community who contributed to this release ๐
November 30 2021
Welcome to gatsby@4.3.0
release (November 2021 #3)
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.
Content Sync Improvements
The createNodeManifest action gets a performance boost.
We no longer hash page-data.json files and include that hash in node manifest files in order to determine if that page-data has deployed. Instead we include the manifest id passed to createNodeManifest within the page-data file as a more performant way to check if the corresponding data for a data update has deployed and become publicly available online. This allows us to create more node manifest files than before, making services such as Content Sync more reliable, in more situations.
We've also added a new updatedAtUTC argument to the action, passing a date here allows Gatsby to determine wether or not the node manifest file should be created or not. If the date is older than 30 days (by default) the node manifest will not be created. Users can change this default by setting the NODE_MANIFEST_MAX_DAYS_OLD
environment variable to any number of days.
Use renderToPipeableStream React 18 API
Gatsby switched to renderToPipeableStream
instead of pipeToNodeWritable
from older React 18 alpha versions. Now with React 18 beta and the new alphas renderToPipeableStream
is the recommend API for Server Side Rendering.
Notable bugfixes & improvements
gatsby
: Don't retain logs in Gatsby Cloud, via PR #34045gatsby-source-shopify
: Fix peerDependencies for gatsby-plugin-image via PR #34044gatsby
: Reduce cost of sourcing after the initial, via PR #33692
Contributors
A big Thank You to our community who contributed to this release ๐
- laurenskling: fix(gatsby-source-graphql): Use default export from node-fetch PR #33977
- SaloniThete
- gabxyz: chore(gatsby): add
getCache
helper toNodePluginArgs
PR #33984 - ashhitch: chore(gatsby): Add
getServerData
to PageProps type PR #34003 - buzinas: fix(gatsby-plugin-manifest): Delete
cacheDigest
from generated webmanifest PR #33966 - pranav0281999: feat(gatsby-plugin-nprogress): Replace
nprogress
withaccessible-nprogress
PR #34038 - apotheosistech: Bump timeout from 15s to 30s PR #34035
- obax: chore(docs): Update webpack fs resolution PR #34056
- axe312ger: chore(gatsby-source-contentful): Add note to Rich Text docs PR #34083
- joernroeder: fix(gatsby-transformer-json): Fix high memory consumption PR #34084
- arthuranteater: chore(docs): Add missing permission for Shopify Admin API PR #34091
November 16 2021
Welcome to gatsby@4.2.0
release (November 2021 #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.
gatsby-source-contentful
v7
We're releasing a new major version of gatsby-source-contentful
as the support for gatsby-image
is dropped in favour fo the superior successor gatsby-plugin-image
. Read the Migrating from gatsby-image to gatsby-plugin-image guide to learn more. The PR #33528 implemented this change.
You can also use AVIF
images with Contentful now as the PR #33903 added support for this image format -- use the new gatsby-plugin-image
to use it.
getServerData
improvements
A couple of improvements were made to the new Server-Side Rendering API inside Gatsby:
-
The response headers are now also applied during
gatsby develop
, via PR #33810 -
You can (and should) use
process.env.*
environment variables insidegetServerData
, via PR #33690 -
The status code returned by
getServerData
is respected now, via PR #33914. Please use this syntax (see reference guide):export async function getServerData() { return { status: 200, headers: {}, props: {}, } }
Framework Version Support
You can find the support plans for the major versions of Gatsby on the newly created page Gatsby Framework Version Support.
Notable bugfixes & improvements
- A lot of internal dependency updates to each package, e.g. bumping
sharp
to0.29.2
. You can check theCHANGELOG.md
file in each package's folder for the details gatsby
: Test files inside thesrc/api
(Gatsby Functions) directory are now excluded by default, via PR #33834gatsby-source-wordpress
:gatsby-core-utils
: Add retry on HTTP status codes tofetchRemoteFile
, via PR #33461- Content Sync:
- Content Sync is a Gatsby Cloud feature for improving the Preview experience for content authors. You can read more about it in the conceptual guide
gatsby-source-drupal
is prepared for Content Sync, via PR #33683- Update the Creating Pages documentation, via PR #33848
Contributors
A big Thank You to our community who contributed to this release ๐
- shreemaan-abhishek: chore(docs): fix issues in 0009-telemetry RFC PR #33829
- tonyhallett
- jstramel: searcParams missing from urls PR #33861
- axe312ger
- labifrancis: chore(gatsby-plugin-gatsby-google-analytics): Highlight the plugin we recommend PR #33901
- bytrangle: chore(docs): remove slug generation from MDX doc PR #33915
- Swarleys: feat(contentful): modifying schemes to add support for AVIF images PR #33903
- InfamousStarFox: Fixes incorrect link "programmatically creating pages from data" PR #33964
- SaloniThete: chore: Typo in BUG_REPORT PR #33971
- henryjw: chore(docs): Update client-only doc PR #33967
November 02 2021
Welcome to gatsby@4.1.0
release (November 2021 #1)
Key highlights of this release:
- Support for Deferred Static Generation in File System Route API
- JSX Runtime Options in
gatsby-config.js
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.
Support for Deferred Static Generation in File System Route API
With the introduction of Deferred Static Generation (DSG) (What is DSG?) you can defer non-critical page generation to the first user request. Currently, you can only achieve this by setting defer: true
in the createPage
action.
You're now also able to use DSG with File System Route API. For this we're introducing a new API inside File System Route templates that we'll continue to improve: A config()
function. You'll be able to use it like this:
import React from "react"
import { graphql } from "gatsby"
export default function Component(props) {
return <pre>{JSON.stringify(props, null, 2)}</pre>
}
export async function config() {
// Get all posts that were created before 2020-10-31
const { data } = graphql`
{
oldPosts: allMarkdownRemark(
filter: { frontmatter: { date: { lt: "2020-10-31" } } }
) {
nodes {
fields {
slug
}
}
}
}
`
// Create a Set for easier comparison/lookup
const oldPosts = new Set(data.oldPosts.nodes.map(n => n.fields.slug))
// Return a function that when called will return a config for FS route pages
// (right now only `defer` is supported)
return ({ params }) => {
return {
// Defer pages older than 2020-10-31
defer: oldPosts.has(params.fields__slug),
}
}
}
export const pageQuery = graphql`
query BlogPost($id: String!) {
markdownRemark(id: { eq: $id }) {
html
frontmatter {
title
date(formatString: "MMMM DD, YYYY")
description
}
}
}
`
In the async function config()
you can use GraphQL to query the data layer you're used to. But you don't have to -- you can also use regular JavaScript or skip the outer function completely. config()
must return a function itself in which you get params
as an argument. params
is the same object you also get as props.params
in the page component (see params documentation), e.g. src/pages/{Product.name}.js
has params.name
.
Here's a minimal version of config()
that defers every page of the current File System Route template:
export async function config() {
return ({ params }) => {
return {
defer: true,
}
}
}
You can read the API reference or the DSG guide to learn more.
Please note: As DSG has no effect in gatsby develop
at the moment you can only test config()
in gatsby build
right now. As this is the first iteration of the config()
API we're looking for feedback!
gatsby-config.js
JSX Runtime Options in You now can configure the jsxRuntime
and jsxImportSource
inside gatsby-config.js
:
module.exports = {
jsxRuntime: "automatic",
jsxImportSource: "@emotion/react",
}
Setting jsxRuntime
to automatic
allows the use of JSX without having to import React (learn more in the official blog post). You can use the jsxImportSource
option to set which package React should use as underlying JSX transformer.
Notable bugfixes & improvements
- We've improved our Creating a Source Plugin guide to account for changes made in v4
gatsby-source-contentful
: ThedownloadLocal
option is working correctly again, via PR #33715gatsby-plugin-image
:gatsby
:gatsby-remark-images
: Fix figure caption generation when usingGATSBY_EMPTY_ALT
, via PR #30468gatsby-plugin-sharp
: PassfailOnError
to sharp when usinggatsby-plugin-image
, via PR #33547
Contributors
A big Thank You to our community who contributed to this release ๐
- bicstone: chore(docs): Fix links to old tutorial docs PR #33605
- shreemaan-abhishek: docs(gatsby): fix grammar issue PR #33525
- marijoo: chore(gatsby-source-faker): Update README PR #33606
- tonyhallett
- codejet: chore(gatsby-remark-images): Fix typo in README PR #33646
- desirekaleba: chore(starters): Fix link to old GraphQL tutorial PR #33654
- abhirajkrishnan: chore(docs): Fix Broken Link For Headless CMS Definition PR #33645
- Mrtenz: chore(docs): NodeModel.findAll returns a Promise PR #33653
- sarvesh4396: chore(gatsby-source-wordpress): Fix typos PR #33639
- erikbgithub: chore(gatsby-plugin-mdx): Fix grammar PR #33485
- Simply007: chore(docs): Improve v3->v4 migration guide on
GatsbyIterable
PR #33666 - Dgiordano33: chore(examples): Swapped to deploy on Gatsby Cloud PR #33686
- raresportan: fix(gatsby-plugin-image): GatsbyImage not displaying image in IE11 PR #33416
- TommasoAmici: fix(gatsby-plugin-mdx): mkdirp needs to be listed as a direct dependeโฆ PR #33724
- redabacha: fix(gatsby-plugin-sharp): pass failOnError to sharp in getImageMetadata PR #33547
- herecydev: feat(gatsby): Add JSX Runtime options to
gatsby-config.js
PR #33050 - nategiraudeau: fix(gatsby-remark-images): GATSBY_EMPTY_ALT figcaption generation PR #30468
- Rutam21: chore(docs): Improve "Adding a service worker" PR #33737
October 21 2021
Welcome to gatsby@4.0.0
release (October 2021 #1).
We've released Gatsby 3 in March 2021 and now have a lot of exciting new features for Gatsby 4! Weโve tried to make migration smooth. Please refer to the migration guide and let us know if you encounter any issues when migrating.
Key highlights of this release:
- Parallel Query Running - up to 40% reduction in build times
- Deferred Static Generation (DSG) - defer page generation to user request, speeding up build times
- Server-Side Rendering (SSR) - pre-render a page with data that is fetched when a user visits the page
Major dependency updates:
Also check out notable bugfixes and improvements.
Bleeding Edge: Want to try new features as soon as possible? Install gatsby@next
and let us know
if you have any issues.
Previous release notes for 3.14
Breaking Changes
If you're looking for an overview of all breaking changes and how to migrate, please see the migrating from v3 to v4 guide.
Overview Video
Prefer video over text? No problem! Learn more about all the new features (+ demo) and what we'll work on beyond Gatsby 4 in the video below:
Parallel Query Running
Query running is the portion of the Gatsby build process that happens after your site's content has been sourced from the various content sources configured for your Gatsby site. This step is understandably one of the more expensive portions of the build process because it's where all of the data is being extracted into the corresponding page data required to efficiently generate the actual website pages that your visitors interact with.
We've rearchitected the Gatsby data layer (not a trivial thing to do!) to allow page queries and static queries to occur in parallel, leading to a 40% reduction in build times for some sites! This innovation starts with allowing for parallel content queries, but positions Gatsby for a number of interesting use cases (imagine what you can do with a portable data layer ๐ค).
How does it work?
The crux of the matter, regarding query running, is that Gatsby had historically utilized Redux as its internal, in-process data store. Now, our existing datastore is very fast because itโs an in-memory data store, but it carries a key limitation that was hindering our ability to substantially optimize the Gatsby build process: Itโs only accessible via the current thread/process. This means that the Gatsby build process, and more specifically the query running portion of that process, could not be shared across CPU cores.
The team evaluated a collection of strategies for optimizing and decoupling the data layer in order to allow cross-cpu, and possibly cross-machine coordination of content queries and landed on the node.js implementation of LMDB: lmdb-store as the foundation for the architecture update. lmdb-store
affords incredibly efficient data access, focused on fast read operations, which makes it suitable for the Gatsby userโs use case.
The Gatsby main process now coordinates content query workers with the now-shared data store. Therefore, you will now have n-1
query workers when building your Gatsby site, where n is the total number of CPUโs provisioned for your Gatsby Cloud (or other CI/CD host) site.
You can learn more about Parallel Query Running in the video below:
Deferred Static Generation (DSG)
When a Gatsby site uses Deferred Static Generation, it means they are deferring or delaying the building of particular pages on their website until runtime. Once a delayed page is requested (visited) by a site visitor it will be built on the fly in the same manner as any Server-Side Rendered page, but it will now persist as a static build on the edge. So, for that first, and only first user on a deferred page โ they will get the performance of any other SSR page, but each and every user after that will receive a completely statically generated page.
For example, imagine you have an archive of old articles that no longer receive significant traffic. There is no practical reason to generate them on each build (and thus delay the delivery of fresh articles). In this case, you may choose to defer the generation of old pages, and Gatsby will skip them during the build step.
Due to the introduction of lmdb-store
as the data store the generation of DSG pages happens with a snapshot of all the data at buildtime which means no APIs need to be requested on runtime and the data will be the same for everyone. Gatsby generates an engine internally that can build pages with the provided data, meaning that each of your deploys will be atomic as both page generation & data for each page is saved. Once you update your content, Incremental Builds only updates the necessary pages and updates the data store.
You can learn more about the different rendering options or read the How-To on using DSG.
Server-Side Rendering (SSR)
Gatsby 4 now supports Server-Side Rendering, giving developers the choice of generating content at either build time, as with static-site generation, or at runtime. With Server-Side Rendering, teams can now run more effective A/B tests, personalize content, and more all while still using the Gatsby framework.
Server-Side Rendering is a method of content rendering in which each web page is served to a site visitor at runtime, meaning that a portion of the build process happens on each page request. Because the content is rendering during runtime, visitors will always get the latest version of content directly from the server โ though they may have to wait a few seconds for it display.
For example, imagine you are building a site with user reviews. You want those reviews to be immediately indexed by search engines as soon as they are posted, so client-side rendering is not an option.
You can learn more about the different rendering options or read the How-To on using SSR.
Node 14
We are dropping support for Node 12 as a new underlying dependency (lmdb-store
) is requiring >=14.15.0
. See the main changes in Node 14 release notes.
Check Nodeโs releases document for version statuses.
Pages Output in CLI
With our new rendering options you now can have different kinds of pages in your project. We've added an output for gatsby build
that tells you exactly which pages are SSG, DSG, SSR, or a Gatsby Function.
Notable bugfixes and improvements
gatsby
: Reduce page-renderer size, via PR #33051gatsby
: Add queue to prefetch, making it less eager. Via PR #33530gatsby-source-wordpress
: Usegatsby-plugin-image
, via PR #33138
Contributors
A big Thank You to our community who contributed to this release ๐
- merceyz: fix: add missing dependencies PR #31837
- actuallyatiger: chore(docs): Update GitHub Pages doc PR #29031
- acbramley: Document filtering temporary files PR #32048
- jabrks: fix(gatsby): Don't bundle moment locale files PR #33092
- nagiek: feat(gatsby): Add aggregation resolvers to group PR #32533
- aleksanderantropov
- bartveneman: docs(gatsby-plugin-gatsby-cloud): fix typo: asterix -> asterisk PR #33135
- rudouglas: chore(gatsby): add environment variable for setting tracing config file PR #32513
- herecydev: feat(gatsby-plugin-styled-components): Add ability to disable vendor prefixes PR #33147
- minimalsm: docs: Fix broken link on Getting Started with MDX page PR #33148
- angeloashmore
- axe312ger
- fix(contentful): createUrl now enforces https protocol PR #33236
- feat(gatsby-source-contentful): move types into createSchemaCustomization PR #33207
- chore(gatsby-source-contentful): download assets via gatsby-core-utils PR #33482
- chore(gatsby-source-contentful): clean up code base and introduce es-module syntax PR #33213
- fbuireu: chore(gatsby-source-contentful): Fix RichText example PR #33261
- alvis: fix(gatsby): correct the definition for getNode PR #33259
- Xenonym: chore(docs): fix typo in site performance guide PR #33294
- labifrancis: chore(docs): Improve Shopify guide PR #33298
- aaronadamsCA: chore(gatsby): Fix static query types, document useStaticQuery PR #33322
- crstnre: docs: fix "(r)esource congestion" PR #33392
- NikSchaefer: chore(docs): Fix Grammar Issue PR #33408
- torn4dom4n: chore(gatsby-plugin-manifest): Update README links PR #33406
- orsi: chore(gatsby-source-contentful): Improve README on rich text ref PR #33401
- ondrabus: chore(docs): Update Kentico Kontent references PR #33411
- samouss: fix(gatsby): postcss-svgo - remove plugin removeAttrs PR #33266
- raresportan: fix(gatsby): replace checks for .cache/json with checks for .cache/caches-lmdb PR #33431
- amalitsky: chore(gatsby-plugin-sitemap): Fix a typo PR #33467
- mrudden: chore(docs): Removed plugin in tutorial not mentioned elsewhere PR #33486
- shreemaan-abhishek
- JSinkler713: docs: Update building-an-ecommerce-site-with-shopify.md PR #33478
- RomerDev: chore(docs): Updating Git adding Remote Origin PR #33314
- joshatoutthink
- tim-hanssen: chore(docs): Add 'Prepr CMS' guide to docs PR #33480
- ParasRawat29: chore(docs): Fix typo in part-7 tutorial PR #33556
- digiturnal: chore(gatsby-plugin-react-helmet): Update Examples PR #33552
- shivangisareen: chore(docs): Update query var in part-7 tutorial PR #33559
- aaronm-git: chore(docs): Clarify SEO component guide PR #33451
- erikbgithub: specifying what actually changed PR #33452
- tonyhallett: chore(gatsby): Add
assetPrefix
toIGatsbyConfig
PR #33575 - psharma-ii: fix(gatsby-source-wordpress): Add steps for
refetch_ALL
PR #33264
September 17 2021
Welcome to gatsby@3.14.0
release (September 2021 #1)
This is the final minor release for gatsby v3. Gatsby v4 beta is already published behind the
next
npm tag and the next stable release will begatsby@4.0.0
. See what's inside!We will keep publishing patches for 3.14.x with hotfixes until
4.0.0
stable is published and at least several weeks after.
Key highlights of this release:
- Better UX for navigation in the middle of deployment
- New developer tools -
createPages
snippet in GraphiQL and new GraphQL capability - Preparations for gatsby v4 - API deprecations; migration guide; docs
- Improvements for
gatsby-source-drupal
- New home for
gatsby-plugin-netlify
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.
Better UX for navigation in the middle of deployment
This release solves a common UX problem with navigation in the middle of deployment. Imagine the following scenario:
- Users loads a page
- New version of the site is deployed
- User tries to navigate to another page with
gatsby-link
However, nothing happens and there are some JS errors in the console.
It happens because paths of JS chunks change with the new deployment and so the old chunks cannot be found. This problem is now addressed in Gatsby automatically. Once we spot this error, the page is hard-reloaded for the user.
This was one of the most upvoted issues in our repo. See PR #33032 for details.
New developer tools
createPages
snippet in GraphiQL
Often, a developer will begin creating the site by examining their data layer in GraphiQL. They will then want to create pages based off of their initial query. For example:
query MyQuery {
allContentfulBlogPosts {
nodes {
id
slug
}
}
}
Usually this will end up with this code in gatsby-node.js
:
const path = require(`path`)
exports.createPages = async ({ graphql, actions }) => {
const { createPage } = actions
const result = await graphql(`
{
allContentfulBlogPosts {
nodes {
id
slug
}
}
}
`)
const templatePath = path.resolve(`PATH/TO/TEMPLATE.js`)
result.data.allContentfulBlogPosts.nodes.forEach(node => {
createPage({
path: NODE_SLUG,
component: templatePath,
context: {
slug: NODE_SLUG,
},
})
})
}
Doing it manually is tedious, but now you can generate this snippet from GraphiQL
and paste to gatsby-node.js
!
See PR #32968 for details.
Added GraphQL aggregation fields to group
Now you can apply max
, min
, distinct
, sum
, group
to grouped nodes. In other words,
a query like this is now possible:
{
allMarkdown {
group(field: frontmatter___authors___name) {
fieldValue
group(field: frontmatter___title) {
fieldValue
max(field: frontmatter___price)
}
}
}
}
See PR #32533 for details.
Preparations for gatsby v4
Actions used for schema customization should not be used in sourceNodes
API anymore:
namely createTypes
, createFieldExtension
and addThirdPartySchema
.
Usage of those actions in sourceNodes
is deprecated as of this release and will break in Gatsby v4.
Also check out the migration guide (work in progress!) for other upcoming breaking changes and don't hesitate to let us know what you think in GitHub discussion.
gatsby-source-drupal
improvements
The plugin got a fair share of improvements and bugfixes for warm and incremental builds:
- Fix GraphQL schema errors and crashes when deleting nodes, PRs #32971, #33099, #33143 and #33181
- Warn on bad webhook format: PR #33079
- Add tracing for full/delta fetches and http requests: PR #33142
gatsby-plugin-netlify
New home for The plugin is moved to https://github.com/netlify/gatsby-plugin-netlify Go check it out for the latest source code.
Notable bugfixes & improvements
gatsby
: make conditional page builds work with static queries, via PR #32949gatsby
: reduce page-renderer size, via PR #33051gatsby
: fix nesting of tracing spans + add docs for OpenTelemetry, via PR #33098gatsby
: don't bundle moment locale files, via PR #33092gatsby
: add environment variable for setting tracing config file, via PR #32513gatsby
: Assign parentSpan to activities that were missing them, via PR #33122gatsby-source-contentful
: fix error "Unable to download asset", via PR #33024gatsby-transformer-sqip
: ensure failed asset downloads do not break build, via PR #33037gatsby-plugin-google-tagmanager
: ability to serve gtm.js from "self-hosted" tagging server, via PR #32733gatsby-plugin-styled-components
: Add ability to disable vendor prefixes, via PR #33147
Contributors
A big Thank You to our community who contributed to this release ๐
-
tackaberry: feat(gatsby-plugin-google-tagmanager): add option for selfHostedOrigin PR #32733
-
ascorbic: chore: add missing
@babel/runtime
dependencies PR #32954 -
Himadu2000: fix(starters): Formats for StaticImage PR #33057
-
actuallyatiger: chore(docs): Update GitHub Pages doc PR #29031
-
jabrks: fix(gatsby): Don't bundle moment locale files PR #33092
-
nagiek: feat(gatsby): Add aggregation resolvers to group PR #32533
-
bartveneman: docs(gatsby-plugin-gatsby-cloud): fix typo: asterix -> asterisk PR #33135
-
rudouglas: chore(gatsby): add environment variable for setting tracing config file PR #32513
-
minimalsm: docs: Fix broken link on Getting Started with MDX page PR #33148
August 31 2021
Welcome to gatsby@3.13.0
release (August 2021 #3)
Key highlights of this release:
- Improved Changelogs - Better structured and easier to read
sharp
v0.29 - Reduced install size, improved encoding time, and improved AVIF image quality- Faster Sourcing for
gatsby-source-drupal
- Speed up fetching data by around 4x - webpack Caching in Development for Everyone - Activating it for all users
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.
Improved Changelogs
While the release notes (like the one you're reading right now) are hand-written and manually published, the changelog of each package we publish has been autogenerated by lerna
in the past and unfortunately the generated output wasn't ideal for users to consume. We know that developers love detailed and accurate changelogs so we decided to replace lerna
behavior with our own tooling. In PR #32884 we added these functionalities and the results are much better.
Take gatsby-plugin-image
changelog as an example:
- Each semver release is its own heading (+ the date it was released)
- If applicable the general release notes are linked
- The PRs are categorized into features, bug fixes, chores, and other
sharp
v0.29
As always, thanks to lovell for maintaining sharp
and sending in the PR #32851 to update sharp
(see sharp
v0.29 changelog) and our image plugins. gatsby-plugin-sharp
now no longer uses imagemin
but native sharp
methods.
You'll get these benefits by upgrading:
- Reduced JPEG, PNG, and AVIF encoding time by up to 50%
- Reduced Gatsby install size/time by ~10% (~19MB smaller on filesystem)
- Improved AVIF image quality and will also work with Chrome 93+
gatsby-source-drupal
Faster Sourcing for You now can significantly speed up sourcing from your Drupal instance if you install JSON:API Extras and enable "Include count in collection queries" (/admin/config/services/jsonapi/extras
). The PR #32883 leverages that information to enable parallel API requests.
For a test site with ~3200 entities and a warm Drupal cache (and no CDN cache), this change dropped sourcing time from 14s to 4s. On a very large production Drupal site (~600k entities), fetching time for a cold build dropped from 2 hours to 30 minutes ๐.
webpack Caching in Development for Everyone
After ramping up the opt-in of this feature to 20% in v3.12 we're now enabling this feature for everyone! So webpack 5 built-in persistent caching is now enabled for everyone both in development and production. It allows webpack to reuse results of previous compilations and significantly speed up those steps.
Notable bugfixes & improvements
gatsby-source-drupal
: Provide an additional config option to specify entities that are not translatable to resolve to default language, via PR #32548gatsby
: Remove theremoveDimensions
option from svgo config, via PR #32834gatsby
: Hashes and anchors in redirects also work in production, via PR #32850gatsby-plugin-gatsby-cloud
: Always create theredirect.json
file even if you remove all redirects, via PR #32845gatsby-remark-images
: Only convert supported image extensions, via PR #32868gatsby-source-wordpress
: Compatibility with Parallel Query Running (PQR), via PR #32779gatsby-core-utils
: Switch from deprecatedauth
option ingot
tousername
/password
, via PR #32665gatsby
: Don't logFAST_DEV
messages multiple times, via PR #32961gatsby
: Fix for "Static Query cannot be found" error, via PR #32949
Contributors
A big Thank You to our community who contributed to this release ๐
-
glennforrest: Fix typo of wether to whether PR #32797
-
apmsooner: feat(gatsby-source-drupal): Default language when non translatable. PR #32548
-
jonniebigodes: chore(docs): Update Storybook guide with Addon PR #32793
-
vanessayuenn: chore(docs): Add title for image-plugin-architecture PR #32803
-
nategiraudeau: docs(gatsby-source-contentful) provide a code example for rendering rich-text embedded assets images PR #32777
-
Dgiordano33: chore(docs): Change Jamstack Article PR #32764
-
SwiftWinds: chore(docs): Fix typo in v3.0 release notes PR #32844
-
ashiishme: chore(docs): Remove outdated information from Theme Guide PR #32849
-
facundojmaero: chore(docs): Fix typo in part 5 of the tutorial PR #32854
-
torn4dom4n: chore(docs): Fixes typo in tutorial part 4 PR #32859
-
lovell: feat(gatsby-plugin-sharp): reduce encoding time and install size PR #32851
-
frankpengau: chore(docs): Update Gallery example in tutorial part 2 PR #32872
-
moinulmoin: chore(docs): Fix typo in tutorial part 6 PR #32866
-
Mike-Dax: chore(gatsby-remark-images): Only convert supported image extensions PR #32868
-
barrymcgee: Update docs on building eCom with Shopify to work with latest versions PR #32884
-
jfrosch: chore(docs): Update wording for "using-web-fonts" PR #32902
-
satrix321: fix(gatsby-core-utils): Switch
auth
option from got to username/password PR #32665
August 17 2021
Welcome to gatsby@3.12.0
release (August 2021 #2)
Key highlights of this release:
- Ramping up support for webpack caching in development - opt-in 20% of users
- Improvements to
gatsby-source-shopify
- Add compat for breaking change in Shopify's API - Improvements to
gatsby-source-wordpress
- Support for generating WebP images in HTML fields
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.
Ramping up support for webpack caching in development
We added caching support for webpack in development in 3.10 and it's gotten a fair bit of usage since then.
With this release we opt-in 20% of users for a final test before the full release.
gatsby-source-shopify
Improvements to Our gatsby-source-shopify
plugin received multiple bug fixes and improvements in this release. If you use Sales Channels you might have gotten wrong results in the past. The filter for it was fixed in PR #32674. With PR #32710 the plugin will also only query location fields when you activate locations since it requires additional permissions. If you're using Gatsby Cloud production builds will now be prioritized over content previews and branch previews (via PR #32144).
Shopify recently deprecated the valueType
field on metafields. We've updated the API version to 2021-07
, added the new type
field and aliased the old valueType
to this new field. So the breaking change is backwards compatible, see PR #32774 for all details.
gatsby-source-wordpress
Improvements to Also gatsby-source-wordpress
received some fixes and foundational work for future improvements. A bug was fixed for Gatsby Preview when e.g. you use the duplicate-post
plugin in WordPress (via PR #32488). The PR #32679 fixed the issue that a low perPage
option could prevent some MediaItem
nodes from being fetched.
You can set the html.generateWebpImages
option now to true
to generate WebP images for images in HTML fields. While this will increase the time it takes to generate images it can improve your performance scores since all major browsers support WebP now.
Notable bugfixes & improvements
- Dependency Updates: The Renovate bot updated a bunch of dependencies (see full changelog for more details), most notably:
eslint
(7.28.0 to 7.32.0),styletron-react
(5.2.7 to 6.0.1) gatsby-plugin-sitemap
: Add warning that oldexclude
option is obsolete, via PR #32509gatsby
: Worker support forgatsby develop
, via PR #32432gatsby-source-contentful
: base64 previews now reflect all query options, via PR #32709gatsby-remark-image-contentful
: Show useful error message for files that can not be rendered as image, via PR #32530gatsby
: Speed up "Writing page-data" step by ~10%, via PR #32763
Contributors
A big Thank You to our community who contributed to this release ๐
-
Sayanta66: chore(starters): Update links in README-template PR #32549
-
orta: fix(gatsby-plugin-sitemap): Add plugin options forbidden for deprecated
exclude
PR #32509 -
mattmortek: fix(gatsby-source-shopify): update method of generating published_status when salesChannel parameter is used PR #32674
-
nemophrost: fix(gatsby): Worker support in fast-refresh-module PR #32432
-
kingkero: :construction: Check that node is not falsey PR #32488
-
vi-nastya: feat(gatsby-source-wordpress): generate webp images PR #30896
-
RocketLL: chore(gatsby): fix typo in string enum member PR #32721
-
ascorbic: feat(gatsby): add env flag to disable lazy function compilation in develop PR #32707
-
rburgst: fix(wordpress): ensure all file links are rewritten PR #32679
-
SaloniThete: fix(examples): Correct typo in comment PR #32762
-
redabacha: fix(gatsby-plugin-image): only log missing plugin error in development PR #32335
-
nategiraudeau: chore(docs): Improved getSavedScrollPosition API desc PR #32765
-
herecydev: fix(gatsby): Wrap performance mark in check PR #32778
-
VallyPepyako: chore(docs): Fix typo PR #32784
August 03 2021
Welcome to gatsby@3.11.0
release (August 2021 #1)
Key highlights of this release:
- Improvements to Parallel Query Running - Better performance and more configurable
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.
Improvements to Parallel Query Running
In case you missed it, in 3.10 we've added experimental support for Parallel Query Running. Depending on your site you will see dramatic improvements in gatsby build
performance. We've moved more information into LMDB, fixed a bug and optimized how we merge the state of the workers. You can also force the chunk size for each worker now by setting the GATSBY_PARALLEL_QUERY_CHUNK_SIZE
environment variable.
To learn more about Parallel Query Running head to the previous release notes.
Please give it a try and report back in the PQR GitHub Discussion. We really appreciate any feedback!
Notable bugfixes & improvements
gatsby
: Display message about unfit flags found ingatsby-config.js
per PR #32394gatsby
: Correct pagination logic (fixing a regression) per PR #32496gatsby-source-shopify
: Add a query forShopifyLocation
andShopifyInventoryLevel
per PR #32450gatsby-plugin-mdx
: Performance improvement for a specific usage scenario (multiple GraphQL fields that require MDX processing) per PR #32462gatsby-source-wordpress
: Fetch referenced media items during single node updates per PR #32381gatsby-plugin-gatsby-cloud
: Fix bug where Incremental Builds on Gatsby Cloud would result in downloading duplicate JavaScript assets per PR #32535
Contributors
A big Thank You to our community who contributed to this release ๐
- angeloashmore: fix(gatsby): correct hasNextPage pagination info when resultOffset is provided PR #32319
- jvidalv: chore(docs): modified file-mock path for typescript config on unit-teโฆ PR #32390
- kik-o: chore(docs): SEO remove typos & outdated information PR #32433
- farhan443: chore(docs): Fix a minor typo "with" > "will" PR #32491
- nyedidikeke: chore(docs): Fix typo in documentation for assetPrefix PR #32499
- xugetsu: chore(docs): Fix typo in File System Route API doc PR #32517
July 20 2021
Welcome to gatsby@3.10.0
release (July 2021 #2)
Key highlights of this release:
- Experimental: Parallel Query Running - Improves time it takes to run queries during gatsby build
- Experimental: webpack persistent caching for
gatsby develop
- significantly speed up start of webpack server
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.
Experimental: Parallel Query Running
Gatsby's build process is composed of multiple steps (see our documentation for more details) and one step that will increase in time with more and more pages/nodes is query running. You're seeing this step as run static queries
and run page queries
in your build log.
This step currently only runs in a singular process and the goal of Parallel Query Running is to spread out the work to multiple processes to better utilize available cores & memory. We're using gatsby-worker
(highly inspired by jest-worker
) and lmdb-store
to accomplish this. In Gatsby v3.7 we've added support for LMDB in Gatsby and are now leveraging this new data storage option to enable communication between the main process and the workers.
Depending on the type of queries you use you will see dramatic improvements in performance. You can try out different types of queries (and expected results) with the query-filters-sort benchmark. Toggle the feature flag for a before/after comparison.
Here are two examples:
- Fast
eq-uniq
filter withGATSBY_CPU_COUNT=5 NUM_NODES=100000 NUM_PAGES=10000 FILTER=eq-uniq TEXT=1
.- Before:
run page queries - 3.787s - 10001/10001 2641.07/s
- After:
run queries in workers - 3.445s - 10001/10001 2903.34/s
- For the already fast
eq
filters you will see smaller improvements compared to the slower filters like...
- Before:
- Slow
gt
filter withGATSBY_CPU_COUNT=5 NUM_NODES=10000 NUM_PAGES=10000 FILTER=gt TEXT=1
:- Before:
run page queries - 41.832s - 10001/10001 239.07/s
- After:
run queries in workers - 15.072s - 10001/10001 663.57/s
- Huge improvements for more complex queries or filters that are not "Fast Filters"
- Before:
To try it out in your own site, please make sure that you're using Node v14.10 or later. Install lmdb-store
as a dependency:
npm install lmdb-store
Then enable the config flag in your gatsby-config.js
:
module.exports = {
flags: {
PARALLEL_QUERY_RUNNING: true,
},
}
Please share your results, findings, and feedback in the PQR GitHub Discussion. You'll also be able to read about known/common pitfalls there and possible solutions.
gatsby develop
Experimental: webpack persistent caching for After rolling out webpack 5 persistent caching for production builds in Gatsby v3.8 we're now beginning the gradual rollout of it for gatsby develop
. It greatly improves the startup time of the development server.
To use it, add a flag to your gatsby-config.js
:
module.exports = {
flags: {
DEV_WEBPACK_CACHE: true,
},
}
If you're already using the FAST_DEV
flag you'll be using it automatically once you update to Gatsby v3.10. Please share your feedback in the GitHub Discussion.
Notable bugfixes & improvements
gatsby
: Updatepostcss
to 8.3.5 to remove deprecation warning on Node v16.gatsby
: SwitchedcreateRoot
tohydrateRoot
. Please note, this only applies if you use React 18 in Gatsby.gatsby-source-wordpress
: Check preview URL earlier and give better feedback, via PR #32251.gatsby
: Passsearch
andhash
towindow.location
to final URL of redirect and after the service worker updated, via PR #32334 and PR #32323.gatsby
: Avoid theUNHANDLED REJECTION write EPIPE
error when usingCtrl + C
, via PR #32311 and PR #32356.gatsby
: When agatsby build
fails on e.g. missing data it now prints thepage-data.json
file for this page to give more context on what's missing, via PR #32301.gatsby-source-contentful
: Support image corner radius from Image API, via PR #32333.gatsby-source-contentful
: Supportmetadata.tags
property, via PR #31746.
Contributors
A big Thank You to our community who contributed to this release ๐
- RapTho: Wrong post ids in example author name filter PR #32191
- anselm94: chore(docs): Update Storybook guide to v6 PR #31653
- SarthakC: fix: added missing parentheses in creating a source plugin tutorial PR #32259
- emmanuelgautier: fix(gatsby-plugin-gtag): replace google analytics domain with google tag manager PR #31036
- nellaparedes: fix(gatsby): Pass search/hash to location after swUpdated PR #32323
- karlhorky: Avoid UNHANDLED REJECTION error on ctrl-C PR #32311
- weronikadominiak: docs(contributing): update docs with info about translations being on hold (#31883) PR #32328
- cabutler10: chore(docs): Fix typo in apollo/client npm package name PR #32345
- ezeYaniv: chore(docs): Update building-a-theme to latest Theme UI PR #32357
- SonnyBrooks: chore(docs): Correct JavaScript spelling PR #32368
- axe312ger
July 06 2021
Welcome to gatsby@3.9.0
release (July 2021 #1)
Key highlights of this release:
- React 18 - New Suspense SSR Architecture - Enables SSR support for Suspense when using React 18 (Alpha)
- Shopify App for Gatsby Cloud
- gatsby-source-contentful - quality of life improvements
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.
React 18 - New Suspense SSR Architecture
We're happy to announce support for the new React 18 server architecture during build time.
When installing react@alpha
and react-dom@alpha
, you automatically opt into the new
pipeToNodeWritable
renderer.
Now you're able to use Suspense
and React.lazy
on the server as well.
Shopify app for Gatsby Cloud
Following the brand-new Shopify source plugin published in the previous release, this release brings Gatsby Cloud to Shopify App Store.
Install Gatsby Cloud from the app store to quickly connect your Shopify store. Choose an existing project youโve been working on or get up and running the Shopify starter in seconds.
gatsby-source-contentful
Quality of life improvements to - Don't ignore errors thrown when fetching assets via PR #24288
- Re-enable support for gif images via PR #31986
- Force base64 previews to be formatted as JPEG via PR #32155
Notable bugfixes & improvements
gatsby
: Bumpedexpress-graphql
to0.12.0
to only have graphql v15 installed via PR #31178gatsby
: Prevent generation of polyfill bundle if not needed via PR #31993gatsby-plugin-netlify-cms
: Limit global styles to preview pane only via PR #32106gatsby
: Add activity for writing outpage-data.json
files via PR #31987gatsby
: Fixed a bug in develop when a new page is not available with HMR via PR #32189gatsby
: Fixed a bug with filtering by custom interface fields (affecting WordPress plugin) via PR #32195gatsby
: Performance improvements to queries withlimit
/skip
via PR #32135
Contributors
A big Thank You to our community who contributed to this release ๐
-
MichaelDeBoey: chore: Delete profile.js PR #31997
-
shanekenney: fix(gatsby-source-contentful): Don't ignore errors thrown when fetching assets PR #24288
-
kdichev: chore(gatsby-plugin-image): Add duotone, grayscale, rotate and trim options in transformOptions TS type PR #31926
-
stanulilic: docs: Fix typos in tutorial 4 PR #31891
-
alvis: fix(gatsby): correct args type in createParentChildLink PR #32139
-
justinyaodu: chore(gatsby-plugin-mdx): Add comment why rehype-slug is required PR #32128
-
browniebroke: fix(gatsby): leave
xmlns
element when optimizing SVGs PR #32123 -
erezrokah: fix(plugin-netlify-cms): exclude cms.css from index.html PR #32106
-
herecydev: feat(gatsby): Prevent generation of polyfill bundle if not needed PR #31993
-
alisson-suzigan: chore(gatsby): Migrate schema-composer.js to TS PR #31998
-
gijsbotje: chore(docs): Fix environment variables example PR #32169
-
AntoineGRoy: chore(starters): Add a Gatsby CLI instructions link PR #32158
-
Pearce-Ropion: chore(netlify-cms): Bump webpack version to match gatsby PR #32175
-
jamesaucode: chore(gatsby): Bumped express-graphql to v0.12.0 PR #31178
June 22 2021
Welcome to gatsby@3.8.0
release (June 2021 #2)
Key highlights of this release:
- React 18 - Alpha - React 18 Alpha is available in Gatsby
gatsby-source-shopify
v5 - brand new version- Web Vitals Tracking - Analytics Plugins now support tracking Web Vitals
- webpack caching - built-in persistent caching activated for everyone
- Improvements to Drupal integration โ Sourcing is up to 30%+ faster and more reliable
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.
React 18 - Alpha
Gatsby supports React 18 Alpha. It's still very early days but we like to be ahead of the pack. You can use startTransition
and stateBatching
today by installing react@alpha
& react-dom@alpha
. We love to get feedback in the Umbrella Discussion.
gatsby-source-shopify
v5
Gatsby's new Shopify integration which we announced at GatsbyConf earlier this year is now generally available.
- Incremental data updates are now 16x faster than previous versions
- v5 uses Shopify's Admin API and bulk operation to overcome API rate limits of the Storefront API
- Gatsby Cloud now offers Quick Connect for Shopify
Web Vitals Tracking
We've added support for tracking Web Vitals to gatsby-plugin-google-analytics
& gatsby-plugin-google-tagmanager
by using the web-vitals
package (PR #31665).
The plugins now send three metrics:
- Largest Contentful Paint (LCP): measures loading performance. To provide a good user experience, LCP should occur within 2.5 seconds of when the page first starts loading.
- First Input Delay (FID): measures interactivity. To provide a good user experience, pages should have a FID of 100 milliseconds or less.
- Cumulative Layout Shift (CLS): measures visual stability. To provide a good user experience, pages should maintain a CLS of 1 or less.
You can activate the tracking in your gatsby-config.js
by setting enableWebVitalsTracking
to true
.
webpack caching
In the previous 3.7 release we started a gradual rollout of webpack 5 built-in persistent caching. It allows webpack to reuse results of previous compilations and significantly speed up compilation steps. With Gatsby v3.8 it's now enabled for everyone.
Drupal integration
gatsby-source-drupal is now a lot faster and more reliable when sourcing data from Drupal. We switched to use Got for HTTP requests plus added an optimized http agent and http/2 support.
Notable bugfixes & improvements
gatsby-plugin-sitemap
: Properly throw error on missing siteUrl via PR #31963gatsby
: Removed outdated ESLint rulesjsx-a11y/no-onchange
andjsx-a11y/accessible-emoji
via PR #31896
Contributors
A big Thank You to our community who contributed to this release ๐
- prajapati-parth: docs(gatsby-plugin-image): fix minor typo PR #31751
- cometkim: fix(gatsby): fix signature for latest experimental version of react-dom PR #31750
- lqze: chore(docs): Update gatsby-plugin-image typos PR #31790
- dhrumilp15: chore(docs): Update digitalocean certbot instructions PR #31796
- DanailMinchev: chore(docs): Add
testEnvironment
to RTL doc PR #31793 - gmanfunky: chore(docs): Add link to latest migration doc PR #31798
- lee1409: fix(gatsby-remark-copy-linked-files): replace checking parent node type to 'dir' PR #31780
- smurrayatwork: Fixes bug where datum have no attributes and attributes have no langcode. PR #31864
- ThyNameIsMud: fix(gatsby-source-wordpress) Use send property for timeout (#31737) PR #31847
- eligundry: fix(gatsby-source-contentful): improve error message when dominant color can't be generated PR #31879
- NikSchaefer: chore(docs): Fix grammar issue PR #31937
- amaaniqbal: chore(docs): Fix multiple grammar issues PR #31946
- nikolaik: docs: Fix missing commas in plugin-image defaults PR #31961
June 08 2021
Welcome to gatsby@3.7.0
release (June 2021 #1)
Key highlights of this release:
- Functions - Now generally available
- webpack caching - Starting gradual rollout
- Yarn 2 (PNP) support
- New API for source plugins:
createNodeManifest
- Experimental: Node persistence in LMDB - Lower peak memory usage
gatsby-remark-images
: async image decoding by default
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.
Functions
Functions, first class support for serverless functions is now generally available in this version of Gatsby. Learn more about functions in the documentation and examples.
If you've been using it as an experimental feature for a while, you no longer need to include the experimental FUNCTIONS
flag to use it after this update.
webpack caching
webpack 5 introduced built-in persistent caching. It allows webpack to reuse results of previous compilations and significantly speed up compilation steps.
We've added this feature in 3.4 release behind a flag. Now we are starting a gradual rollout for everyone. This release enables it for 20% of users.
If you encounter any issues, please let us know in the umbrella discussion.
createNodeManifest
New API for source plugins: This new API will be used to write out information that ties the state of some CMS content to a finally built page. Useful for routing to previews or even production content once they're built.
This release adds a new public action unstable_createNodeManifest
which is used to tie a manifest ID
(a CMS id that maps to a unique revision state of some content) to a page that was built from a specific node.
To make the mapping from node to page more accurate, this release introduces a new argument to the createPage
helper,
ownerNodeId
so that a user can specify that a page is owned by a specific node.
In the case that no ownerNodeId
is provided, the logic checks for a page with an id
variable in page context that
matches to the node id of the node manifest. If neither of those exist the logic maps the manifest to the first
page the node is found on in query tracking.
The result is that a source plugin can allow a CMS to create a manifest file using a CMS ID that maps to a finally built page in Gatsby, allowing for a service to redirect to the right page after a build is complete.
Experimental: Node persistence in LMDB
This release introduces a new experimental data storage option: LMDB (via the excellent lmdb-store package).
Instead of keeping nodes in memory (as it's in Redux), they are instantly saved to this persistent embeddable storage. This will be beneficial for larger sites that can run into OOMs when persisting redux state to disk. Several other performance improvements using this new data store will follow.
We encourage you to try it and let us know if you encounter any issues!
Installation instructions are in the Umbrella Discussion.
gatsby-remark-images: async image decoding by default
Added new plugin option decoding
that adds corresponding attribute to all img
tags produced by the plugin.
Default value is async
(other allowed values are: sync
or auto
).
The decoding
property allows you to control if the browser is allowed to try to parallelize loading your image.
If doing so would cause problems, you can specify sync
to disable asynchronous loading.
Read more about the decode
property.
Yarn 2 (PNP) support
Yarn 2 with Plug'n'Play (Pnp) is available again. With the upgrade of Webpack v4-v5 during our Gatsby v3 release, PnP support broke. We've added an e2e-test to make sure this won't happen again in the future. With yarn 2, you'll notice faster NPM installs and less data usage as yarn2 is aggresivily caching node_modules.
Notable bugfixes & improvements
- Better detection of Babel rules for HMR when customizing the webpack config, via PR #31477
- Correct config for svgo plugins, via PR #31620
gatsby-plugin-gatsby-cloud
: FixedMaximum call stack size exceeded
error, via PR #31547gatsby-source-contentful
: Fix blinking progress bar, via PR #31467gatsby-source-wordpress
: Prevent "EADDRINUSE: address already in use 127.0.0.1" error, via PR #31710gatsby-remark-katext
: Fix compatibility with remark 13, via PR #31596
Contributors
A big Thank You to our community who contributed to this release ๐
-
Marco-Daniel: feat(gatsby-source-wordpress): auto-alias any field named
fields
to prevent conflicts with Gatsby core PR #31526 -
njbmartin: fix(gatsby-source-contentful): use correct name for crop parameter in query string PR #31492
-
wafflepie: fix(gatsby): better detection of Babel rules for HMR when customizing the Webpack config PR #31477
-
pindjur: fix(gatsby): prevent infinite loop in fast-refresh-overlay PR #31594
-
TommasoAmici: Fixed syntax error in example PR #31636
-
dhoko: feat(gatsby-source-wordpress): Fix false positive error if the URL and the responsePath are the same PR #31612
-
sj-rai: chore(docs): Update Jest instructions for v27 PR #31649
-
kevinfoerster: chore(docs): Correct nginx spelling PR #31651
-
viralganatra: feat(gatsby-remark-images): Add decoding prop to img elements PR #31558
-
BurkovBA: fix(gatsby-remark-katex): fix compatibility with remark 13 PR #31596
May 25 2021
Welcome to gatsby@3.6.0
release (May 2021 #2)
Key highlights of this release:
- Functions - now supported in Plugins and Themes! Multiple performance and DX improvements.
- Preview Status Indicator - Design upgrade and added functionality.
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.
Functions
This is a feature-packed release for Functions! Since Gatsby v3.4 you can enable them as a flag in your gatsby-config.js
(learn more in the discussion).
Gatsby plugins (and thus also Gatsby themes) can ship serverless functions now (PR #31466). Place them inside src/api/%pluginName%/
and your users will be able to call them at /api/%pluginName%/
-- this unlocks powerful plug-and-play opportunities like e-commerce themes that ship with frontend and backend logic. We're eager to see in the discussion what you're building.
Functions also support uploading files as part of forms with this release (PR #31470). You can access the data at req.files
.
Last but not least we shipped multiple performance & DX improvements to Functions. We disabled minifaction of functions to speed up the build, enabled webpack 5 filesystem
caching, and lazily compile functions in development to ensure a fast bootstrap.
Preview Status Indicator
With the latest release, we introduce our newest design for the preview status indicator. As with the previous indicator, you will need the latest version of gatsby-plugin-gatsby-cloud
to be installed and configured in your gatsby-config.js
file.
This indicator will show up on your previews hosted on Gatsby Cloud. There are 4 interactable states to alert to the user the state of their preview builds as well as giving more context to when things succeed or go wrong.
This only works with our next gen preview which is currently in the middle of being rolled out to all sites.
Notable bugfixes & improvements
gatsby-source-wordpress
: AddsearchAndReplace
feature, via PR #31091.gatsby-plugin-sitemap
: Fixes a bug where sitemaps were being written in a sub-directory but the sitemap index didn't contain that sub-directory, via PR #31184. Also removereporter.verbose
calls that would spam your Gatsby Cloud logs, via PR #31448.gatsby-source-drupal
: Add toggleable multilingual support by prefixing nodes with their langcode, via PR #26720.gatsby-plugin-image
: Remove extra "margin" onCONSTRAINED
images, via PR #31497.gatsby-source-contentful
: Use correct parameter for "focus" & fix dominant color on cropped images, via PR #31492.
Contributors
A big Thank You to our community who contributed to this release ๐
- hoobdeebla: fix(tests): update cheerio snapshots PR #31298
- lukashass: chore(gatsby-plugin-sitemap): fix typos PR #31351
- angeloashmore: fix(gatsby-plugin-page-creator): support index routes when using the File System Route API PR #31339
- jooola
- DaleSeo: chore(docs): Fix missing closing code fence PR #31404
- camro: Update typo in docs PR #31405
- ascorbic: fix(gatsby-cli): Switch host env to
GATSBY_
prefix PR #31426 - saintmalik: chore(docs): Update "choosing a CMS" PR #31429
- Hahlh: chore(gatsby-plugin-google-gtag): Fix typo PR #31431
- moonmeister: fix(gatsby-plugin-sitemap): Sitemap path bug PR #31184
- NickBarreto: chore(docs): Fixing JSON in configuration options PR #31460
- smurrayatwork: Fixes a bug related to filters appended onto next links for gatsby-source-drupal. PR #31350
- Auspicus: feat(gatsby-source-drupal): Add toggleable multilingual support by prefixing nodes with their langcode PR #26720
- klaasvw: Fixes filenames imported from Drupal via jsonapi are saved URL encoded. PR #31425
- axe312ger: update Contentful e2e test snapshots PR #31073
- jgosmann: fix(gatsby-transformer-sharp): Dereference symlinks when copying files PR #31511
- ekathuria: chore(docs): Update adding-search PR #31512
May 11 2021
Welcome to gatsby@3.5.0
release (May 2021 #1)
Key highlights of this release:
- Performance improvements - up to 20% faster CLI startup, up to 20% faster query running, 70% speedup to creating pages
gatsby-graphql-source-toolkit
v2 - Compatibility with Gatsby v3- New SSR in Develop overlay - the experimental SSR in Develop feature got a new overlay
- Documentation updates - new docs: Functions, CSS, and our image plugins
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.
Performance Improvements
We're always working hard on making Gatsby faster. In this release we shipped three improvements:
- Speedup CLI startup by lazily requiring some modules. PR #31134
- Create page object &
SitePage
node in same action creator. In our synthetic create-pages benchmark (for 100K pages) this reduced thecreatePages
activity from 16s to 4.5s (~70% drop) and peak RSS memory from 1.4gb to 0.7gb (~50% drop). PR #31104 - Up to ~20% improvement to running queries by switching to a faster queue library (fastq). The improvements are most noticeable if you use the fastest query filters (e.g.
eq
filter on theid
property) and don't do CPU intensive work in query running e.g. process markdown or MDX. PR #31269
gatsby-graphql-source-toolkit
v2
The gatsby-graphql-source-toolkit
simplifies data sourcing from remote GraphQL APIs into Gatsby. While it's not a source plugin by itself, it helps you writing custom GraphQL source plugins by providing a set of convenience tools and conventions. Craft CMS or GraphCMS use it for their source plugins.
The bump to a new major version ensures compatibility with gatsby@^3.0.0
. No breaking changes were in this release.
New SSR in Develop overlay
Previously the error overlay (when the page didn't successfully SSR) consisted out of a HTML page served by express. But that wasn't tied into our already existing Fast Refresh overlay we use throughout Gatsby. The information on the page stays the same but it now has the look & feel of all our other errors:
Documentation Updates
- New Functions docs โ PR #31066
- New top-level CSS doc - PR #31138
- Architecture of Gatsby's image plugins - PR #31096
- If you're maintaining a plugin, please subscribe to this GitHub discussion to receive information about changes that may require updates to the plugins you maintain
Notable bugfixes & improvements
- Fix support of theme shadowing in monorepo PR #30435
- Fix scroll restoration for layout components PR #26861
gatsby-plugin-mdx
: make HMR work again for MDX PR #31288gatsby-plugin-preact
: enable error-overlay PR #30613gatsby-plugin-sitemap
: allow writing sitemap to the root of the public folder PR #31130gatsby-transformer-remark
: restore support for footnotes PR #31019- Add
ImageDataLike
as an exported type ofgatsby-plugin-image
PR #30590 - Update the public plugin API types PR #30819
Contributors
A big Thank You to our community who contributed to this release ๐
-
micha149: fix(gatsby-react-router-scroll): scroll restoration for layout components PR #26861
-
hoobdeebla: chore(renovate): update typescript as its own group PR #30909
-
P177: fix(docs): replace invalid style prop with emotion css prop in tutorial PR #31062
-
fshowalter: fix(gatsby-transformer-remark): Activate footnotes by default & remove included options with remark v13 PR #31019
-
joshua-isaac: chore(docs): Update sourcing from agility cms PR #30966
-
Auspicus: fix(gatsby-source-drupal): remove computed fields before running createNode on existing node PR #28682
-
mjameswh: fix(webpack-theme-component-shadowing): Support shadowing in yarn-style workspaces with Webpack 5 PR #30435
-
ben-xD: Update Cloudflare Workers Sites deployment documentation PR #31173
-
pedrolamas: Allows sitemap output on root of public folder PR #31130
-
ridem: fix(gatsby-plugin-netlify-cms): Fix typo in semver PR #31177
-
benomatis: chore(docs): GATSBY_ACTIVE_ENV is undefined by default PR #31136
-
junaidilyas: fix(gatsby): add generic type to GatsbyFunctionResponse PR #31182
-
MorrisonCole: fix(gatsby-plugin-image): add @babel/core peer dependency PR #31188
-
kimbaudi: fix(gatsby): rehydration issue in Dev404Page with DEV_SSR PR #30581
-
FlxAlbroscheit: docs: Updates file name suggestion in babel.md PR #31198
-
dev-szymon: added breakpoints to sharp_attributes set in babel-helpers PR #30451
-
gabo2192: docs: Update example to apollo-client v3 PR #29737
-
cobraz: feat(gatsby-plugin-image): Export ImageDataLike type PR #30590
-
Hannah-goodridge: chore(docs): Update MDX frontmatter for programmatic pages PR #29798
-
alowdon: chore(docs): Update "Adding Search with Algolia" guide PR #29460
-
YehudaKremer: fix(gatsby-plugin-image): print error details PR #30417
-
kelvindecosta: docs(gatsby-plugin-image): Add docs for customizing default options PR #30344
April 27 2021
Welcome to gatsby@3.4.0
release (April 2021 #2)
Key highlights of this release:
- Experimental: Enable webpack persistent caching for production builds - significantly speed up webpack compilation on subsequent builds
- Experimental: Gatsby Functions - serverless functions in Gatsby & Gatsby Cloud
- New Aggregation Resolvers - adds
min()
,max()
, andsum()
resolvers toallX
queries - Better Fast Refresh handling for styling libraries - Theme UI and Chakra UI now work correctly with Fast Refresh
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.
Experimental: Enable webpack persistent caching for production builds
webpack 5 introduced built in persistent caching. It allows webpack to reuse result of previous compilations and significantly speed up compilation steps.
To use it, add a flag to your gatsby-config.js
:
// In your gatsby-config.js
module.exports = {
// your existing config
flags: {
PRESERVE_WEBPACK_CACHE: true,
},
}
Experimental: Functions
We're making our initial alpha release of serverless functions in Gatsby!
New Aggregation Resolvers
The PR #30789 added new aggregation resolvers similar to the already existing group
and distinct
resolvers. You now can use min()
, max()
, and sum()
. They support numeric fields, but also attempt to cast non-numeric fields and includes them if the value is not NaN
.
An example query:
{
allShopifyProduct {
maxPrice: max(field: variants___price)
minPrice: min(field: variants___price)
totalPrice: sum(field: variants___price)
}
}
Better Fast Refresh handling for styling libraries
Since the introduction of Fast Refresh changes to theme files both in Theme UI and Chakra UI didn't result in correct hot-reloading behavior as the user had to manually reload the page to see their changes. The PR #30901 added better Fast Refresh handling for components that don't satisfy the constraints set by Fast Refresh but it didn't completely fix the incorrect behavior in both plugins. Upstream PRs from us to Theme UI and Chakra UI fixed the behavior! Install theme-ui@^0.7.1
or @chakra-ui/gatsby-plugin@^2.0.0
to get the updates.
Notable bugfixes & improvements
- Fixed page context changes not triggering query rerunning PR #28590
- Fixed not being able to disable
DEV_SSR
flag whenFAST_DEV
is enabled PR #30992 - Speed up
createPages
by ~10% by memoizingprocess.env
access PR #30768 - You now can define the
--host
option ofgatsby-cli
withenv.HOST
PR #26712 - Allow CI AWS lamba builds PR #30653
- File System Route API: De-dupe collection pages PR #31016
Contributors
A big Thank You to our community who contributed to this release ๐
-
gustavo-a: fix(gatsby-source-wordpress): change
console.warning
toconsole.warn
PR #30764 -
NatnaelSisay: Fix: change attribute name PR #30800
-
evildmp: chore(docs): Update links to Diรกtaxis framework PR #30808
-
hoobdeebla: fix(renovate): add breaking minor updates to major updates list PR #30676
-
herecydev: fix(gatsby): Decode base path in runtime PR #30682
-
- Refactor: using-contentful to use gatsby-plugin-image exclusively PR #30717
- feat(contentful): warn users when using restricted content type names PR #30715
- test: introduce e2e tests for Contentful PR #30390
- test: Add Contentful content rendering to E2E tests PR #30854
- test(contentful): improve content reference snapshot tests PR #31008
-
kaboumk: fix(gatsby-starter-wordpress-blog): Fix altText PR #30832
-
johndavidcooley: chore(docs): Fix typo PR #30858
-
AbdallahAbis: chore(gatsby-plugin-image): Remove version note PR #30758
-
pvorozhe: chore: Add cloud hosting option for starter READMEs PR #30792
-
pelleknaap: Fix small typo PR #30911
-
mgurevin: fix(gatsby-cli): added HOST environment variable PR #26712
-
VMBindraban: chore(gatsby-source-graphql): Update README url => uri PR #30872
-
OdysLam: chore(docs): Add tailwind to more options at tutorial part 2 PR #30910
-
moonmeister: breaking(gatsby-plugin-sitemap): vNext rewrite PR #25670
-
AcademicHumber: Change the 'idKey' parameter's default value PR #30502
-
kennethormandy: chore(gatsby-plugin-mdx): Document CommonMark option PR #30669
-
mathisobadia: fix(gatsby): change order of feedbackDisabled checks to allow CI AWS lambda build PR #30653
-
MichaelDeBoey: chore(gatsby-plugin-flow): Add pluginOptionsSchema validation PR #27599
-
chrish-d: chore(docs): Updated warning icon to use emoji PR #30979
-
jcalcaben: fix(gatsby-plugin-mdx): Reference style links broken in static builds PR #30967
April 13 2021
Welcome to gatsby@3.3.0
release (April 2021 #1)
Key highlights of this release:
- Performance optimizations - faster JS bundling, lower peak memory usage
- Upgrade to the latest
sharp
- built-in image optimizations; and now works on M1 Macs - Upgrade to the latest
remark
- more consistency in Markdown rendering - Bugfixes in
gatsby-plugin-image
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.
Performance optimizations
Faster JS bundling
This release adds memoization of babel loader options. It significantly reduces the overhead in JS compilation step. With our sample site we saw a speed-up in JS bundling up to 30-40%
Note: this improvement only affects JS bundling, so if you use other heavy transformations (CSS-in-JS, Mdx, etc), you will likely see modest improvements.
Lower peak memory usage
This release restricts concurrency of html-file generation which can greatly reduce memory and disk pressure and decrease spikes in memory usage โ especially for sites with many 100s+ pages and large page-data.json files. With our example site we saw a decrease in peak memory usage from ~3.5 GB to ~1.7 GB (without negative effects to build time).
remark
Upgrade to the latest Remark has had a significant major upgrade
recently (version 13) and changed the underlying parser. The ecosystem has almost caught up
since then, so we've decided to release new major versions of all our remark
plugins.
The following plugins are now fully compatible with remark@13
:
gatsby-transformer-remark@4.0.0
gatsby-remark-autolink-headers@4.0.0
gatsby-remark-code-repls@5.0.0
gatsby-remark-copy-linked-files@4.0.0
gatsby-remark-embed-snippet@6.0.0
gatsby-remark-graphviz@3.0.0
gatsby-remark-images-contentful@4.0.0
gatsby-remark-images@5.0.0
gatsby-remark-katex@5.0.0
gatsby-remark-prismjs@5.0.0
gatsby-remark-responsive-iframe@4.0.0
gatsby-remark-smartypants@4.0.0
We've tried to make the migration effortless and non-breaking (just update the dependencies) but there are subtle differences in HTML output caused by the new remark parser. We've identified and listed the most common differences in this discussion (if you spot other notable changes - please comment there!)
Also check out remark changelog, specifically the section: "Changes to output / the tree".
Incompatible plugin: gatsby-remark-custom-blocks
The only plugin provided by Gatsby that is not compatible yet with remark@13
is
gatsby-remark-custom-blocks
.
This plugin relies on the upstream remark plugin remark-custom-blocks
which is itself not compatible with
remark@13
yet.
The work on updating it is in progress though, and as soon as it is finished we will publish the new major version for our plugin as well.
In the meantime if you use this plugin you can just wait when it's ready or modify your markdown
and switch to another syntax. Remark authors suggest
using remark-directive
as an alternative.
Use to-gatsby-remark-plugin
package to convert it to Gatsby remark plugin.
sharp
Upgrade to the latest Check out Sharp changelog for a full list of changes.
The most important highlights of the new release:
- Smaller install size
- Supports Mac M1: now uses prebuilt libvips binaries for M1 Macs
- Includes buil-in image optimization (unlocks future perf improvements in Gatsby)
gatsby-plugin-image@1.3.0
Bugfixes in - Fix a bug that caused errors in third party packages that access the
global
object - Fix a bug that prevented
draggable="false"
being set on theGatsbyImage
component - Fix a bug that caused blurred previews to be generated at the wrong aspect ratio
- Fix a bug that prevented lazy-loaded images displaying in Safari
- Fix a bug that caused duplicate type errors when using Contentful images with other plugins that implement images
Notable bugfixes & improvements
- Fixed invalid query results in cached builds PR #30594
- Schema customization: merge fields of interfaces defined by multiple plugins PR #30501
- Fix for IE11: add dom collections to polyfills PR #30483
Contributors
A big Thank You to our community who contributed to this release ๐
-
JobenM: fix(gatsby-plugin-mdx): timeToRead returns NaN when word count is 0 PR #30489
-
- fix(gatsby-source-contentful): Improve network error handling PR #30257
- chore(contentful): create compiled files in dist instead of . PR #30414
- fix(examples): Update using-contentful to use gatsby-plugin-image PR #29526
- build(using-contentful): add missing sharp dependency PR #30546
- feat(gatsby-source-contentful): Increase Contentful sync by up to 10x PR #30422
- fix(contentful): set proper defaults for gatsby-plugin-image PR #30536
- feat(gatsby-source-contentful): update docs and improve errors PR #30538
- fix(gatsby-source-contentful): Contentful page limit backoff PR #30549
- fix(contentful): ensure fragments are properly distributed PR #30555
- fix(using-contentful): clean up dependencies PR #30556
- fix(contentful): make gatsby-plugin-image a peer dependency PR #30709
-
ridem: fix(gatsby-plugin-netlify-cms): Don't use StaticQueryMapper PR #30599
-
Nurou: chore(gatsby-source-wordpress): Link to source WP plugin PR #30645
-
baker-jr-john: chore(docs): Update how-gatsby-works-with-github-pages PR #30630
-
nategiraudeau: fix(gatsby-example-using-remark) fix broken example for typescript users PR #30505
-
AntonNiklasson: chore(docs): include autoprefixer in tailwind install command PR #30718
March 30 2021
Welcome to gatsby@3.2.0
release (March 2021 #3)
Key highlights of this release:
- Better
StaticImage
errors - Adjustable ES Modules option for CSS Modules
gatsby-source-contentful
- improved performance and other changes
Also check out notable bugfixes.
Sneak peek to next releases:
Bleeding Edge: Want to try new features as soon as possible? Install gatsby@next
and let us know
if you have any issues.
StaticImage
errors
Better For our new gatsby-plugin-image
we also introduced StaticImage
to allow quick usage of the image pipeline for images that are the same every time. But it comes with some restrictions that you need to think of.
To make using StaticImage
easier the previous error message was adjusted to now also show the offending code and link to the relevant documentation.
Bonus: If you want to use StaticImage
as a background image, read our newly added docs.
Adjustable ES Modules option for CSS Modules
With the release of Gatsby v3 we made the choice to import CSS modules as ES Modules by default. This allows better treeshaking and smaller files as a result -- however, when using third-party packages that still expect CommonJS you'll need to work around this behavior to be able to migrate to Gatsby v3.
Together with v3.2 also new minors of gatsby-plugin-sass
, gatsby-plugin-less
, gatsby-plugin-postcss
, and gatsby-plugin-stylus
were released. You're now able to override the esModule
and namedExport
option of css-loader
inside each plugin.
Please see the migration guide for an example.
gatsby-source-contentful@5.2.0
Features:
- The default limit when fetching data from Contentful was increased by 10 times. This will speed up build times.
- The
using-contentful
example got updated to Gatsby v3 and demonstrates how to usegatsby-plugin-image
with Contenful. - New e2e-contentful test suite to improve plugin reliability.
Fixes:
- Network errors are properly retried again.
- Set proper defaults when for
gatsby-plugin-image
(Constrained layout with dominant color as placeholder) - Improved help when connection credentials are wrong
- Improved the docs and added more details about the
downloadLocal
config option
Notable bugfixes & improvements
- Be less aggressive about the
fs
in SSR usage warnings, now excludinghttp(s).Agent
andnode-gyp-build
PR #30216 - Fixing rendering issues in
gatsby-plugin-image
with the placeholder and component itself PR #30221 - Documentation about Debugging Incremental Builds PR #30329
- Validate plugin options schema also for local plugins PR #29787
Next version: major bump of all remark plugins
Remark has had a significant major upgrade recently and changed the underlying parser. The ecosystem seems to have almost caught up since then, so we are going to release a new major version for all remark-related plugins soon.
We tried to make the upgrade effortless but there could still be subtle differences in output and edge cases. So please try pre-release versions of those plugins and let us know if you notice any inconsistencies or bugs.
Install the following canary versions of all remark packages that you have in your package.json
:
gatsby-remark-autolink-headers@alpha-remark13
gatsby-remark-code-repls@alpha-remark13
gatsby-remark-copy-linked-files@alpha-remark13
gatsby-remark-custom-blocks@alpha-remark13
gatsby-remark-embed-snippet@alpha-remark13
gatsby-remark-graphviz@alpha-remark13
gatsby-remark-images-contentful@alpha-remark13
gatsby-remark-images@alpha-remark13
gatsby-remark-katex@alpha-remark13
gatsby-remark-prismjs@alpha-remark13
gatsby-remark-responsive-iframe@alpha-remark13
gatsby-remark-smartypants@alpha-remark13
gatsby-transformer-remark@alpha-remark13
Contributors
A big Thank You to our community who contributed to this release ๐
- misfist: chore(starters): Update WordPress blog README PR #30209
- TngSam: chore(docs): Update using-web-fonts PR #30243
- andrewrota: chore(docs): Fix link to markdown-syntax PR #30239
- dhrumilp15
- pedrolamas: fix(gatsby-plugin-netlify): upgrade webpack-assets-manifest for compatibility with webpack@5 PR #30217
- Elendev: chore(docs): Fix typo in createPages doc PR #30343
- blenderskool: fix(gatsby): Add reporter.panic in empty catch in load-themes PR #29640
- UgRoss: fix(gatsby): Fix wrong resolve id for CommentJson type PR #30389
- larowlan: fix(drupal): Support forward revisions for Drupal paragraphs PR #29289
- kamranayub: fix(gatsby): validate local plugin options schema PR #29787
- JobenM: fix(gatsby-plugin-mdx): timeToRead returns NaN when word count is 0 PR #30489
- axe312ger
- fix(gatsby-source-contentful): Improve network error handling PR #30257
- chore(contentful): create compiled files in dist instead of . PR #30414
- fix(examples): Update using-contentful to use gatsby-plugin-image PR #29526
- build(using-contentful): add missing sharp dependency PR #30546
- feat(gatsby-source-contentful): Increase Contentful sync by up to 10x PR #30422
- fix(contentful): set proper defaults for gatsby-plugin-image PR #30536
- feat(gatsby-source-contentful): update docs and improve errors PR #30538
- fix(gatsby-source-contentful): Contentful page limit backoff PR #30549
- fix(contentful): ensure fragments are properly distributed PR #30555
- fix(using-contentful): clean up dependencies PR #30556
March 16 2021
Welcome to gatsby@3.1.0
release (March 2021 #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.
Fast Refresh Dark Mode
Gatsby's Fast Refresh modal now respects the prefers-color-scheme
setting from your operating system. Depending on your setting you'll see the overlay in light or dark mode -- which is great because it makes the modal more accessible!
Improved Error Messages
We've seen many complaints about the unspecific error "Error page resources for <path> not found. Not rendering React"
. There are many reasons why this could happen so we improved our error logging to output the original error. As usual you'll see the error in DevTools console or in your error tracker.
Consider the following example, it now shows the actual error.
if (typeof window === "undefined") {
throw new Error("GATSBY")
}
export default function MyPage() {}
In development mode we also now show the original error when it occurs in gatsby-browser.js
or outside of React components.
gatsbyImageData
is stable
Contentful Contentful now fully supports gatsby-plugin-image
out of the box. You can find the official docs for gatsby-plugin-image in gatsby-source-contentful the official contentful plugin docs
{
allContentfulBlogPost {
nodes {
heroImage {
gatsbyImageData(layout: FULL_WIDTH)
}
}
}
}
You can find more information on how to switch to gatsby-plugin-image
by going to our gatsby-image
to gatsby-plugin-image
migration guide
Notable bugfixes
- gatsby: Fix routing when path starts with @ symbol, via PR #29935
- gatsby: Fix incremental builds when remove trailing slashes is used, via PR #29953
- gatsby: Add build stage to custom babel-preset-gatsby configurations, via PR #30047
- gatsby: Fix hanging Gatsby process between webpack rebuilds in development, via PR 30127
- gatsby: fix SitePage schema, via PR #30132
- gatsby: fix double save during gatsby develop, via PR #30193
- gatsby-plugin-image: Handle placeholder in plugin toolkit correctly, via PR #30141
- gatsby-source-contentful: fix deprecation warnings, via PR #29675
Contributors
-
visualfanatic: docs(gatsby-plugin-subfont): correct property name PR #29803
-
chrsep: fix: query on demand loading indicator always active on preact. PR #29829
-
imshubhamsingh: chore(docs): updated doc for payment using square PR #27272
-
ahmetcanaydemir: fix(gatsby-react-router-scroll): debounce function for scrollListener PR #26933
-
talohana: chore(docs): add paths to unit-testing using typescript PR #28029
-
hashimwarren: chore(docs): Update headless WordPress article PR #29402
-
lorensr: chore(docs): Add twitter links to tutorial PR #29696
-
herecydev: fix(gatsby): Add dir=ltr to Fast Refresh overlay PR #29900
-
dan2k3k4: chore(docs): Fix link to /docs/conceptual/using-gatsby-image PR #29930
-
lourd: refactor(gatsby-transformer-remark): Refactors out Bluebird usage in transformer-remark PR #29638
-
ahollenbach: docs: clarify env variable prefix in gatsby-source-filesystem docs PR #30013
-
Swarleys: docs(gatsby-plugin-image): fixing a typo. PR #29994
-
samlogan: fix(gatsby-plugin-image): broken documentation links PR #30065
-
KarlBaumann: chore(gatsby-source-wordpress): Remove version from README PR #30056
-
Vazerthon: chore(docs): Add link to art direction docs PR #30041
-
magnusdahlstrand: chore(gatsby-plugin-postcss): Update README to show correct usage PR #30035
-
feedm3: chore(docs): set process polyfill correctly PR #30160
-
machadoluiz: fix(docs): update conceptual gatsby image doc PR #30175
-
dhrumilp15: chore(docs): Update deploying-to-digitalocean-droplet PR #30161
March 02 2021
Welcome to gatsby@3.0.0
release (March 2021 #1).
This is the first major bump of Gatsby since September 2018! Weโve tried to make migration smooth. Please refer to the migration guide and let us know if you encounter any issues when migrating.
Key highlights of this release:
- Incremental Builds in OSS - regenerate HTML only when necessary, leading to faster builds
- Fast Refresh - new hot-reloading engine, error recovery, better DX
- gatsby-plugin-image@1.0.0
- gatsby-source-wordpress@5.0.0 - brand-new, significantly improved integration with WordPress
- gatsby-source-contentful@5.0.0
- Miscellaneous changes in plugins
Major dependency updates:
Also check out notable bugfixes and improvements.
Bleeding Edge: Want to try new features as soon as possible? Install gatsby@next
and let us know
if you have any issues.
Previous release notes for v2.32
Breaking Changes
If you're looking for an overview of all breaking changes and how to migrate, please see the migrating from v2 to v3 guide.
Incremental Builds in OSS
Gatsby v2 introduced experimental "Conditional Page Builds" (enabled by GATSBY_EXPERIMENTAL_PAGE_BUILD_ON_DATA_CHANGES
environment variable). It had some gotchas and quirks, and it wasn't ready yet for GA. With Gatsby v3, we improved this feature and activated it by default for everyone! So incremental builds is available in OSS now. This improvement is (re)generating only subset of HTML files that needs to be generated. To be able to use it you will need to keep the .cache
and public
directories from previous builds.
Take a project powered by Shopify as an example. You have your listing of all products and then individual product pages. When you change one single product, only that page should be rebuilt. In the screenshot below you can see exactly that (the sentence "Hello World" was added to the description):
The screenshot is taken from a talk about Gatsby v3 at GatsbyConf. You can view the video showcasing this feature on YouTube.
How does it work?
Gatsby tracks "inputs" when generating HTML files. In particular we track:
- which page template the page is using
- result of page query
- results of static queries used by a page template
- frontend source code (shared and also browser
gatsby-browser
/ SSRgatsby-ssr
specifically)
When those inputs change since the last build, the HTML files are marked to be regenerated. If they don't change, we can reuse HTML files generated in previous build.
Avoid direct filesystem calls
As we mentioned, Gatsby tracks "inputs" used to generate HTML files. However, the gatsby-ssr
file allows some arbitrary code execution like using the fs
module. For example:
const fs = require(`fs`)
const someUntrackedInput = fs.readFileSync(`some-path.txt`)
// Rest of gatsby-ssr.js file
While Gatsby could also track files that are read, the custom code that does those reads might have some special logic that Gatsby is not aware of. In the above example the filename could be generated and changed between builds, or the file read itself could change -- so we see this as "arbitrary" file reading. If Gatsby discovers that fs
modules are used, it will disable "Incremental Builds"-mode to stay on the safe side (there will be warnings mentioning "unsafe builtin method").
If your gatsby-ssr
(either site itself or plugin) make use of fs
reads, head over to migrating from v2 to v3 guide and check how to migrate.
Fast Refresh
After adding our initial Fast Refresh integration back in November 2020, we worked on it over the last couple of releases. For Gatsby v3 we further improved usability, reliability, and accessibility to make it the default overlay. With this the old react-hot-loader
is removed and you can benefit from all the new features it has: Fast Refresh is faster, handles errors better, and preserves state across re-renders.
Here's a preview:
We built a custom error overlay that aims to give you helpful information to fix your bugs more quickly. It features:
- A clear indication whether it's a runtime error, compile error, or GraphQL error
- Source code snippets that you can open in your editor with the press of a button
- The exact error location, including the original line and column
- The overlay automatically goes away once you fix the error
We also added two new ESLint rules inside the default configuration that will warn you against anti-patterns in your code:
- No anonymous default exports
- Page templates must only export one default export (the page) and
query
as a named export
Visit the Fast Refresh reference guide to learn more.
Node 12
We are dropping support for Node 10 as it is approaching maintenance EOL date (2021-04-30).
The new required version of Node is 12.13.0
. See the main changes in Node 12 release notes.
Check Nodeโs releases document for version statuses.
webpack 5
Please refer to the webpack release notes for a full list of changes.
Key changes in the new webpack version:
- Improved build performance with Persistent Caching
- Improved Long-Term Caching with better algorithms and defaults
- Improved bundle size with better Tree Shaking and Code Generation
- Improved compatibility with the web platform
- Cleaned up internal structures
What does that mean for your Gatsby site? Gatsby is now able to tree-shake on a page level instead of an app level. You'll see reductions up to 20% on file size. Users returning to your site will benefit from the improved hashing algorithms as unchanged files will be loaded from the browser cache.
Weโve tried to protect you from the burden of manual webpack migration, but if you are using a custom webpack config or community plugins that do not support webpack 5 yet, you may find the webpack migration guide useful.
React 17
Please refer to React's own release notes for a full list of changes.
The minimum version of Gatsby is now 16.9.0 to support Fast Refresh, React Hooks, and Suspense by default. We've also made sure we're 100% compatible with React 17. To use the new React JSX transform have a look at the babel-preset-gatsby
section below.
With this change, we'll be adding more experiments to support Concurrent mode and React server components in future releases.
GraphQL 15
Please refer to graphql-js
's own release notes for a full list of changes.
With this upgrade we can finally leverage interface inheritance for queryable interfaces.
You no longer need to use @nodeInterface
directive in schema customization:
exports.createSchemaCustomization = function createSchemaCustomization({ actions }) {
const { createTypes } = actions
createTypes(`
- interface Foo @nodeInterface
+ interface Foo implements Node
{
id: ID!
}
`)
}
Also, Gatsby now displays GraphQL deprecations as CLI warnings. Example output:
ESLint 7
Please refer to eslint
's own migration guide to update your custom ESLint files.
If you rely on Gatsby's default ESLint configuration, you should have a smooth transition. We upgraded the underlying rules, so you might get some new warnings/errors.
Gatsby no longer uses the deprecated eslint-loader
. Weโve moved to eslint-webpack-plugin
. By using the plugin, behaviour has changed a little bit, as warnings and errors are displayed later than in version 2.
gatsby-plugin-image@1.0.0
This release includes a new plugin, gatsby-plugin-image
, replacing the old gatsby-image
plugin. Built from the ground up for speed and best practices, it's the most performant way to use images in React. If you saw your scores drop with recent Lighthouse updates, migrating to this plugin should help you get top scores again. It comes with a new, simplified GraphQL API (no more fragments), as well as a new StaticImage
component that's as easy to use as an <img>
tag.
The GatsbyImage
component supports three responsive layout types, as shown in the video below.
There is a codemod available to help migrate from gatsby-image
. Support is included in all sources that use childImageSharp
, as well as out of the box support in several CMS plugins, with more coming soon.
For more information, see:
- Migrating from gatsby-image to gatsby-plugin-image
- How-To Guide: Using gatsby-plugin-image
- Reference Guide: Gatsby Image plugin
- The
gatsby-plugin-image
README - GatsbyConf: Announcing gatsby-plugin-image
gatsby-source-wordpress@5.0.0
Recently weโve announced the brand-new WordPress integration. Refer to this post on the Gatsby Blog for the full details: Announcing Gatsbyโs New WordPress Integration
The originally published version of renewed gatsby-source-wordpress
is 4.0.0
. It is
fully compatible with Gatsby v2.
For Gatsby v3 bump weโve also bumped gatsby-source-wordpress
to 5.0.0
. It should
be a straight-forward update from gatsby-source-wordpress@^4.0.0
. No additional changes
from you are required.
- Fixed a bug where adding a post type named "Filter" would break options queries PR #29718
- Fixed an HTML field
gatsby-image
regression that would prevent image transforms in certain situations PR #29778 and PR #29813
gatsby-source-contentful@5.0.0
- Migrated to the latest Contentful SDK, via PR #29520
- Compatibility with
gatsby-plugin-image
- Retries when downloading assets
- Retries on network errors
gatsby-plugin-gatsby-cloud v1 & v2
Gatsby Cloud now includes Hosting for all your Gatsby projects. gatsby-plugin-gatsby-cloud
is a new plugin that you need to install when using Gatsby Cloud Hosting. It generates redirects and rewrites for your client side routes automatically and even allows you to set custom Headers on a per-file basis.
If you're using Gatsby v2 please install gatsby-plugin-gatsby-cloud@^1.0.0
. For Gatsby v3 weโve bumped gatsby-plugin-gatsby-cloud
to 2.0.0
. It should
be a straight-forward update, no additional changes from you are required.
Read more about gatsby-plugin-gatsby-cloud
at the README.
Miscellaneous changes in plugins
babel-preset-gatsby
babel-preset-gatsby
now accepts reactImportSource
which is passed to the underlying @babel/preset-react
importSource field. Note that this field is only supported when reactRuntime
is automatic
. It is classic
by default.
Configuration looks like this.
{
"presets": [
[
"babel-preset-gatsby",
{
"reactRuntime": "automatic",
"reactImportSource": "@emotion/react"
}
]
]
}
gatsby-plugin-guessjs
The plugin is deprecated. It is not compatible with Gatsby v3.
gatsby-transformer-remark
When using the tableOfContents
functionality, the defaults have changed. absolute
now defaults to false
, and pathToSlugField
defaults to an empty string.
gatsby-react-router-scroll
ScrollContainer
, previously deprecated, has now been removed. Please use the useScrollRestoration
hook instead.
gatsby-core-utils
Introduce fetchRemoteNode
utility (supersedes file download utils from gatsby-source-filesystem
) via PR #29531
gatsby-plugin-styled-components
Support topLevelImportPaths
option, via PR #29544
gatsby-plugin-canonical-urls
Add plugin options validation to gatsby-plugin-canonical-urls
, via PR #29688
Notable bugfixes and improvements
- Drop
terminal-link
from our CLI as in some terminals it turned lines blank, via PR #29472 - Update the
pathExist
function ingatsby-plugin-feed
, via PR #29616 - Cache AVIF images in
gatsby-plugin-offline
, via PR #29394 - Improve efficiency when writing HTML files to disk, via PR #29219
- 10-20% faster sourcing by memoizing actions when running plugins, via PR #29240
- Do not miss page invalidations when using
runQuery
in custom resolvers, via PR #29392 - Upgrade TypeScript to 4.0, via PR #29388
Contributors
A big Thank You to our community who contributed to this release ๐
- lokesh-coder: chore(docs): Fix typo in contributing style guide PR #29262
- domvo: fix(gatsby-plugin-sharp): make sure to pass the failOnError option to base64 generation PR #29254
- axe312ger
- feat(contentful): add retry logic to asset downloading PR #29268
- feat(gatsby-source-contentful): improve Contentful image handling PR #29398
- fix(contentful): fix import PR #29522
- fix(contentful): retry on network errors when checking credentials PR #29664
- chore(gatsby-source-contentful): migrate to latest Contentful SDK PR #29520
- louis-morgan: chore(gatsby-source-wordpress): Update querying-data tutorial PR #29353
- deraru: chore(docs): Fix product slugs for building-an-ecommerce-site-with-shopify page PR #29292
- meeroslav: docs(wordpress): fix broken assets link after migration PR #29389
- zonayedpca: chore(docs): Remove extra curly brace PR #29405
- geekster909: docs(gatsby-source-wordpress): fix back to readme.md link PR #29468
- isabelleingato: docs(gatsby-plugin-netlify): Update readme PR #29168
- Javaman2
- astrokd: chore(docs): Update sourcing-from-json-or-yaml PR #29488
- jbampton
- docs: fix spelling PR #29494
- docs: remove unneeded whitespace from Markdown link PR #29582
- docs: fix spelling PR #29581
- docs: fix case of GitHub, JavaScript, TypeScript and WordPress PR #29580
- fix(gatsby-recipes): change 'Typescript' to 'TypeScript' PR #29587
- fix(gatsby-source-wordpress): remove hard tabs from Markdown PR #29627
- chore(docs): remove unneeded whitespace before commas and full stops PR #29629
- rogermparent: Fix URL typo in sass recipe PR #29530
- gregberge: fix(gatsby-plugin-styled-components): Support
topLevelImportPaths
option PR #29544 - strategore: chore(docs): Update Directus plugin link PR #29533
- jasonbahl: Update graphql-wordpress-and-gatsby.md PR #29558
- bryndyment: chore(docs): Fix caching typo PR #29578
- mareksuscak: Update the changelog of Contentful plugin to show a working example PR #29579
- kdwarn: chore(docs): Add note on reloading bash configuration. PR #29613
- frederickfogerty: chore: improve description of placeholder parameter PR #29670
- odkpatrick: chore(docs): Updated gatsby-for-ecommerce PR #29676
- lwz7512: fix(gatsby-source-wordpress):issue #29535 not finished createSchemaCuโฆ PR #29554
- stefanprobst: fix(gatsby): fix regex filter in graphql queries PR #26592
- kartikcho: fix(gatsby): context.nodeModel.runQuery should return [] instead of null PR #25885
- hendra-go: Update index.js PR #29758
- hiad: fix(gatsby-plugin-feed): Exists function and update version fs-extra PR #29616
- disintegrator: feat(babel-preset-gatsby): allow setting importSource on preset-react PR #29260
- herecydev: fix(gatsby): Add dir=ltr to Fast Refresh overlay PR #29900
February 02 2021
Welcome to gatsby@2.32.0
release (February 2021 #1)
Key highlights of this release:
- Stable API in beta image plugin
- Support for beta image plugin in Contentful
- Default sharp settings in beta image plugin
- Support for art direction in beta image plugin
- Performance improvements for larger sites (10000+ pages)
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.
Stable API in beta image plugin
With this release, the API for gatsby-plugin-image can be considered stable. We do not expect any breaking changes to be made before general release, upcoming work will focus on bugfixes and minor updates. You can start to migrate your sites to use the new plugin, and benefit from the improved performance, new components, and cleaner API.
Support for beta image plugin in Contentful
This release includes initial support for the beta image plugin in gatsby-source-contentful
. This adds a new gatsbyImageData
resolver to ContentfulAsset nodes, allowing you to use the new image components with your Contentful data. This is a first release and does not yet have proper documentation, but please try it out and report back in the gatsby-plugin-image RFC.
Default sharp settings in beta image plugin
Do you always want to generate AVIF images? Should your hero image breakpoints support 8K monitors? Until now you needed to pass the relevant options for every image. This release adds support for default options, meaning you can set most options once in gatsby-config and they will apply by default to both dynamic and static images. Add a defaults
object to your gatsby-plugin-sharp
config, and pass it any valid option. Note that sizing options, e.g. width and height, are not supported as they're image specific.
Support for art direction in beta image plugin
Art direction is a browser feature that allows you to specify different images to be displayed at different screen sizes. This is different from responsive images, which provides different image resolutions. Until now this feature has been missing in the new image plugin, but this release adds a new useArtDirection
hook, which allows you to art direct your images. It does not have full docs, but see the PR for more information and a video featuring a pug in a raincoat.
Performance improvements for larger sites (10000+ pages)
We landed two PRs that improve build performance for larger sites.
On our minimal benchmark site, these improved build times by ~15% for a 10,000 page site and 30% for a 100,000 page site!
Notable bugfixes
- gatsby-plugin-sharp: The
failOnError
is correctly passed to sharp, allowing the build to proceed when there are corrupt images, via PR #29254 - gatsby-plugin-sharp: Fixes a bug that caused build failures on Windows when generating traced SVGs, via PR #29246
- gatsby-plugin-manifest: Fixes to plugin options validation, via PR #29242 and PR 29193
- gatsby-source-contentful: Correctly handle env-specific API key validation, via PR 29228
- babel-plugin-remove-graphql-queries: Make sure imports are POSIX-compliant, via PR #29144
Contributors
A big Thank You to our community who contributed to this release ๐
-
Grsmto: fix(gatsby-plugin-image): pass down missing sizes attribute to
<sources>
PR #29092 -
StefanSelfTaught: Update creating-a-local-plugin.md PR #28072
-
Simply007: Update plugin option schema validation code sample PR #28904
-
ediblecode: fix(gatsby): Add missing prev location TS property for RouteUpdateArgs PR #29125
-
Himanshu-27: chore(docs): Netlify CMS added branch to backend settings PR #29162
-
yonatanLehman: chore(docs): Update debugging-the-build-process PR #29067
-
alexleventer: chore(docs): Add cassandra to list of database sources PR #29137
-
johanneswuerbach: fix: sync crash with error response PR #29212
-
jevenson: chore(docs): Update TypeScript Unit Testing Docs PR #29227
-
domvo fix(gatsby-plugin-sharp): make sure to pass the failOnError option to base64 generation PR #29254
January 19 2021
Welcome to gatsby@2.31.0
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.
Performance improvements
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.
Support for Gatsby's fragments in GraphiQL
The underlying 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:
Fast Refresh enabled by default for React 17
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
query
as a named export
Please give us your feedback about the Fast Refresh integration in the umbrella issue. Thanks!
gatsby-plugin-image
updates
Important 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.
fluid
layout renamed tofullWidth
: We're renaming thefluid
layout tofullWidth
, to better reflect what it's used for. It was calledfluid
before to match the equivalent layout in the oldgatsby-image
component. However this was confusing, because for many of the cases where people usedfluid
before they should be using the newconstrained
layout. This displays the image at the specified width, but allows it to shrink to fit smaller screens. HoweverfullWidth
images 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
maxWidth
forfullWidth
images: The oldfluid
resolver allows you to pass amaxWidth
argument, 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 the1x
resolution 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 withmaxHeight
(also doesn't do what you'd expect). Its replacement is: - Use breakpoints for
fullWidth
images: Previouslyfluid
layout generated image resolutions that were based on multiples and fractions of themaxWidth
, similar to how they are done forfixed
andconstrained
. 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. - Change
maxWidth/maxHeight
towidth/height
There was no good reason to haveconstrained
takemaxWidth/maxHeight
, while fixed tookwidth/height
. We've changed it so they both takewidth/height
. - Add
aspectRatio
prop: We realized that lots of people were using hacks to set the aspect ratio of images, because it was hard to do properly, particularly forfluid
images. We've added a newaspectRatio
prop 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. - Automatic
object-fit
polyfill: This version includes an automatic polyfill for browsers that don't support the CSSobject-fit
andobject-position
properties. 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.
Notable bugfixes
- Extract non-CSS-in-JS CSS and add to
<head>
when SSRing in develop mode (withDEV_SSR
flag), via #28471 - Show stack trace for non-GraphQL errors, via #28888
- Update vulnerable packages and include React 17 in peerDeps, via #28545
Contributors
A big Thank You to our community who contributed to this release ๐
-
DecliningLotus: Update Fontsource Documentation PR #28750
-
saintmalik: chore(docs): fix a broken url PR #28756
-
eriklofblad: chore(docs): Updated Twin + Gatsby + Emotion link PR #28782
-
yonatanLehman: chore(docs): Update lighthouse instructions in tutorial PR #28785
-
takapiro99: chore(docs): Fix all
/packages
links to/plugins
PR #28816 -
Taremeh: chore(docs): Update migrate-remark-to-mdx PR #28811
-
- 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
-
AlexRAV: Add avif format support to gatsby remark images package PR #28927
-
nishantwrp: chore(default-starter): format code using prettier PR #28958
-
GrantHair5: chore(docs): Change cd path to "my-gatsby-site" PR #28933
-
mrhut10: feat(gatsby-source-shopify): download images option PR #23840
-
andrewmcoupe: chore(gatsby): Improve type safety of ShouldUpdateScrollArgs PR #28923
-
Vishal19111999: chore(docs): Add Tina in list of Headless CMS PR #28981
-
ariadne-github: perf(gatsby-source-contentful): prevent redundant fs/remote fetches for tracedSVG PR #28926
-
kaneshin: fix(gatsbu-source-contentful): apply useNameForId when creating the graphql schema PR #28649
-
nategiraudeau: fix(sharp) wrap sharp calls in try/catch to avoid crashing on bad images PR #28645
-
hoobdeebla: fix(security): update vulnerable packages, include React 17 in peerDeps PR #28545
-
hasparus: fix(gatsby-plugin-typescript): add missing options validations PR #29066
January 05 2021
Welcome to gatsby@2.30.0
release (January 2021 #1)
Key highlights of this release:
- Query on Demand and Lazy Images: Generally available - improves
gatsby develop
bootup time - Server Side Rendering (SSR) in development โ helps you find and fix many build errors in development. We're starting a partial release of this feature to 5% of users.
gatsby-plugin-sass
v3 - use the latestsass-loader
andDart Sass
by default- Image transformations up to 30% faster
And several impactful updates in the new gatsby-plugin-image
(beta):
- AVIF support - enjoy next-gen image format
- Support remote static images - download, transform and optimize remote images with a single line
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.
Query on Demand and Lazy Images: Generally Available
Those two features change the way how gatsby develop
works:
- We no longer transform all images eagerly on dev server start
- We no longer run all queries
Instead, it happens lazily when the browser requests a page or a specific image variant.
This significantly shortens the boot-up time for gatsby develop
.
Note that it does not affect
gatsby build
in any way, onlygatsby develop
We've been gradually rolling out those features:
- "Query on Demand" was introduced behind the flag in v2.27.
- "Lazy images" were introduced behind the flag in gatsby-plugin-sharp@2.10.0.
- In v2.29 10% of our users were automatically opted-in
This allowed us to collect the feedback and fix bugs as they were discovered.
Now we feel confident enough to publish it as generally available. You don't need to add flags or any environment
variables to enable it. Just upgrade to gatsby@2.30.0
(and gatsby-plugin-sharp@2.12.0
for lazy images).
In v2.29 we improved the UX around long-running queries by adding a loading indicator and message to the browser console (only in gatsby develop
). If you want or need to de-activate this indicator, you can! For more details please see the umbrella discussion.
Server Side Rendering (SSR) in development
There are certain types of build errors that haven't been detectable while developing. The most common is code that tries to access browser globals (like window
) that don't exist in Node.js when SSRing your Gatsby site.
This is frustrating as you might develop for a while before building and only then discover the error. Then actually fixing the problems is painful as the feedback cycle is slow as you have to run a build after each code change.
We've been working to add SSR support to the develop server so that you can immediately see SSR bugs and get quick feedback as you fix them. With this change, whenever you do a full reload, the Gatsby dev server will deliver a SSRed HTML file along with your React code, mimicking how production Gatsby sites work.
This is related to our general efforts to make the develop and build environment identical.
Like the recent Query on Demand and Lazy Images changes, we released this change first behind a flag for early testing and now, weโre rolling this out to a small percentage of users (5%) for more real-world testing before the final release to 100% of users.
Weโll let you know after upgrading if your site has SSR enabled. If itโs not enabled and youโd like to start using it immediately, simply add the DEV_SSR
flag to your gatsby-config.js
.
module.exports = {
flags : { DEV_SSR: true },
plugins: [...],
}
gatsby-plugin-sass@3.0.0
Now that LibSass and Node Sass are deprecated, we've
upgraded sass-loader
to 10.1.0
and thus switched sass implementation to Dart Sass.
The plugin itself is compatible with the previous version. For the majority of projects the upgrade won't require any special actions.
But keep in mind that Dart Sass may still have subtle differences in some edge cases comparing to Node Sass, so if you encounter any issues make sure to check out "How do I migrate section" in sass docs.
See also:
gatsby-plugin-sharp@2.12.0
New approach to concurrency speeds up image transformations up to 30%.
Previously we were applying several transformations to a single image concurrently. With the new approach we transform multiple images in parallel but apply transformations to each image serially.
Another major change is lazy images in develop.
gatsby-plugin-image@0.5.0 (beta)
AVIF support
This release adds beta support for generating and displaying AVIF images. AVIF is a brand-new image format, which offers considerably better filesizes and quality than JPG and even WebP. It is currently only supported in Chrome, with Firefox support coming soon. However it is safe to use today, because unsupported browsers will fall back to using a supported format.
AVIF is not currently enabled by default, so to use it in your site you need to add it to the formats
array. You should also include auto and WebP to support other browsers. Ensure that you have upgraded to the latest version of gatsby-plugin-sharp
, gatsby-transformer-sharp
and gatsby-plugin-image
, and then use the following syntax:
In StaticImage
:
<StaticImage
src="./cornwall.jpg"
formats={["auto", "webp", "avif"]}
alt="Cornwall"
/>
...or in GraphQL:
query {
file(relativePath: { eq: "cornwall.jpg" }) {
childImageSharp {
gatsbyImageData(maxWidth: 720, formats: [AUTO, WEBP, AVIF])
}
}
}
This does not currently work in Gatsby Cloud, but will be enabled later this week.
This is possible thanks to the incredible work by the sharp and libvips contributors.
Support remote image URLs (experimental)
This release enables experimental support for remote URLs in the StaticImage
component. This means that you can pass an absolute URL in the src
prop and Gatsby will download the file and process it at build time. It is currently experimental, but you can try it out today and let us know how you find it.
To enable, set the GATSBY_EXPERIMENTAL_REMOTE_IMAGES
environment variable to 1
when building:
GATSBY_EXPERIMENTAL_REMOTE_IMAGES=1 gatsby develop
or...
GATSBY_EXPERIMENTAL_REMOTE_IMAGES=1 gatsby build
You can then pass absolute URLs to StaticImage
:
<StaticImage src="https://placekitten.com/400/400" alt="Kittin" />
Please note that this is only supported in StaticImage
.
Notable bugfixes
- Display meaningful message on errors when writing base64 images, via #28614
- Fix broken VS Code debugger, via #28643
- Always add both
childField
andchildrenField
in GraphQL to avoid schema inference errors, via #28656 - Fix obscure
undefined failed
message for webpack compilation errors, via #28701 gatsby-plugin-mdx
: performance improvements during sourcing, via #27974gatsby-source-graphql
: add HTTP error reporting, via #28786gatsby-source-filesystem
: retry a download increateRemoteFileNode
if a file is incomplete, via #28547gatsby-plugin-schema-snapshot
: fix warningThe type Foo does not explicitly define the field childBar
, via #28483gatsby-source-contentful
: dont re-create nodes unnecessarily, via #28642
Contributors
A big Thank You to our community who contributed to this release ๐
- mdb571: docs: update styling-css.md PR #28581
- erezrokah: chore(plugin-netlify-cms): update Slack link PR #28529
- ax-vasquez: Fix broken import statement (#28611) PR #28611
- runningdeveloper: Fixed typo brackets in file-system-route-api.md PR #28612
- herecydev: chore: update ink to v3 PR #26190
- gugu: feat(gatsby): Add AVIF file support to image loader in webpack config PR #28638
- angristan: fix(docs): dead links sourcing-data -> querying-data PR #28651
- jbampton: docs: fix spelling PR #28665
- connor4312: fix(gatsby): Do not activate inspect if already active PR #28643
- antoinerousseau: feat(gatsby-source-graphql): Default Apollo Link fetch wrapper to show better API errors PR #28786
December 15 2020
Welcome to gatsby@2.29.0
release (December 2020 #2)
Key highlights of this release:
- Query on Demand - improves
gatsby develop
bootup time - Lazy Images - do not wait for all images to be processed to start the development
- Improvements to our CLI - improved
create-gatsby
& newplugin
command - Experimental: Parallel data sourcing - run source plugins in parallel to speedup sourcing on sites with multiple source plugins
Other notable changes:
- Performance improvements
- Slugify option for File System Route API
gatsby-image
codemod- 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.
Query on Demand
Starting with v2.29, 10% of our users are automatically opt-in to this feature. We've first shipped this feature behind a flag in v2.27 and feel confident now that more people can try it out. Opt-in users will receive a notice in their terminal about that opt-in behavior and a hint on how to turn it off (in case it disturbs your workflow). As a recap of what Query on Demand will improve:
Gatsby will run queries for pages as they're requested by a browser. Think of it like lazily loading the data your pages need, when they need it! This avoids having to wait for slower queries (like image processing) if you're editing an unrelated part of a site. What this means for you: faster local development experience, up to 2x faster in many cases!
By slowly rolling out this feature to more and more users we'll be getting closer to a GA (general availability) release that will benefit all users of Gatsby. Please give us your feedback in the umbrella discussion.
If you want to turn it on/off, you can set the corresponding flag inside gatsby-config.js
:
// In your gatsby-config.js
module.exports = {
flags: {
QUERY_ON_DEMAND: false,
},
plugins: [], // your plugins stay the same
}
In v2.29 we improved the UX around it by adding a loading indicator and message to the browser console (only in gatsby develop
). If you want or need to de-activate this indicator, you can! For more details please see the umbrella discussion. Here's a preview of them in action:
Loading indicator
The loading indicator respects the user's settings for prefers-reduced-motion
and prefers-color-scheme
. It also announces itself to screen readers.
Browser console
Lazy Images
Similarly as with Query on Demand also Lazy Images will be automatically delivered to 10% of our users with this v2.29 release. We've first shipped this feature behind a flag in v2.28. Opt-in users will receive a notice in their terminal about that opt-in behavior and a hint on how to turn it off (in case it disturbs your workflow). As a recap of what Lazy Images will improve:
As more and more images are added to a Gatsby site, the slower the local development experience oftentimes becomes. You spend time waiting for images to process, instead of you know, developing! No longer! This experimental version of
gatsby-plugin-sharp
only does image processing when the page gets requested.
By slowly rolling out this feature to more and more users we'll be getting closer to a GA release that will benefit all users of Gatsby. Please give us your feedback in the umbrella discussion.
If you want to turn it on/off, you can set the corresponding flag inside gatsby-config.js
:
// In your gatsby-config.js
module.exports = {
flags: {
LAZY_IMAGES: false,
},
plugins: [], // your plugins stay the same
}
Improvements to our CLI
In v2.27 we introduced create-gatsby
, a new and interactive way to create a Gatsby site. You can run it in your terminal with npm init gatsby
.
A couple of papercuts were fixed but we also added new features:
- Prompt for your site name instead of a folder name
- Automatically add this name to your
siteMetadata
andpackage.json
- Add
-y
flag. This flag bypasses all prompts other than naming your site
The regular gatsby-cli
received a new command to list out all plugins in your site by running gatsby plugin ls
.
Experimental: Parallel data sourcing
In v2.28 we gave a sneak peek at a new feature that enables parallel data sourcing. As a recap:
Plugin APIs in Gatsby run serially. Generally this is what we want as most API calls are CPU/IO bound so things are fastest letting each plugin have the full undivided attention of your computer. But source plugins are often network bound as they're hitting remote APIs and waiting for responses. We tried changing the invocation of
sourceNodes
to parallel on a few sites with 4+ source plugins and saw a big speedup on sourcing (40%+) as they were no longer waiting on each other to start their API calls.
You're now able to activate this experiment in the stable release of Gatsby by adding a flag to your gatsby-config.js
:
// In your gatsby-config.js
module.exports = {
flags: {
PARALLEL_SOURCING: true,
},
plugins: [], // your plugins stay the same
}
Please give us your feedback in the umbrella discussion.
Performance improvements
We were able to ship a bunch of performance improvements both to Gatsby itself and its plugins:
gatsby
- Improve query running performance for sites with large amount of data (up to 10% in our tests). See https://github.com/gatsbyjs/gatsby/pull/28525 for details.
gatsby-source-contentful
- Improve performance of data sourcing for large Contentful spaces. See https://github.com/gatsbyjs/gatsby/pull/28375 for details.
- Prevent concurrent requests to Contentful's image processing API. See https://github.com/gatsbyjs/gatsby/pull/28438 for details.
Slugify option for File System Route API
The File System Route API uses slugify to create slugs for the generated routes. You're now able to pass custom options to that instance, e.g. when you want to change the separator. The full details are listed in the README of gatsby-plugin-page-creator
.
gatsby-image
codemod
We introduced some API changes for working with images when we published the new gatsby-plugin-image
in v2.26. In order to make it easier to migrate your code to work with the new plugin, we've created a codemod. Follow the migration instructions in the README in order to run the codemod against your project.
Notable bugfixes
- Scroll restoration issue in the browser API was fixed in #27384 that affected e.g. page transitions
- Do not fail in develop when eslint loader is removed in #28494
- Respect hash as source of truth for scroll position in #28555
- Wait for jobs to complete in
onPostBuild
in #28534 - Truncated long terminal messages fixed in #26190
Contributors
A big Thank You to our community who contributed to this release ๐
- bappr: Update kintohub documentation with kintohub V1 deployment PR #27016
- axe312ger
- olisteadman: Tell user to supply BOTH keys in .env.development. PR #28405
- galihmelon: [docs][guides] improvements to Why Gatsby Uses GraphQL #15235 PR #27640
- sreeharisj23: Remove Broken Link. PR #28412
- vrabe: fix(gatsby): scroll restoration issue in browser API PR #27384
- WillMayger: fix(gatsby): re-render route when location state changes PR #28346
- kasipavankumar: chore(gatsby-plugin-manifest): Update pluginOptionsSchema link PR #28344
- rburgst: fix: avoid joi validation error when using reporter.panic PR #28291
- davidmauskop: chore(docs): Update Deploying to Render guide PR #28272
- saintmalik: chore(docs): fix broken url PR #28197
- muescha: fix(docs): document pluginOptionsSchema - add file extension, code block language, quotation marks PR #27844
- herecydev & hoobdeebla: chore: update ink to v3 PR #26190
December 01 2020
Welcome to gatsby@2.28.0
release (December 2020 #1).
Key highlights of this release:
- New
gatsby new
- new, interactive way to create a Gatsby site - Feature flags in
gatsby-config.js
- set your feature toggles without environment variables - Improved Fast Refresh integration - better hot reloading
- Experimental: Lazy images in develop - run image transformations only when they are needed by browser
Other notable changes:
- Image plugin helpers - make it easier for plugin authors to support the new gatsby image plugin
- Experimental: New cache clearing behaviors - we're experimenting with ways to be smarter about clearing caches
gatsby-plugin-emotion
v5.0 - now uses emotion v11- Removed experimental lazy page bundling
- Notable bugfixes
Sneak peek to next releases:
- Experimental: Parallel data sourcing - run source plugins in parallel to speedup sourcing on sites with multiple source plugins
Bleeding Edge: Want to try new features as soon as possible? Install gatsby@next
and let us know
if you have any issues.
gatsby new
New In previous release we added interactive way of scaffolding new gatsby project (with npm init gatsby
). As of this release, gatsby new
(without any addition arguments) will use the same flow.
gatsby-config.js
Feature flags in Gatsby traditionally used environment variables to use various modes or enable experimental features. This worked, but it was far from pleasant and had many issues, notably:
- Setting environment variables has idiosyncrasies across platforms (it's different for Windows and different for Linux or MacOS)
- Forced using NPM scripts (and correlating environment variables in continuous deployment solutions like Gatsby Cloud)
No longer! Now you can use flags in gatsby-config.js
, which will work the same regardless of which environment you're on, where you're deploying, and for every member of your team! Woo hoo!
To use those, add flags
to your gatsby-config.js
:
// In your gatsby-config.js
module.exports = {
// your existing config
flags: {
FAST_DEV: true,
},
}
Currently supported flags:
DEV_SSR
- Server-side render (SSR) pages on full reloads during develop. Helps you detect SSR bugs and fix them without needing to do full builds.QUERY_ON_DEMAND
- Only run queries when needed instead of running all queries upfront. Speeds starting the develop server.LAZY_IMAGES
- Don't process images during development until they're requested from the browser. Speeds starting the develop server (requiresgatsby-plugin-sharp@^2.10.0
). See Experimental: Lazy images in develop section for additional details.FAST_DEV
- Umbrella flag that enablesDEV_SSR
,QUERY_ON_DEMAND
andLAZY_IMAGES
features.FAST_REFRESH
- Use React Fast Refresh instead of the legacyreact-hot-loader
for instantaneous feedback in your development server. Recommended for versions of React >= 17.0.
Improved Fast Refresh integration
Gatsby had some support for react-refresh
(or Fast Refresh as it can be referred to) already. The PR for a preliminary Fast Refresh integration added a custom overlay, better error recovery and in general a better communication between Gatsby's dev server and React Fast Refresh. This will give you quicker feedback and an overall improved development experience.
To use it, add a flag to your gatsby-config.js
:
// In your gatsby-config.js
module.exports = {
// your existing config
flags: {
FAST_REFRESH: true,
},
}
Visit the umbrella issue about Fast Refresh to see preview images and give feedback.
gatsby develop
faster
Making We continue working on speeding up your local development server. We need your help to test out these experiments and provide feedback, so please check 'em out! ๐
Experimental: Lazy images in develop
As more and more images are added to a Gatsby site, the slower the local development experience oftentimes becomes.
You spend time waiting for images to process, instead of you know, developing! No longer!
This experimental version of gatsby-plugin-sharp
only does image processing when the page gets requested.
To use it, make sure you have gatsby-plugin-sharp@^2.10.0
and add LAZY_IMAGES
to flags in gatsby-config.js
:
// In your gatsby-config.js
module.exports = {
// your existing config
flags: {
LAZY_IMAGES: true,
},
}
Image plugin helpers
This release adds new utility functions to help plugin authors add support for the new Gatsby image component. If you maintain a source plugin, or if you want to help with one, take a look at the RFC.
Experimental: New cache clearing behaviors
Gatsby aggressively clears its cache, sometimes too aggressively. Here's a few examples:
- You
npm install
a plugin, or update an existing - You change your
gatsby-node.js
and add a few log statements - You change your
siteMetadata
ingatsby-config.js
to update your site's title
In all of these cases, your cache is entirely cleared, which means that the next time you run gatsby develop
the experience is slower than it needs to be. We'll be working on this to ensure that your first run, and every run thereafter, is as quick and speedy as you expect!
We added two new flags for the webpack and downloaded files caches that when enabled, will preserve these caches across changes. We'll be evaluating their impact and safety to assess whether these can soon be enabled, by default. Please test and give feedback!
To enable, modify your gatsby-config.js
as follows:
module.exports = {
// your existing config
flags: {
PRESERVE_WEBPACK_CACHE: true,
PRESERVE_FILE_DOWNLOAD_CACHE: true,
},
}
gatsby-plugin-emotion@5.0.0
The plugin is updated to the new major version of emotion: v11. Check out this post in emotion docs for updates.
Removed experimental lazy page bundling
In gatsby@2.27.0
we added Experimental: Lazy page bundling mode for gatsby develop
that would delay compiling page templates until it was needed. While preliminary tests were very promising, we discovered few showstoppers that degraded development experience. We decided to end the experiment for now and shift our efforts to (experimental) new cache clearing behaviors.
Notable bugfixes
- fix: hot reloading hangs on multiple fast saves in develop #28237
- fix error:
The result of this StaticQuery could not be fetched
when static query is added #28349
Work in progress
Experimental: Parallel data sourcing
Plugin APIs in Gatsby run serially. Generally this what we want as most API calls are CPU/IO bound so things are fastest letting each plugin have the full undivided attention of your computer. But source plugins are often network bound as they're hitting remote APIs and waiting for responses. We tried changing the invocation of sourceNodes
to parallel on a few sites with 4+ source plugins and saw a big speedup on sourcing (40%+) as they were no longer waiting on each other to start their API calls.
This is a very "Your mileage may vary" situation โ not all sites will notice any difference and also not all source plugins are network bound (gatsby-source-filesystem
reads from the local machine). We're looking at finding better heuristics so that all sites are as fast as possible at data sourcing but in the meantime, if you have sites with multiple source plugins, this could be a big help.
You can try it today using gatsby@next
version and adding a flag to your gatsby-config.js
:
// In your gatsby-config.js
module.exports = {
// your existing config
flags: {
PARALLEL_SOURCING: true,
},
}
Contributors
A big Thank You to our community who contributed to this release ๐
- styxlab: fix(gatsby-source-filesystem): fix race condition when using
publicURL
field PR #28176 - visualfanatic: link to issue fixed inside release notes PR #28193
- oorestisime: feat(gatsby-plugin-sitemap): allow
serialize
plugin option to be async function PR #28207 - theskillwithin: breaking(gatsby-plugin-emotion): update to emotion@11 PR #27981
- hassankhan: fix(gatsby-transformer-remark): ensure
getNodesByType()
is passed through PR #28218 - nina-py: chore(gatsby-cli): Bump up update-notifier version to 5.0.1 PR #28273
- leerob: Add Vercel Analytics to documentation. PR #27841
- KKVANONYMOUS: chore(docs): Fix link to inc builds PR #28306
- jmiazga: fix(gatsby-recipes): updated chakra ui recipe after v1 release PR #28270
- blainekasten: feat(gatsby): Add preliminary fast-refresh integration PR #26664
November 19 2020
Welcome to gatsby@2.27.0
release (November 2020 #2).
Key highlights of this release:
create-gatsby
- new, interactive way to create a Gatsby site- Experimental: Queries on Demand - improves
gatsby develop
bootup time - Experimental: Lazy page bundling - also improves
gatsby develop
bootup time - Experimental: SSR in develop - catch SSR errors early
gatsby-plugin-mdx@1.5.0
- new option for better performance- Notable bugfixes
Sneak peek to next releases:
Bleeding Edge: Want to try new features as soon as possible? Install gatsby@next
and let us know if you have any issues.
create-gatsby
There is now a new, interactive way to create a Gatsby site. As long as you have Node.js installed you're ready to go.
npm init gatsby
This command will ask a series of questions, allowing you to select your CMS, preferred styling tools and common Gatsby plugins. After you've made your selections let the installation complete and you'll have a working Gatsby site, all packages included and configured for use.
gatsby develop
faster
Making The Gatsby develop server can get slow to start on larger sites. We're working hard to speed it up. We're addressing different scaling problems one by one and have shipped several improvements behind flags as detailed below. If you'd like to enable all these dev speedups (along with all future ones!), we've created a single flag for you. Run your site like GATSBY_EXPERIMENTAL_FAST_DEV=true gatsby develop
and zoom zoom!
Experimental: Queries on Demand
When developing a Gatsby site there's no need to run all graphql queries before serving the site. Instead, Gatsby will run queries for pages as they're requested by a browser. Think of it like lazily loading the data your pages need, when they need it!
This avoids having to wait for slower queries (like image processing) if you're editing an unrelated part of a site. What this means for you: faster local development experience, up to 2x faster in many cases!
This feature is available under a flag.
GATSBY_EXPERIMENTAL_QUERY_ON_DEMAND=1 gatsby develop
Please try it and let us know if you have any issues
(it may become a default for develop
in the future)
Experimental: SSR in Development
One of the least enjoyable bugs to encounter in Gatsby is when your build fails due to code trying to reference window
or document
or other browser globals that are not accessible in Node.js during SSR.
Currently the only way to debug these is to change some code and rebuild and repeat until the problem is solved. This is a very slow way to debug. Worst, these sorts of bugs are often only encountered after a long development period. It's no fun to push code you're proud of to CI only to discover it's broken.
With this coming feature, we'll SSR pages during development when do a full refresh of a page (navigating between pages will still only do a client-side render). This will help you both discover build errors earlier and fix them faster.
Try it out immediately by running GATSBY_EXPERIMENTAL_DEV_SSR=true gatsby develop
. Join in the discussion in its umbrella issue.
Experimental: Lazy page bundling in development
UPDATE: After a number of community members tested the change on their website, we decided it wasn't going to work out โ https://github.com/gatsbyjs/gatsby/discussions/28137#discussioncomment-138998
An obstacle to Gatsby being a delightful experience for larger sites is JavaScript compilation can start to get annoyingly slow. For example, gatsbyjs.com takes over two minutes currently (with a cold cache) to compile and bundle the code for the many page components. Not acceptable!
We knew we needed to make this lazy and have shipped experimental support for this.
Now when you run GATSBY_EXPERIMENT_DEVJS_LAZY=true gatsby develop
, webpack won't look at any of your page components until you visit them. You'll notice a slight (generally under 0.5s) delay when you first visit a page while webpack compiles it but thereafter, it'll be instantaneous.
All sites should see some speedups but it's especially noticeable for larger sites like gatsbyjs.com which now starts webpack 81% faster than before! Please test it out and tell us how fast your dev server boots up over at the umbrella issue along with any bugs you might run across.
gatsby-plugin-mdx@1.5.0
Adds a lessBabel
option to the plugin which allows you to use a fast path for scanning exports during sourcing. The savings are significant, especially at scale, but as the new scanner does not use Babel, if your site depends on Babel then you can't use this. Please give the option a try and report any problems unrelated to not running Babel so we can improve the support.
See PR #27941
Notable bugfixes
Work in progress
Experimental: Lazy images in develop
We've got some feedback that the more images your website contains, the slower your local development experience gets.
You spend time waiting for images to process, instead of you know, developing! No longer!
This experimental version of gatsby-plugin-sharp
only does image processing when the page gets requested.
Try early alpha (and let us know if you have any issues with it):
npm install gatsby-plugin-sharp@lazy-images
Lazy images are enabled by-default in this version.
Documentation Reorganization
Weโve heard repeatedly from the community that Gatsby is a powerful tool, but it has a steep learning curve. We want to make it easier to get started with Gatsby. And that means having documentation that helps yโall find the information you need when you need it.
Contributors
A big Thank You to our community who contributed to this release ๐
- jerrydevs: fix(gatsby-transformer-asciidoc): fails when doc doesn't have title PR #27865
- shoxton
- vhiairrassary: Fix #26359: Support HTTPS for the develop status server PR #27955
- stefanjudis: docs(gatsby-source-contentful): clean up changelog PR #28000
- lellky: chore(docs): Update add-seo-component PR #28022
- MichaelDeBoey
- trevorblades: Make optional SVG favicon come after the fallback PR #27843
- moonmeister: fix(plugin-manifest): Allow for all valid WebAppManifest properties PR #27951
- nm123github: add query pluginOption for mongodb plugin PR #27756
- sreeharisj23: chore: change .org to .com PR #28053
- DecliningLotus: chore(docs): replace typefaces with fontsource PR #27313
- yaacovCR: chore(gatsby-source-graphql): upgrade graphql-tools to v7 PR #27792
November 12 2020
Welcome to gatsby@2.26.0
release (November 2020).
Key highlights of this release:
- New Image Plugin (beta) - access static images without GraphQL, high Lighthouse scores again
- File System Route API - create routes from your data using filename conventions
- New Release Process - more stability and clarity around Gatsby releases
gatsby-source-contentful
v4.0 - new RichText implementation, performance improvements
Other notable changes:
gatsby-plugin-mdx
- performance improvements- Enable compression in the dev server - speeds up remote previews
Sneak peek to next releases:
- Queries on Demand - improves
gatsby develop
bootup time - Experimental: Lazy images in develop
- Documentation Reorganization
Bleeding Edge: Want to try new features as soon as possible? Install gatsby@next
and let us know
if you have any issues.
New Release Process
We are evaluating a new process that should bring more stability and clarity to Gatsby releases.
File System Route API
This new API enables you to create routes from your GraphQL data using filename conventions, e.g. to create individual blog post pages for your blog. It also allows for creating client-only routes more easily.
Some examples:
src/pages/products/{Product.name}.js
will generate pages for all products with a path like/products/burger
src/pages/products/{Product.fields__sku}.js
will generate pages for all products with a path like/products/001923
src/pages/users/[id].js
will generate a route like/users/:id
src/pages/image/[...].js
will generate a route like/image/*
See full documentation, examples and related PR #27424.
Enable compression in the dev server
This lowers the amount of data transferred for one site especially in remote situations.
Most of that drop was from the commons.js
bundle.
See PR #27948 for details.
gatsby-plugin-image@0.1.0
(beta)
New image plugin to replace gatsby-image
, which greatly improves performance (Lighthouse ๐ฏ again) and adds easy static images (no GraphQL). Part of it is also a new, simpler API for gatsby-transformer-sharp
.
StaticImage
This component is a new, simpler way to use Gatsby's image processing for static images without needing to write GraphQL queries:
import React from "react"
import { StaticImage } from "gatsby-plugin-image"
export const Dino = () => (
<StaticImage width={100} height={100} src="trex.png" alt="T-Rex" />
)
GatsbyImage
This is a complete rewrite of the Gatsby Image component, using native lazy loading whenever possible. In our tests it allows sites whose Lighthouse scores dropped in recent updates to get back to 100s across the board.
Simpler GraphQL for non-static images
Instead of having to remember lots of different fragments for different image types, you can pass all your options as field arguments (and get inline help in GraphiQL):
query {
file(relativePath: { eq: "plant.jpg" }) {
childImageSharp {
gatsbyImageData(maxWidth: 720, layout: FLUID, placeholder: TRACED_SVG)
}
}
}
You then use the data like this:
import { GatsbyImage, getImage } from "gatsby-plugin-image"
export function Plant({ data }) {
const imageData = getImage(data.file)
return <GatsbyImage image={imageData} alt="Plant" />
}
gatsby-source-contentful@4.0.0
New Rich Text Implementation
Breaking Change: New rich text implementation for performance and usability. This is only a breaking change if you rely on the Rich Text Contentful field type.
See PR #25249 description for details and migration guide.
Performance improvements
The max of pageLimit
option was raised from 100
to 1000
(on Contentful's side) which should lead
to significant reduction of remote fetching times.
Note that the default value for the pageLimit
option is still 100
, so you need to change
it manually in your site config to see performance improvements.
Due to technical limitations, the response payload size is still bound by a hard chunk download size, so it is possible you may need to use a lower value for your particular site.
gatsby-plugin-mdx@1.4.0
There was a significant performance improvement by making a certain node fetching step lazy. This is especially noticeable at scale. See PR #27937 for details.
Work in progress
Queries on Demand
When developing a Gatsby site there's no need to run all graphql queries before serving the site. Instead, Gatsby could run queries for pages as they're requested by a browser. This would avoid having to wait for slower queries (like image processing) if you're editing an unrelated part of a site.
Try early alpha (and let us know if you have any issues with it):
npm install gatsby@qod
Enable in your gatsby-config.js
:
module.exports = {
// your existing configuration
__experimentalQueryOnDemand: true,
}
Experimental: Lazy images in develop
We've got some feedback that the more image-heavy your website gets, the slower gatsby develop
.
This experimental version of gatsby-plugin-sharp
only does image processing when the page gets requested.
Try early alpha (and let us know if you have any issues with it):
npm install gatsby-plugin-sharp@lazy-images
Lazy images are enabled by-default in this version.
Documentation Reorganization
Weโve heard repeatedly from the community that Gatsby is a powerful tool, but it has a steep learning curve. We want to make it easier to get started with Gatsby. And that means having documentation that helps yโall find the information you need when you need it.
Contributors
A big Thank You to our community who contributed to this release ๐
- muescha
- MichaelDeBoey: chore(gatsby-plugin-cxs): Add pluginOptionsSchema validation PR #27600
- davad: fix(docs): Update documentation for createPages PR #27735
- me4502: fix(gatsby-plugin-sitemap): fixed missing sitemapSize config entry PR #27866
- axe312ger
- Refactor Rich Text implementation in gatsby-source-contentful PR #25249
- ARKEOLOGIST: fix(gatsby-plugin-google-tagmanager): allow functions for defaultDataLayer option PR #27886
- hoobdeebla: fix(renovate): move express-graphql and react-reconciler from minor to major update groups PR #27101
- StephanWeinhold: chore(docs): Add required
path
import to modifying-pages doc PR #27883 - ervasive: fix(gatsby): Update TS types to allow Node 'parent' to be nullable PR #26570
- manavm1990: chore(docs): Add children to styled-components doc PR #27011
- kadhirash: fix(docs): dictionary.txt -> KintoBlock-kintoblock PR #27580
- jerrydevs: fix(gatsby-transformer-asciidoc): fails when doc doesn't have title PR #27865