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

#5.9.0

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.

Previous release notes

Full changelog

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

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#5.8.0

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.

Previous release notes

Full changelog

Notable bugfixes & improvements

  • gatsby:
    • Regenerate HTML when lazily imported component changes, via PR #37712
    • Invalidate webpack cache when gatsby-node.mjs changes, via PR #37750
  • gatsby-plugin-page-creator: Correctly recreate deleted pages during gatsby develop, via PR #37745
  • gatsby-plugin-mdx: Account for links and inline code in table of contents, via PR #37789
  • gatsby-source-wordpress: Add compatibility with WPGraphQL version 1.14.0, via PR #37749

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#5.7.0

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.

Previous release notes

Full changelog

Notable bugfixes & improvements

  • gatsby: Improve memory usage in gatsby develop command, via PR #37619
  • gatsby-source-contentful: Fix engine validation, via PR #37660

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#5.6.0

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.

Previous release notes

Full changelog

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.

Head API supports context providers from wrapRootElement

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:
    • Fix static query mapping when contentFilePath contains a space, via PR #37544
    • Bump @gatsbyjs/reach-router to fix husky install issue, via PR #37547
    • Support Slices in DEV_SSR, via PR #37542
    • Move react-dom-server out of framework chunks, via PR #37508
  • gatsby-plugin-utils: Export two IRemoteFile utility types, via PR #37532

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#5.5.0

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.

Previous release notes

Full changelog

Faster Hashing for gatsby-source-filesytem

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 and mtime 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 the inode and mtime. 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.

Setting <html> and <body> attributes

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 when pathPrefix and/or assetPrefix is used, via PR #37423
    • fix pluginOptionsSchema not being called for local plugins with gatsby-node.ts, via PR #37443
    • support updated sort argument syntax in nodeModel.findAll function, via PR #37477
  • 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 ๐Ÿ’œ

#5.4.0

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.

Previous release notes

Full changelog

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 from 0.6.0 to 0.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

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#5.3.0

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.

Previous release notes

Full changelog

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 #37087
  • gatsby:
    • Add documentSearchPaths option to graphqlTypegen, via PR #37120
    • Materialize nodes in gatsbyPath, via PR #37111
  • gatsby-plugin-utils: Add pathPrefix to Image CDN URLs, via PR #36772
  • Miscellaneous dependency updates:

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#5.2.0

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.

Previous release notes

Full changelog

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 #37062
  • gatsby-source-drupal: Provide proxyUrl in addition to baseUrl to allow using CDN, API gateway, etc., via PR #36819
  • gatsby-cli: We changed our error messages a little bit. You should see a more detailed type beside the error ID now
  • gatsby: Sanitize length on objects, via PR #34253

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#5.1.0

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.

Previous release notes

Full changelog

Notable bugfixes & improvements

  • gatsby:
    • Fix writing of static query files when automatic sort and aggregation graphql codemod is run, via PR #36997
    • Fix graphql@16 peer dependency problems by migrating from express-graphql to graphql-http, via PR #37001
    • Use XState predictableActionArguments and upgrade to latest, via PR #36342
  • 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
  • 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 ๐Ÿ’œ

#5.0.0

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.

Full changelog

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:

Diagram of building a header with Gatsby Slice

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:

Two stylized browser windows on the left and right side. The left one has the title "Full Hydration", the right one "Partial Hydration". Both browser windows have a stylized web page (with header, content, footer, etc.) with mostly static content except for an interactive gallery. The left window has its complete window marked blue (as the full page hydrates), the right one only the interactive gallery (because of Partial Hydration).

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 and react-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

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 and gatsby-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 ๐Ÿ’œ

#4.24.0

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.

Previous release notes

Full changelog

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 the React is not defined error, via PR #36595
  • gatsby-remark-copy-linked-files: Add absolutePath to dir function, via PR #36213
  • gatsby & gatsby-plugin-mdx: Fix "Multiple root query" error when using a name for your MDX template, via PR #36525
  • gatsby-parcel-config: The underlying Parcel config (used for compiling gatsby-config.ts and gatsby-node.ts files) was changed to only handle JavaScript/TypeScript. This aligns the behavior with current Node.js capabilities of gatsby-config.js/gatsby-node.js (e.g. you can't just import YAML files), via PR #36583
  • gatsby: Source maps are available for gatsby-config.ts/gatsby-node.ts files, via PR #36450

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.23.0

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.

Previous release notes

Full changelog

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:

  1. Create the slice by adding a slices/footer.js file, or using the createPages API action:

    actions.createSlice({
  id: `footer`,
  component: require.resolve(`./src/components/footer.js`),
})

  2. Add a <Slice /> component on your site, providing an alias string prop, where alias is either name of the file (in our case, footer). Any additional props passed will be handed down to the underlying component.

    return (
  <>
    <Header className="my-header" />
    {children}
    <Slice alias="footer" />
  </>
)

To read more, head over to RFC: Slices API. We appreciate any feedback there.

Changes in sort and aggregation fields in Gatsby GraphQL Schema

We are proposing Breaking Changes for the next major version of Gatsby to our GraphQL API. The goal of this change is increasing performance and reducing resource usage of builds. Proposed changes impact sort and aggregation fields (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:
    • Improve webpack tree shaking of gatsby-browser-entry imports, via #36484
    • Support node: protocol in engine bundling, via #36506
    • Improve error handling during React 18's renderToPipeableStream, via #36555
    • Inject context passed by createResolverContext action when materializing fields, via #36552
  • gatsby-source-wordpress:
    • Match full urls when replacing media item links, via #36447
    • Ensure node data replacements for post updates, via #36474
  • gatsby-plugin-sharp:
    • Upgrade svgo dependency to fix vulnerability, via #36445
  • 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 ๐Ÿ’œ

#4.22.0

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.

Previous release notes

Full changelog

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:

  1. Create the slice by adding a slices/footer.js file, or using the createPages API action:

    actions.createSlice({
  id: `footer`,
  component: require.resolve(`./src/components/footer.js`),
})

  2. Add a <Slice /> component on your site, providing an alias string prop, where alias is either name of the file (in our case, footer). Any additional props passed will be handed down to the underlying component.

    return (
  <>
    <Header className="my-header" />
    {children}
    <Slice alias="footer" />
  </>
)

To read more, head over to RFC: Slices API. We appreciate any feedback there.

Changes in sort and aggregation fields in Gatsby GraphQL Schema

We are proposing Breaking Changes for the next major version of Gatsby to our GraphQL API. The goal of this change is increasing performance and reducing resource usage of builds. Proposed changes impact sort and aggregation fields (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
    • Add option to emit TypeScript types during gatsby build, via PR #36405
    • Fix issue where TypeScript retry mechanism would cause Windows to crash Gatsby while Parcel cache is open, via PR #36377
    • Prevent errors when the Head component has a root text node, via PR #36402
  • gatsby-cli: Preserve verbosity in spawn child processes, via PR #36399
  • gatsby-source-graphql: we have "soft deprecated" this package in favor of other, CMS-specific source plugins
  • gatsby-plugin-mdx
    • Fix issue with plugin options from e.g. gatsby-remark-images not getting passed through, via PR #36387
    • Fix issue with too long chunk names, via PR #36387
  • gatsby-plugin-image: Fix bug that prevents onLoad being called on first load, via PR #36375

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.21.0

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.

Previous release notes

Full changelog

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 add remark or rehype 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:

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:

  1. Create the slice by adding a slices/footer.js file, or using the createPages API action:

    actions.createSlice({
  id: `footer`,
  component: require.resolve(`./src/components/footer.js`),
})

  2. Add a <Slice /> component on your site, providing an alias string prop, where alias is either name of the file (in our case, footer). Any additional props passed will be handed down to the underlying component.

    return (
  <>
    <Header className="my-header" />
    {children}
    <Slice alias="footer" />
  </>
)

To read more, head over to RFC: Slices API. We appreciate any feedback there.

Changes in sort and aggregation fields in Gatsby GraphQL Schema

We are proposing Breaking Changes for the next major version of Gatsby to our GraphQL API. The goal of this change is increasing performance and reducing resource usage of builds. Proposed changes impact sort and aggregation fields (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 to 0.30.7 (also in all other related packages). This deprecates the failOnError option as it's being replaced by the failOn option, via PR #35539
  • gatsby:
    • Fix e.remove() is not a function error when using Gatsby Head API, via PR #36338
    • Make inline scripts run in develop, via PR #36372
    • Make runtime error overlay work in non-v8 browsers, via PR #36365
  • gatsby-source-contentful: Correctly overwrite field type on Assets, via PR #36337
  • gatsby-plugin-react-helment: Stop appending empty title tags, via PR #36303
  • gatsby-link: Correctly export default for CommonJS, via PR #36312

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

  • Bi11: fix(gatsby-plugin-image): Add outputPixelDensities to SHARP_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
#4.20.0

August 02 2022

Welcome to gatsby@4.20.0 release (August 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.

Previous release notes

Full changelog

RFC for changes in sort and aggregation fields in Gatsby GraphQL Schema

We are proposing Breaking Changes for the next major version of Gatsby to our GraphQL API. The goal of this change is increasing performance and reducing resource usage of builds. Proposed changes impact sort and aggregation fields (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.

Release Candidate for gatsby-plugin-mdx v4

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 for gatsby 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 in gatsby serve, via PR #36231
    • Improved performance of sorting, filtering and aggregation on fields with custom resolvers, via PR #36253
  • gatsby-plugin-sass
    • Added support for additionalData option, via PR #36086
  • gatsby-plugin-sharp
    • Ensure min 1px height for BLURRED placeholder, via PR #35914
  • gatsby-plugin-utils
    • fixed IMAGE_CDN and FILE_CDN handling for urls requiring encoding, via PR #36179
  • gatsby-source-wordpress
    • Added option to disable automatic use of gatsby-plugin-catch-link through setting catchLinks: false in gatsby-source-wordpress plugin options, via PR #36141
  • 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 ๐Ÿ’œ

#4.19.0

July 19 2022

Welcome to gatsby@4.19.0 release (July 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.

Previous release notes

Full changelog

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.

Release Candidate for gatsby-plugin-mdx v4

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, and gatsby-core-utils both as CJS & ESM, via PR #36012 and PR #36020
  • gatsby
    • Sanitize page state to remove non-serializable elements, via PR #36074
    • Remove the /___services endpoint and remove development proxy. Also remove proxyPort (aliased to port for now). Via PR #35675

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.18.0

July 05 2022

Welcome to gatsby@4.18.0 release (July 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.

Previous release notes

Full changelog

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
    • Add retry mechanism for gatsby-node/config.ts compilation to fix intermittent bug during gatsby build, via PR #35974
    • Fix potentially wrong query results when querying fields with custom resolvers, via PR #35369
  • gatsby-cli: Set NODE_ENV earlier to fix Jest failing with Couldn't find temp query result error, via PR #35968
  • gatsby-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 reduce lodash size published packages, via PR #35947

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.17.0

June 21 2022

Welcome to gatsby@4.17.0 release (June 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.

Previous release notes

Full changelog

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:
    • Improve error message when engines try to bundle ts-node, via PR #35762
    • Stabilize types output of GraphQL typegen, via PR #35925
  • gatsby-source-drupal: Fix not found image urls failing builds, via PR #35855
  • gatsby-source-wordpress: Refactor option check, via PR #35827
  • gatsby-transformer-documentationjs: Add support for JSX files, via PR #35899

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.16.0

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.

Previous release notes

Full changelog

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 as source-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:
    • Remove exports in Gatsby files before compiling SSR/DSG engines, via PR #35749
    • Prioritize raw body parser, via PR #35780
  • gatsby-plugin-preload-fonts: Disable Puppeteer cache, via PR #34633
  • gatsby-source-drupal: Allow sites to configure the request timeout, via PR #35794
  • gatsby-plugin-utils: Add new setRequestHeaders API, via PR #35655
  • gatsby-plugin-utils: Add contentDigest to image cdn args, via PR #35816
  • gatsby-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 ๐Ÿ’œ

#4.15.0

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.

Previous release notes

Full changelog

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 hydrated
  • idle - Loads after the page has become idle
  • off-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 and onError callbacks for post-hydrate and idle 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 your transformIgnorePatterns key in your Jest config since gatsby-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:
    • Improved performance of "Building development bundle", via PR #35641
    • Don't apply trailing slashes to ".pdf" or ".xml" links, via PR #35681
  • gatsby-cli: Default to production NODE_ENV for gatsby serve to be consistent with gatsby build, via PR #35693
  • gatsby-source-wordpress: handle media edit (for example rotation or rename) properly for IMAGE_CDN, via PR #35687
  • gatsby-source-drupal:
    • Warn about corrupt files and don't create enable IMAGE_CDN if skipFileDownloads is not enabled, via PR #35619
    • Add missing placeholderStyleName plugin config option, via PR #35644

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.14.0

May 10 2022

Welcome to gatsby@4.14.0 release (May 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.

Previous release notes

Full changelog

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:

Comparison of before and after this change on gatsbyjs.com. The left side shows "Now", the right one "Before". Both videos show how the hero section of gatsbyjs.com is loaded, below it a number showing the time in seconds is placed.

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.

Preview of the new landing page. At the top it says "Welcome to Gatsby", below that it links to the separate subpages like "TypeScript" or "Server Side Rendering". Then four blocks linking out to sections like the tutorial or examples are shown. The footer contains links to Discord, Documentation, and more.

Notable bugfixes & improvements

  • gatsby-source-contentful:
    • Add support for tables in Rich Text, via PR #33870
    • Add contentTypeFilter option, via PR #35204
  • gatsby: Fixes UNHANDLED EXCEPTION write EPIPE on Netlify, via PR #35513
  • gatsby-plugin-image:
    • Fix image flicker issues between page navigations and/or state updates, via PR #35226
    • The getImage helper function was updated to look for gatsbyImage, via PR #35507
  • gatsby-source-wordpress:
    • Always include Draft slugs for Gatsby Preview via PR #35573.
    • Use Image CDN for non-transformable images in html fields, via PR #35529
    • Prevent GraphQL errors when a union list item is null, via PR #35533

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.13.0

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.

Previous release notes

Full changelog

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
    • Fix static file creation when assets have no id in localFile via PR #35423
    • Opt out of AVIF image generation when not using Gatsby Cloud image service via PR #35370
  • 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 ๐Ÿ’œ

#4.12.0

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.

Previous release notes

Full changelog

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!

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 #35272
  • gatsby-core-utils: Fix exports map for importing from dist via PR #35274
  • gatsby-plugin-sharp: Handle slashes and .. within paths for Windows via PR #35246
  • gatsby-plugin-utils: Fix path pieces being too long in image URLs and make url safely encoded via PR #35160
  • gatsby-source-contentful: Handle backreferences on data updates properly via PR #35214
  • gatsby-source-wordpress: Fix logic for matching image nodes via PR #35324

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.11.0

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.

Previous release notes

Full changelog

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
    • Fix eperm issue on windows when clearing cache, via PR #35154
    • Improve functions compilation error, via PR #35196
  • gatsby-plugin-utils: Support aspect ratio for Image Service, via PR #35087
  • gatsby-source-mongodb: Add optional typePrefix option to override dbName, via PR #33820
  • gatsby-cli: Resolve babel preset ts explicitly, via PR #35153
  • gatsby-plugin-preact: Fix preact alias via PR #35196

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.10.0

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.

Previous release notes

Full changelog

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
    • Fix handling of encoded query params, via PR #34816
    • Fix incorrect "inconsistent node counters" errors, via PR #35025
    • Use gatsby-config.ts file when creating new Gatsby project with TypeScript, via PR #35128
    • Don't write out page-data file if query rerun but result didn't change, via PR #34925
  • gatsby-plugin-sharp
    • Fix MaxListenersExceededWarning messages, via PR #35009
    • Fix generating multiple similar images with different duotone settings, via PR #35075

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.9.0

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.

Previous release notes

Full changelog

Support for TypeScript in gatsby-config and gatsby-node

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 a gatsby-config.js and gatsby-config.ts (where gatsby-config.js registers ts-node) you were able to use TypeScript. You'll need to remove the gatsby-config.js file, ts-node dependency, and address any of the current limitations. When both a gatsby-config.js and gatsby-config.ts exist the .ts file will now always take precedence.

Notable bugfixes & improvements

  • gatsby
    • Cache date formatting in LMDB cache for speed improvements, via PR #34834
    • Batch page dependency actions for speed improvements, via PR #34856

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.8.0

February 22 2022

Welcome to gatsby@4.8.0 release (February 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.

Previous release notes

Full changelog

Support for TypeScript in gatsby-browser and gatsby-ssr

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.

New APIs in gatsby-core-utils and gatsby-plugin-utils

Two new APIs have been added:

  • createMutex in gatsby-core-utils, via PR #34761
  • hasFeature in gatsby-plugin-utils, via PR #34748

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 #34725
  • gatsby:
    • 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
  • gatsby-source-wordpress: Fix Safari image loading bug, via PR #34727
  • gatsby-core-utils: Improvements to fetch-remote-file, via PR #34758

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.7.0

February 08 2022

Welcome to gatsby@4.7.0 release (February 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.

Previous release notes

Full changelog

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.

Faster Schema Creation & createPages

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:
    • Handle export const syntax in pages and don't remove config exports in non-pages, via PR #34581 & PR #34582
    • Fix an issue using a eq: $id filter with files, via PR #34693
  • gatsby-plugin-fullstory: Updated snippet, via PR #34583
  • gatsby-core-utils: Remote file downloads are now queued properly for all cases, via PR #34414
  • gatsby-plugin-preact: Fix alias for react-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 ๐Ÿ’œ

#4.6.0

January 25 2022

Welcome to gatsby@4.6.0 release (January 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.

Previous release notes

Full changelog

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. ![alt text](./some-image.jpg)) 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.

New Major Version for gatsby-plugin-utils

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 keys
  • testPluginOptionsSchema now returns warnings and hasWarnings 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 #34331
  • create-gatsby: Fixed an issue where user-provided GATSBY_TELEMETRY_DISABLED environment variable did not disable telemetry, via PR #34495
  • gatsby-sharp: Create more resilient wrapper around sharp, via PR #34339
  • gatsby-source-contentful: Enable tag support for assets, via PR #34480
  • gatsby: Optimized queries that filter just on id, via PR #34520

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.5.0

January 11 2022

Welcome to gatsby@4.5.0 release (January 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.

Previous release notes

Full changelog

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.

TypeScript Types for getServerData

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
}

Deprecation of gatsby-recipes

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
  • gatsby-plugin-preact: Fix exports resolution to get it working with Gatsby 4, via PR #34337
  • gatsby-source-contentful:
    • Calculate aspect ratio for base64 previews correctly, via PR #33533
    • Fix issue where images were not downloaded when using downloadLocal, via PR #34276
  • gatsby-cli: Make --inspect-brk work with specified port, via PR #34242
  • gatsby-source-filesystem: Replace special filename characters, via PR #34249

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.4.0

December 14 2021

Welcome to gatsby@4.4.0 release (December 2021 #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.

Previous release notes

Full changelog

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 with jsxRuntime option (gatsby-config.js), via PR #34085
  • gatsby: Allow external systems to setup tracing for builds, via PR #34204
  • gatsby-source-filesystem: Ensure that the fastq concurrency parameter is of the correct type, via PR #34186
  • gatsby-plugin-manifest: Consider path prefix when getting localized manifest, via PR #34174
  • gatsby-cli: Fix for --inspect-brk, via PR #34242

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.3.0

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.

Previous release notes

Full changelog

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 #34045
  • gatsby-source-shopify: Fix peerDependencies for gatsby-plugin-image via PR #34044
  • gatsby: Reduce cost of sourcing after the initial, via PR #33692

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.2.0

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.

Previous release notes

Full changelog

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 inside getServerData, 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 to 0.29.2. You can check the CHANGELOG.md file in each package's folder for the details
  • gatsby: Test files inside the src/api (Gatsby Functions) directory are now excluded by default, via PR #33834
  • gatsby-source-wordpress:
    • Fix for 'createRoot' is not exported from 'react-dom' (imported as 'ReactDOM'). warning, via PR #33991
    • Hydrate images in develop on first occurrence, via PR #33989
  • gatsby-core-utils: Add retry on HTTP status codes to fetchRemoteFile, via PR #33461
  • Content Sync:

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.1.0

November 02 2021

Welcome to gatsby@4.1.0 release (November 2021 #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.

Previous release notes

Full changelog

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!

JSX Runtime Options in gatsby-config.js

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: The downloadLocal option is working correctly again, via PR #33715
  • gatsby-plugin-image:
    • Remove flickering and blinking on re-renders, via PR #33732
    • Fix GatsbyImage not displaying image in IE11, via PR #33416
  • gatsby:
    • Cache Query Engine & SSR engine (when you use DSG) to improve build times, via PR #33665
    • Pass pageContext to getServerData(), via PR #33626
  • gatsby-remark-images: Fix figure caption generation when using GATSBY_EMPTY_ALT, via PR #30468
  • gatsby-plugin-sharp: Pass failOnError to sharp when using gatsby-plugin-image, via PR #33547

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#4.0.0

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:

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

Full changelog

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.

CLI showing an overview of all pages. Pages that are DSG are marked with a "D", SSR pages are marked with a "โˆž" and Gatsby Functions are marked with a "ฮป". All other pages are SSG.

Notable bugfixes and improvements

  • gatsby: Reduce page-renderer size, via PR #33051
  • gatsby: Add queue to prefetch, making it less eager. Via PR #33530
  • gatsby-source-wordpress: Use gatsby-plugin-image, via PR #33138

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#3.14.0

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 be gatsby@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:

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.

Previous release notes

Full changelog

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:

  1. Users loads a page
  2. New version of the site is deployed
  3. 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:

New home for gatsby-plugin-netlify

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 #32949
  • gatsby: reduce page-renderer size, via PR #33051
  • gatsby: fix nesting of tracing spans + add docs for OpenTelemetry, via PR #33098
  • gatsby: don't bundle moment locale files, via PR #33092
  • gatsby: add environment variable for setting tracing config file, via PR #32513
  • gatsby: Assign parentSpan to activities that were missing them, via PR #33122
  • gatsby-source-contentful: fix error "Unable to download asset", via PR #33024
  • gatsby-transformer-sqip: ensure failed asset downloads do not break build, via PR #33037
  • gatsby-plugin-google-tagmanager: ability to serve gtm.js from "self-hosted" tagging server, via PR #32733
  • gatsby-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 ๐Ÿ’œ

#3.13.0

August 31 2021

Welcome to gatsby@3.13.0 release (August 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.

Previous release notes

Full changelog

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+

Faster Sourcing for gatsby-source-drupal

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 #32548
  • gatsby: Remove the removeDimensions option from svgo config, via PR #32834
  • gatsby: Hashes and anchors in redirects also work in production, via PR #32850
  • gatsby-plugin-gatsby-cloud: Always create the redirect.json file even if you remove all redirects, via PR #32845
  • gatsby-remark-images: Only convert supported image extensions, via PR #32868
  • gatsby-source-wordpress: Compatibility with Parallel Query Running (PQR), via PR #32779
  • gatsby-core-utils: Switch from deprecated auth option in got to username/password, via PR #32665
  • gatsby: Don't log FAST_DEV messages multiple times, via PR #32961
  • gatsby: Fix for "Static Query cannot be found" error, via PR #32949

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#3.12.0

August 17 2021

Welcome to gatsby@3.12.0 release (August 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.

Previous release notes

Full changelog

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.

Improvements to gatsby-source-shopify

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.

Improvements to gatsby-source-wordpress

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 old exclude option is obsolete, via PR #32509
  • gatsby: Worker support for gatsby develop, via PR #32432
  • gatsby-source-contentful: base64 previews now reflect all query options, via PR #32709
  • gatsby-remark-image-contentful: Show useful error message for files that can not be rendered as image, via PR #32530
  • gatsby: Speed up "Writing page-data" step by ~10%, via PR #32763

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#3.11.0

August 03 2021

Welcome to gatsby@3.11.0 release (August 2021 #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.

Previous release notes

Full changelog

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 in gatsby-config.js per PR #32394
  • gatsby: Correct pagination logic (fixing a regression) per PR #32496
  • gatsby-source-shopify: Add a query for ShopifyLocation and ShopifyInventoryLevel per PR #32450
  • gatsby-plugin-mdx: Performance improvement for a specific usage scenario (multiple GraphQL fields that require MDX processing) per PR #32462
  • gatsby-source-wordpress: Fetch referenced media items during single node updates per PR #32381
  • gatsby-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 ๐Ÿ’œ

#3.10.0

July 20 2021

Welcome to gatsby@3.10.0 release (July 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.

Previous release notes

Full changelog

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 with GATSBY_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...
  • Slow gt filter with GATSBY_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"

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.

Experimental: webpack persistent caching for gatsby develop

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: Update postcss to 8.3.5 to remove deprecation warning on Node v16.
  • gatsby: Switched createRoot to hydrateRoot. 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: Pass search and hash to window.location to final URL of redirect and after the service worker updated, via PR #32334 and PR #32323.
  • gatsby: Avoid the UNHANDLED REJECTION write EPIPE error when using Ctrl + C, via PR #32311 and PR #32356.
  • gatsby: When a gatsby build fails on e.g. missing data it now prints the page-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: Support metadata.tags property, via PR #31746.

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#3.9.0

July 06 2021

Welcome to gatsby@3.9.0 release (July 2021 #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.

Previous release notes

Full changelog

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.

Read more in our blog.

Quality of life improvements to gatsby-source-contentful

  • 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: Bumped express-graphql to 0.12.0 to only have graphql v15 installed via PR #31178
  • gatsby: Prevent generation of polyfill bundle if not needed via PR #31993
  • gatsby-plugin-netlify-cms: Limit global styles to preview pane only via PR #32106
  • gatsby: Add activity for writing out page-data.json files via PR #31987
  • gatsby: Fixed a bug in develop when a new page is not available with HMR via PR #32189
  • gatsby: Fixed a bug with filtering by custom interface fields (affecting WordPress plugin) via PR #32195
  • gatsby: Performance improvements to queries with limit/skip via PR #32135

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#3.8.0

June 22 2021

Welcome to gatsby@3.8.0 release (June 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.

Previous release notes

Full changelog

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

Read more

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 #31963
  • gatsby: Removed outdated ESLint rules jsx-a11y/no-onchange and jsx-a11y/accessible-emoji via PR #31896

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#3.7.0

June 08 2021

Welcome to gatsby@3.7.0 release (June 2021 #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.

Previous release notes

Full changelog

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.

New API for source plugins: createNodeManifest

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.

Original PR.

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.

Original PR

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.

Original PR

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.

Original PR

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: Fixed Maximum call stack size exceeded error, via PR #31547
  • gatsby-source-contentful: Fix blinking progress bar, via PR #31467
  • gatsby-source-wordpress: Prevent "EADDRINUSE: address already in use 127.0.0.1" error, via PR #31710
  • gatsby-remark-katext: Fix compatibility with remark 13, via PR #31596

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#3.6.0

May 25 2021

Welcome to gatsby@3.6.0 release (May 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.

Previous release notes

Full changelog

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.

Showing the different states that the Preview Indicator can take. It's a rectangular container with three vertically stacked icons. The first icon is the Gatsby logo, the second icon indicates a link, and the third icon is an information icon. The Gatsby logo can indicate that the preview information is getting fetched, that a new preview is available, and that the preview has an error. In this case you can view logs. The link icon lets you copy the current URL path to share. The information icon tells you when the preview was last updated.

Notable bugfixes & improvements

  • gatsby-source-wordpress: Add searchAndReplace 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 remove reporter.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" on CONSTRAINED 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 ๐Ÿ’œ

#3.5.0

May 11 2021

Welcome to gatsby@3.5.0 release (May 2021 #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.

Previous release notes

Full changelog

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 the createPages 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 the id 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:

A modal showing that the page failed to SSR and showing a code block with the exact location of the error. Optionally you can reload the page or skip SSR rendering for now.

Documentation Updates

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 #31288
  • gatsby-plugin-preact: enable error-overlay PR #30613
  • gatsby-plugin-sitemap: allow writing sitemap to the root of the public folder PR #31130
  • gatsby-transformer-remark: restore support for footnotes PR #31019
  • Add ImageDataLike as an exported type of gatsby-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 ๐Ÿ’œ

#3.4.0

April 27 2021

Welcome to gatsby@3.4.0 release (April 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.

Previous release notes

Full changelog

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,
  },
}

Details and discussion.

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 when FAST_DEV is enabled PR #30992
  • Speed up createPages by ~10% by memoizing process.env access PR #30768
  • You now can define the --host option of gatsby-cli with env.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 ๐Ÿ’œ

#3.3.0

April 13 2021

Welcome to gatsby@3.3.0 release (April 2021 #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.

Previous release notes

Full changelog

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.

Original PR

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).

Original PR

Upgrade to the latest remark

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.

Upgrade to the latest sharp

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)

Original PR

Bugfixes in gatsby-plugin-image@1.3.0

  • 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 the GatsbyImage 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

  • 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
    • 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

  • cametumbling

    • chore(docs): Add link to part 8 tutorial PR #30604
    • chore(docs): Update wording of tutorial part 8 PR #30606

  • 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

#3.2.0

March 30 2021

Welcome to gatsby@3.2.0 release (March 2021 #3)

Key highlights of this release:

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.

Previous release notes

Full changelog

Better StaticImage errors

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.

CLI showing an error with a description, a codeframe with the relevant code, and link to 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 use gatsby-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

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

Umbrella discussion

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
    • chore(dosc): Update deploying-to-digitalocean-droplet PR #30205
    • chore(docs): Update deploying-to-digitalocean-droplet PR #30266
  • 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
#3.1.0

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.

Previous release notes

Full changelog

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!

Showing a toggle between light and dark mode

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() {}

Browser console showing the actual error

In development mode we also now show the original error when it occurs in gatsby-browser.js or outside of React components.

Fast Refresh overlay showing an error that happened outside of React

Contentful gatsbyImageData is stable

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

#3.0.0

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:

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

Full changelog

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):

Side-by-side view of a Shopify store instance on the left, and the preview on the right. At the bottom the terminal shows that after the change only one page was rebuilt

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 / SSR gatsby-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:

Three error overlays from left to right: Compile error, GraphQL errors, and runtime errors

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:

GraphQL deprecation warning in CLI

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:

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 in gatsby-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 ๐Ÿ’œ

#2.32.0

February 02 2021

Welcome to gatsby@2.32.0 release (February 2021 #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.

Previous release notes

Full changelog

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 ๐Ÿ’œ

#2.31.0

January 19 2021

Welcome to gatsby@2.31.0 release (January 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.

Previous release notes

Full changelog

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:

Screenshot showing the GraphiQL IDE with the fragments in auto-completion

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!

Important gatsby-plugin-image updates

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.

  1. 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.
  2. fluid layout renamed to fullWidth: We're renaming the fluid layout to fullWidth, to better reflect what it's used for. It was called fluid before to match the equivalent layout in the old gatsby-image component. However this was confusing, because for many of the cases where people used fluid before they should be using the new constrained layout. This displays the image at the specified width, but allows it to shrink to fit smaller screens. However fullWidth 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.
  3. Don't use maxWidth for fullWidth images: The old fluid resolver allows you to pass a maxWidth 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 the 1x 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 with maxHeight (also doesn't do what you'd expect). Its replacement is:
  4. Use breakpoints for fullWidth images: Previously fluid layout generated image resolutions that were based on multiples and fractions of the maxWidth, similar to how they are done for fixed and constrained. This makes sense where they are mostly going to be used for higher-pixel density screens, rather than for displaying the image larger. However for a full width image, the size you want is the width of the screen. We can't generate images for every size, but we can choose a good selection of sizes to cover everything from phones to large monitors. We have chosen a default set based on our usage research, but you can pass your own breakpoints in if you'd prefer.
  5. Change maxWidth/maxHeight to width/height There was no good reason to have constrained take maxWidth/maxHeight, while fixed took width/height. We've changed it so they both take width/height.
  6. 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 for fluid images. We've added a new aspectRatio 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.
  7. 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.
  8. Automatic object-fit polyfill: This version includes an automatic polyfill for browsers that don't support the CSS object-fit and object-position properties. It is lazy-loaded so has no overhead for browsers that don't need it.
  9. 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:
    1. A step-by-step how-to guide
    2. A detailed reference guide

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 (with DEV_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 ๐Ÿ’œ

#2.30.0

January 05 2021

Welcome to gatsby@2.30.0 release (January 2021 #1)

Key highlights of this release:

And several impactful updates in the new gatsby-plugin-image (beta):

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.

Previous release notes

Full changelog

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, only gatsby 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 and childrenField 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 #27974
  • gatsby-source-graphql: add HTTP error reporting, via #28786
  • gatsby-source-filesystem: retry a download in createRemoteFileNode if a file is incomplete, via #28547
  • gatsby-plugin-schema-snapshot: fix warning The type Foo does not explicitly define the field childBar, via #28483
  • gatsby-source-contentful: dont re-create nodes unnecessarily, via #28642

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#2.29.0

December 15 2020

Welcome to gatsby@2.29.0 release (December 2020 #2)

Key highlights of this release:

Other notable changes:

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

Full changelog

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.

Short gif demonstrating the loading indicator for Query on Demand -- this is shown when the requested page takes a bit longer

Browser console

Picture showing a note in the browser console that explains on how to disable it

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 and package.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

gatsby-source-contentful

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 ๐Ÿ’œ

#2.28.0

December 01 2020

Welcome to gatsby@2.28.0 release (December 2020 #1).

Key highlights of this release:

Other notable changes:

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.

Previous release notes

Full changelog

New gatsby 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.

Feature flags in gatsby-config.js

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 (requires gatsby-plugin-sharp@^2.10.0). See Experimental: Lazy images in develop section for additional details.
  • FAST_DEV - Umbrella flag that enables DEV_SSR, QUERY_ON_DEMAND and LAZY_IMAGES features.
  • FAST_REFRESH - Use React Fast Refresh instead of the legacy react-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.

Making gatsby develop faster

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,
  },
}

Details and discussion.

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 in gatsby-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 ๐Ÿ’œ

#2.27.0

November 19 2020

Welcome to gatsby@2.27.0 release (November 2020 #2).

Key highlights of this release:

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.

Previous release notes

Full changelog

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.

Making gatsby develop faster

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)

Details and discussion.

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

  • fix: endless page refresh in develop #28034
  • fix: performance regression when running queries #28032

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.

Details and discussion.

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.

Announcement and discussion.

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ

#2.26.0

November 12 2020

Welcome to gatsby@2.26.0 release (November 2020). Key highlights of this release:

Other notable changes:

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.

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,
}

Details and discussion.

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.

Details and discussion.

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.

Announcement and discussion.

Contributors

A big Thank You to our community who contributed to this release ๐Ÿ’œ