From ddd19d611d9d6ea8357ce2409f5be52588855a2e Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Fri, 1 Jun 2018 15:37:29 +0100 Subject: [PATCH 01/26] Remove yarn examples for consistency with other docs --- docs/docs/migrating-from-v1-to-v2.md | 12 ------------ 1 file changed, 12 deletions(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index d5ac0c905b461..438fb864f752a 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -9,24 +9,12 @@ In v1, React and ReactDOM were magically resolved. This “feature” has been r npm i react react-dom ``` -or - -```bash -yarn add react react-dom -``` - Depending on the plugins you use, there may be more dependencies you need to install. For example: if you use typography.js, you now also need to install its dependencies. ```bash npm i typography react-typography ``` -or - -```bash -yarn add typography react-typography -``` - Search for the plugins that you use in [Gatsby’s plugins page](/plugins) and check their installation instructions. ## Layout component From 8718398a713e555f1d128067e564b3372fe1a055 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Fri, 1 Jun 2018 15:38:13 +0100 Subject: [PATCH 02/26] Add rename responsive image queries section --- docs/docs/migrating-from-v1-to-v2.md | 70 ++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 438fb864f752a..97aae37fe011d 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -168,6 +168,76 @@ export default props => ( ## Rename `pathContext` to `pageContext` Similar to `boundActionCreators` above, `pathContext` is deprecated in favor of `pageContext`. +## Rename responsive image queries + +The `sizes` and `resolutions` queries are deprecated in v2. These queries have been renamed to `fluid` and `fixed` to make them easier to understand. + +Before: + +```jsx +const Example = ({ data }) => { +
+ + +
+} + +export default Example + +export const pageQuery = graphql` + query IndexQuery { + foo: file(relativePath: { regex: "/foo.jpg/" }) { + childImageSharp { + sizes(maxWidth: 700) { + ...GatsbyImageSharpSizes_tracedSVG + } + } + } + bar: file(relativePath: { regex: "/bar.jpg/" }) { + childImageSharp { + resolutions(width: 500) { + ...GatsbyImageSharpResolutions_withWebp + } + } + } + } +` +``` + +After: + +```jsx{2-3,13-14,20-21} +const Example = ({ data }) => { +
+ + +
+} + +export default Example + +export const pageQuery = graphql` + query IndexQuery { + foo: file(relativePath: { regex: "/foo.jpg/" }) { + childImageSharp { + fluid(maxWidth: 700) { + ...GatsbyImageSharpFluid_tracedSVG + } + } + } + bar: file(relativePath: { regex: "/bar.jpg/" }) { + childImageSharp { + fixed(width: 500) { + ...GatsbyImageSharpFixed_withWebp + } + } + } + } +` +``` + +Further examples can be found in the [Gatsby Image docs](https://github.com/gatsbyjs/gatsby/tree/d0e29272ed7b009dae18d35d41a45e700cdcab0d/packages/gatsby-image). + From 00d68eebf0462cba47cd08eefaf684c163af276a Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Fri, 1 Jun 2018 16:38:24 +0100 Subject: [PATCH 05/26] Add mixed CommonJS/ES6 section --- docs/docs/migrating-from-v1-to-v2.md | 32 ++++++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 4bd468c8611ff..02906c3a4d2c8 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -245,3 +245,35 @@ Gatsby v2 removed `postcss-cssnext` and `postcss-import` from the default postcs Use `modifyWebpackConfig` to specify your postcss plugins. Note: there will be a `postcss` plugin that allows you to configure postcss from a standard postcss config file. [Follow this discussion on issue 3284](https://github.com/gatsbyjs/gatsby/issues/3284). + +## Files mixing CommonJS with ES6 modules won't compile + +Gatsby v2 uses a version 7 of [babel](https://babeljs.io/) which is stricter about parsing files with mixed JS styles. + +> TODO: link to babel docs here? + +ES6 Modules are ok: + +```js +import foo from "foo" +export default foo +``` + +CommonJS is ok: + +```js +const foo = require('foo'); +module.exports = foo; +``` + +Mixing `requires` and `export` is not ok: +```js +const foo = require('foo'); +export default foo +``` + +Mixing `import` and `module.exports` is not ok: +```js +import foo from "foo" +module.exports = foo; +``` From 805383568accbb877cfb111074d046d8466fedd3 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Fri, 1 Jun 2018 16:44:08 +0100 Subject: [PATCH 06/26] Link to Gatsby webpack docs --- docs/docs/migrating-from-v1-to-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 02906c3a4d2c8..7cbbda804b85d 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -242,7 +242,7 @@ Further examples can be found in the [Gatsby Image docs](https://github.com/gats Gatsby v2 removed `postcss-cssnext` and `postcss-import` from the default postcss setup. -Use `modifyWebpackConfig` to specify your postcss plugins. +Use [`onCreateWebpackConfig`](/docs/add-custom-webpack-config) to specify your postcss plugins. Note: there will be a `postcss` plugin that allows you to configure postcss from a standard postcss config file. [Follow this discussion on issue 3284](https://github.com/gatsbyjs/gatsby/issues/3284). From bb64597ea9251143657678472f0d7225de9c3282 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Fri, 1 Jun 2018 16:54:43 +0100 Subject: [PATCH 07/26] Add node id section --- docs/docs/migrating-from-v1-to-v2.md | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 7cbbda804b85d..f4201e83886e0 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -277,3 +277,12 @@ Mixing `import` and `module.exports` is not ok: import foo from "foo" module.exports = foo; ``` + +## Don't query nodes by ID + +Source and transformer plugins now use UUIDs for IDs. If you used glob or regex to query nodes by id then you'll need to query something else. + +[See the Pull Request that implemented this change](https://github.com/gatsbyjs/gatsby/pull/3807/files) + +> TODO: add example + From 7afa9d9556224e017782b8140921f9030518af0f Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Fri, 1 Jun 2018 17:26:08 +0100 Subject: [PATCH 08/26] Add section: remove explicit polyfills --- docs/docs/migrating-from-v1-to-v2.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index f4201e83886e0..753296ea1e6f4 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -248,9 +248,7 @@ Note: there will be a `postcss` plugin that allows you to configure postcss from ## Files mixing CommonJS with ES6 modules won't compile -Gatsby v2 uses a version 7 of [babel](https://babeljs.io/) which is stricter about parsing files with mixed JS styles. - -> TODO: link to babel docs here? +Gatsby v2 uses babel 7 which is stricter about parsing files with mixed JS styles. ES6 Modules are ok: @@ -278,6 +276,8 @@ import foo from "foo" module.exports = foo; ``` +See [Gatsby's babel docs for more details](/docs/babel). + ## Don't query nodes by ID Source and transformer plugins now use UUIDs for IDs. If you used glob or regex to query nodes by id then you'll need to query something else. @@ -286,3 +286,6 @@ Source and transformer plugins now use UUIDs for IDs. If you used glob or regex > TODO: add example +## Remove explicit polyfills + +If your Gatsby v1 site included any polyfills, you can remove them. Gatsby v2 ships with babel 7 and is configured to automatically include polyfills for your code. See [Gatsby's babel docs for more details](/docs/babel). From f616086c22b815c3262cf475d4781adcd009fa59 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Fri, 1 Jun 2018 17:26:29 +0100 Subject: [PATCH 09/26] Add section: Change modifyBabelrc to onCreateBabelConfig --- docs/docs/migrating-from-v1-to-v2.md | 30 ++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 753296ea1e6f4..ee03050e7ce8b 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -289,3 +289,33 @@ Source and transformer plugins now use UUIDs for IDs. If you used glob or regex ## Remove explicit polyfills If your Gatsby v1 site included any polyfills, you can remove them. Gatsby v2 ships with babel 7 and is configured to automatically include polyfills for your code. See [Gatsby's babel docs for more details](/docs/babel). + +## Change `modifyBabelrc` to `onCreateBabelConfig` + +`modifyBabelrc` was renamed to [`onCreateBabelConfig`](/docs/node-apis/#modifyBabelrc) to bring it in line with the rest of Gatsby's API names. + +Before: + +```js +exports.modifyBabelrc = ({ babelrc }) => { + return { + ...babelrc, + plugins: babelrc.plugins.concat([`foo`]), + } +} +``` + +After: + +```js +exports.onCreateBabelConfig = ({ actions }) => { + actions.setBabelPlugin({ + name: `babel-plugin-foo`, + }) +} +``` + +Note usage of the new [`setBabelPlugin` action](/docs/actions/#setBabelPlugins). + +See [Gatsby's babel docs for more details](/docs/babel) about configuring babel. + From 163d7ea137859a7af617fdd87de8985d65a203db Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Fri, 1 Jun 2018 22:24:10 +0100 Subject: [PATCH 10/26] Add section: Change `modifyWebpackConfig` to `onCreateWebpackConfig` --- docs/docs/migrating-from-v1-to-v2.md | 34 ++++++++++++++++++++++++++++ 1 file changed, 34 insertions(+) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index ee03050e7ce8b..8bde988cbb815 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -319,3 +319,37 @@ Note usage of the new [`setBabelPlugin` action](/docs/actions/#setBabelPlugins). See [Gatsby's babel docs for more details](/docs/babel) about configuring babel. +## Change `modifyWebpackConfig` to `onCreateWebpackConfig` + +`modifyWebpackConfig` was renamed to [`onCreateWebpackConfig`](/docs/node-apis/#onCreateWebpackConfig) to bring it in line with the rest of Gatsby's API names. + +Before: + +```js +exports.modifyWebpackConfig = ({ config, stage }) => { + switch (stage) { + case `build-javascript`: + config.plugin(`Foo`, webpackFooPlugin, null) + break + } + return config +} +``` + + +After: + +```js +exports.onCreateWebpackConfig = ({ stage, actions }) => { + switch (stage) { + case `build-javascript`: + actions.setWebpackConfig({ + plugins: [webpackFooPlugin], + }) + } +} +``` + +Note usage of the new [`setWebpackConfig` action](/docs/actions/#setWebpackConfig). + +See [Gatsby's webpack docs for more details](/docs/add-custom-webpack-config) about configuring webpack. From e54d5f9ceb295132330703d28b1c4ea77c870933 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Fri, 1 Jun 2018 22:24:32 +0100 Subject: [PATCH 11/26] Add section: CSS is inlined automatically --- docs/docs/migrating-from-v1-to-v2.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 8bde988cbb815..2514b010e7634 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -353,3 +353,9 @@ exports.onCreateWebpackConfig = ({ stage, actions }) => { Note usage of the new [`setWebpackConfig` action](/docs/actions/#setWebpackConfig). See [Gatsby's webpack docs for more details](/docs/add-custom-webpack-config) about configuring webpack. + +## CSS is inlined automatically + +Gatsby v2 automatically inlines CSS. Gatsby v1 required you to create a [custom `html.js` file](/docs/custom-html) to do this. You can remove any custom CSS inlining from your custom `html.js`, in many cases this allows you to completely remove your `html.js` file. + +See an example in [this PR that upgrades the `using-remark` site to Gatsby v2](https://github.com/gatsbyjs/gatsby/commit/765b679cbc222fd5f527690427ee431cca7ccd61#diff-637c76e3c059ed8efacedf6e30de2d61). From 5413b7340c30749f6b91da7b1092f2837fc22f3d Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Fri, 1 Jun 2018 22:25:07 +0100 Subject: [PATCH 12/26] Add introduction and small tweaks --- docs/docs/migrating-from-v1-to-v2.md | 30 +++++++++++++++++++++++----- 1 file changed, 25 insertions(+), 5 deletions(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 2514b010e7634..6aafd832cc7e0 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -2,7 +2,16 @@ title: Migrating from v1 to v2 --- +> This document is a work in progress. Have you upgraded your site and run into something that's not covered here? Add your changes on GitHub! + +## Introduction + +This is a reference for upgrading your site from Gatsby v1 to Gatsby v2. While there's a lot covered here, you probably won't need to do everything for your site. + +Let's start with the most important two steps - install React and update your layout components: + ## Install React, ReactDOM, and each plugins’ peer dependencies manually + In v1, React and ReactDOM were magically resolved. This “feature” has been removed and you are now required to install them manually. ```bash @@ -18,6 +27,7 @@ npm i typography react-typography Search for the plugins that you use in [Gatsby’s plugins page](/plugins) and check their installation instructions. ## Layout component + The special layout component (`src/layouts/index.js`) that Gatsby v1 used to wrap every page has been removed. If the layout of your site appears to be broken, this is most likely the reason why. To learn more about the considerations behind this removal, read the [Gatsby RFC](https://github.com/gatsbyjs/rfcs/blob/master/text/0002-remove-special-layout-components.md). @@ -25,9 +35,10 @@ To learn more about the considerations behind this removal, read the [Gatsby RFC The following is the recommended migration path: ### 1. Convert children from function to normal prop (required) + In v1, the `children` prop passed to layout was a function and needed to be executed. In v2, this is no longer the case. -`layout in v1` +Before: ```jsx import React from "react" @@ -39,7 +50,7 @@ export default ({ children }) => ( ) ``` -`layout in v2` +After: ```jsx{5} import React from "react" @@ -52,11 +63,13 @@ export default ({ children }) => ( ``` ### 2. Move `layout/index.js` to `src/components/layout.js` (optional, but recommended) + ```bash git mv src/layouts/index.js src/components/layout.js ``` ### 3. Import and wrap pages with layout component + Adhering to normal React composition model, you import the layout component and use it to wrap the content of the page. `src/pages/index.js` @@ -75,10 +88,12 @@ export default () => ( Repeat for every page and template that needs this layout. ### 4. Change query to use `StaticQuery` - + Since layout is no longer special, you now need to make use of v2’s StaticQuery feature. -`Query with layout in v1` +> TODO: document StaticQuery and link to it from here + +Before: ```jsx import React, { Fragment } from "react" @@ -104,7 +119,7 @@ export const query = graphql` ` ``` -`StaticQuery with layout in v2` +After: ```jsx import React, { Fragment } from "react" @@ -134,6 +149,7 @@ export default ({ children }) => ( ``` ### 5. Pass `history`, `location`, and `match` props to layout + In v1, layout component had access to `history`, `location`, and `match` props. In v2, only pages have access to these props; pass them to your layout component as needed. `layout` @@ -163,9 +179,13 @@ export default props => ( ``` ## Rename `boundActionCreators` to `actions` + `boundActionCreators` is deprecated in v2. You can continue using it, but it’s recommended that you rename it to `actions`. +> TODO: document new actions - see [actions](/docs/actions) + ## Rename `pathContext` to `pageContext` + Similar to `boundActionCreators` above, `pathContext` is deprecated in favor of `pageContext`. ## Rename responsive image queries From d10adad95e76da692acd81033e98962cbed51fea Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Fri, 1 Jun 2018 22:58:39 +0100 Subject: [PATCH 13/26] Correct line numbers --- docs/docs/migrating-from-v1-to-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 6aafd832cc7e0..bc03707620720 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -226,7 +226,7 @@ export const pageQuery = graphql` After: -```jsx{2-3,13-14,20-21} +```jsx{3-4,14-15,21-22} const Example = ({ data }) => {
From ca6d375b3557474dc0940bd14a1e791859b8d82f Mon Sep 17 00:00:00 2001 From: Kyle Mathews Date: Fri, 1 Jun 2018 16:25:04 -0700 Subject: [PATCH 14/26] Improve explanation around movement of libs to peerDependencies --- docs/docs/migrating-from-v1-to-v2.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index bc03707620720..08e6772ebaf9a 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -12,25 +12,25 @@ Let's start with the most important two steps - install React and update your la ## Install React, ReactDOM, and each plugins’ peer dependencies manually -In v1, React and ReactDOM were magically resolved. This “feature” has been removed and you are now required to install them manually. +In v1, The `react` and `react-dom` packages were included as part of the `gatsby` package. They are now `peerDependencies` so you are required to install them into your project. ```bash npm i react react-dom ``` -Depending on the plugins you use, there may be more dependencies you need to install. For example: if you use typography.js, you now also need to install its dependencies. +Some plugins had dependencies that were also made peerDependencies. For example, if you use gatsby-plugin-typography, you now need to install: ```bash npm i typography react-typography ``` -Search for the plugins that you use in [Gatsby’s plugins page](/plugins) and check their installation instructions. +Search for the plugins that you use in the [plugin library](/plugins) and check their installation instructions for additional packages that now need installed. ## Layout component The special layout component (`src/layouts/index.js`) that Gatsby v1 used to wrap every page has been removed. If the layout of your site appears to be broken, this is most likely the reason why. -To learn more about the considerations behind this removal, read the [Gatsby RFC](https://github.com/gatsbyjs/rfcs/blob/master/text/0002-remove-special-layout-components.md). +To learn more about the considerations behind this removal, read the [RFC for removing the special layout component](https://github.com/gatsbyjs/rfcs/blob/master/text/0002-remove-special-layout-components.md). The following is the recommended migration path: From 433833a8e866c686c04b156c3bca17dc8ad3060c Mon Sep 17 00:00:00 2001 From: Jason Lengstorf Date: Fri, 1 Jun 2018 16:32:05 -0700 Subject: [PATCH 15/26] chore: minor capitalization tweak --- docs/docs/migrating-from-v1-to-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 08e6772ebaf9a..584b7c1d35030 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -12,7 +12,7 @@ Let's start with the most important two steps - install React and update your la ## Install React, ReactDOM, and each plugins’ peer dependencies manually -In v1, The `react` and `react-dom` packages were included as part of the `gatsby` package. They are now `peerDependencies` so you are required to install them into your project. +In v1, the `react` and `react-dom` packages were included as part of the `gatsby` package. They are now `peerDependencies` so you are required to install them into your project. ```bash npm i react react-dom From 05b1e85802fdcdcee686f7d4dd5124dc0a0c39e5 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Mon, 4 Jun 2018 16:19:56 +0100 Subject: [PATCH 16/26] Add edit link --- docs/docs/migrating-from-v1-to-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index bc03707620720..f52faef5c83bb 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -2,7 +2,7 @@ title: Migrating from v1 to v2 --- -> This document is a work in progress. Have you upgraded your site and run into something that's not covered here? Add your changes on GitHub! +> This document is a work in progress. Have you upgraded your site and run into something that's not covered here? [Add your changes on GitHub](https://github.com/gatsbyjs/gatsby/blob/v2/docs/docs/migrating-from-v1-to-v2.md)! ## Introduction From d0cebc7306657afd2e2c30528c72743b08dc3c68 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Mon, 4 Jun 2018 16:21:05 +0100 Subject: [PATCH 17/26] Split peer dep updates into two sections --- docs/docs/migrating-from-v1-to-v2.md | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index f52faef5c83bb..dae49b04cd17e 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -8,17 +8,19 @@ title: Migrating from v1 to v2 This is a reference for upgrading your site from Gatsby v1 to Gatsby v2. While there's a lot covered here, you probably won't need to do everything for your site. -Let's start with the most important two steps - install React and update your layout components: +Let's start with a few of the most important steps - install peer dependencies and update your layout components. -## Install React, ReactDOM, and each plugins’ peer dependencies manually +## Manually install React -In v1, React and ReactDOM were magically resolved. This “feature” has been removed and you are now required to install them manually. +In v1, React and ReactDOM were magically resolved. This “feature” has been removed and you are now required to install them manually: ```bash npm i react react-dom ``` -Depending on the plugins you use, there may be more dependencies you need to install. For example: if you use typography.js, you now also need to install its dependencies. +## Manually install plugins’ peer dependencies + +Depending on the plugins you use, there may be more dependencies you need to install. For example: if you use [`gatsby-plugin-typography`](https://www.gatsbyjs.org/packages/gatsby-plugin-typography/), you now also need to install its dependencies: ```bash npm i typography react-typography From 9124ad10ed1e3289dea2b76dde594c1ccb39ef8c Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Mon, 4 Jun 2018 16:21:17 +0100 Subject: [PATCH 18/26] Declarative headings --- docs/docs/migrating-from-v1-to-v2.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index dae49b04cd17e..9363427ed635f 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -268,7 +268,7 @@ Use [`onCreateWebpackConfig`](/docs/add-custom-webpack-config) to specify your p Note: there will be a `postcss` plugin that allows you to configure postcss from a standard postcss config file. [Follow this discussion on issue 3284](https://github.com/gatsbyjs/gatsby/issues/3284). -## Files mixing CommonJS with ES6 modules won't compile +## Convert to either pure CommonJS or pure ES6 Gatsby v2 uses babel 7 which is stricter about parsing files with mixed JS styles. @@ -376,7 +376,7 @@ Note usage of the new [`setWebpackConfig` action](/docs/actions/#setWebpackConfi See [Gatsby's webpack docs for more details](/docs/add-custom-webpack-config) about configuring webpack. -## CSS is inlined automatically +## Remove inlined CSS in `html.js` Gatsby v2 automatically inlines CSS. Gatsby v1 required you to create a [custom `html.js` file](/docs/custom-html) to do this. You can remove any custom CSS inlining from your custom `html.js`, in many cases this allows you to completely remove your `html.js` file. From c5e1c15d7d3be0e6345439f37e650e7f8cec4cbd Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Mon, 4 Jun 2018 16:36:39 +0100 Subject: [PATCH 19/26] Add table of contents --- docs/docs/migrating-from-v1-to-v2.md | 23 ++++++++++++++++++++--- 1 file changed, 20 insertions(+), 3 deletions(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 9363427ed635f..c7401829252cf 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -8,7 +8,24 @@ title: Migrating from v1 to v2 This is a reference for upgrading your site from Gatsby v1 to Gatsby v2. While there's a lot covered here, you probably won't need to do everything for your site. -Let's start with a few of the most important steps - install peer dependencies and update your layout components. +## What we'll cover + +* [Manually install React](/docs/migrating-from-v1-to-v2/#manually-install-react) +* [Manually install plugins’ peer dependencies](/docs/migrating-from-v1-to-v2/manually-install-plugins-peer-dependencies) +* [Update layout component](/docs/migrating-from-v1-to-v2/#update-layout-component) +* [Rename `boundActionCreators` to `actions`](/docs/migrating-from-v1-to-v2/rename-boundactioncreators-to-actions) +* [Rename `pathContext` to `pageContext`](/docs/migrating-from-v1-to-v2/#rename-pathcontext-to-pagecontext) +* [Rename responsive image queries](/docs/migrating-from-v1-to-v2/#rename-responsive-image-queries) +* [Manually specify PostCSS plugins](/docs/migrating-from-v1-to-v2/#manually-specify-postcss-plugins) +* [Convert to either pure CommonJS or pure ES6](/docs/migrating-from-v1-to-v2/#convert-to-either-pure-commonjs-or-pure-es6) +* [Don't query nodes by ID](/docs/migrating-from-v1-to-v2/#dont-query-nodes-by-id) +* [Remove explicit polyfills](/docs/migrating-from-v1-to-v2/#remove-explicit-polyfills) +* [Change `modifyBabelrc` to `onCreateBabelConfig`](/docs/migrating-from-v1-to-v2/#change-modifybabelrc-to-oncreatebabelconfig) +* [Change `modifyWebpackConfig` to `onCreateWebpackConfig`](/docs/migrating-from-v1-to-v2/#change-modifywebpackconfig-to-oncreatewebpackconfig) +* [Remove inlined CSS in `html.js`](/docs/migrating-from-v1-to-v2/#remove-inlined-css-in-htmljs) + + +You can start with a few of the most important steps - install peer dependencies and update your layout components. ## Manually install React @@ -28,7 +45,7 @@ npm i typography react-typography Search for the plugins that you use in [Gatsby’s plugins page](/plugins) and check their installation instructions. -## Layout component +## Update layout component The special layout component (`src/layouts/index.js`) that Gatsby v1 used to wrap every page has been removed. If the layout of your site appears to be broken, this is most likely the reason why. @@ -260,7 +277,7 @@ export const pageQuery = graphql` Further examples can be found in the [Gatsby Image docs](https://github.com/gatsbyjs/gatsby/tree/d0e29272ed7b009dae18d35d41a45e700cdcab0d/packages/gatsby-image). -## Manually specify postcss plugins +## Manually specify PostCSS plugins Gatsby v2 removed `postcss-cssnext` and `postcss-import` from the default postcss setup. From 2be2dca6e6bdb2bcd69347c3ed32d097fc255e28 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Mon, 4 Jun 2018 16:46:58 +0100 Subject: [PATCH 20/26] Use neater Fragment syntax --- docs/docs/migrating-from-v1-to-v2.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index c7401829252cf..01a47d656a059 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -119,12 +119,12 @@ import React, { Fragment } from "react" import Helmet from "react-helmet" export default ({ children, data }) => ( - + <>
{children()}
- + ) export const query = graphql` @@ -156,12 +156,12 @@ export default ({ children }) => ( } `} render={data => ( - + <>
{children}
- + )} /> ) From b8c48606a2b15b9656e30a7ef4e52e98613c7883 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Mon, 4 Jun 2018 16:47:23 +0100 Subject: [PATCH 21/26] More detail on deprecation note --- docs/docs/migrating-from-v1-to-v2.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 01a47d656a059..632aaa0a56faf 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -209,7 +209,7 @@ Similar to `boundActionCreators` above, `pathContext` is deprecated in favor of ## Rename responsive image queries -The `sizes` and `resolutions` queries are deprecated in v2. These queries have been renamed to `fluid` and `fixed` to make them easier to understand. +The `sizes` and `resolutions` queries are deprecated in v2. These queries have been renamed to `fluid` and `fixed` to make them easier to understand. You can continue using the deprecated query names, but it's recommended that you update them. Before: From 405073e5ff0b8da5cc02e16697e2d93da44e0342 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Mon, 4 Jun 2018 16:47:44 +0100 Subject: [PATCH 22/26] Inline comments on code examples --- docs/docs/migrating-from-v1-to-v2.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 632aaa0a56faf..ae5d7be2874da 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -292,6 +292,7 @@ Gatsby v2 uses babel 7 which is stricter about parsing files with mixed JS style ES6 Modules are ok: ```js +// GOOD: ES modules syntax works import foo from "foo" export default foo ``` @@ -299,18 +300,21 @@ export default foo CommonJS is ok: ```js +// GOOD: CommonJS syntax works const foo = require('foo'); module.exports = foo; ``` Mixing `requires` and `export` is not ok: ```js +// BAD: Mixed ES and CommonJS module syntax will cause failures const foo = require('foo'); export default foo ``` Mixing `import` and `module.exports` is not ok: ```js +// BAD: Mixed ES and CommonJS module syntax will cause failures import foo from "foo" module.exports = foo; ``` From bfc9301e68b2a354780061b12e734524c16c6d69 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Mon, 4 Jun 2018 16:48:06 +0100 Subject: [PATCH 23/26] Add Jason's node ID query example --- docs/docs/migrating-from-v1-to-v2.md | 22 ++++++++++++++++++++-- 1 file changed, 20 insertions(+), 2 deletions(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index ae5d7be2874da..64d475e441546 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -325,9 +325,27 @@ See [Gatsby's babel docs for more details](/docs/babel). Source and transformer plugins now use UUIDs for IDs. If you used glob or regex to query nodes by id then you'll need to query something else. -[See the Pull Request that implemented this change](https://github.com/gatsbyjs/gatsby/pull/3807/files) +Here's an example querying an image: + +```diff + query MyImageQuery { + allImageSharp(filter: { +- id: {regex: "/default.jpg/"} ++ sizes: {originalName: {regex: "/default.jpg/"}} + }) { + edges { + node { + id + sizes(maxWidth: 660) { + src + } + } + } + } + } +``` -> TODO: add example +[See the Pull Request that implemented this change](https://github.com/gatsbyjs/gatsby/pull/3807/files) ## Remove explicit polyfills From d5beb1beb338cf8082fe39b45a067474368d80b3 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Mon, 4 Jun 2018 17:08:19 +0100 Subject: [PATCH 24/26] Use markdown diff syntax for before / after examples --- docs/docs/migrating-from-v1-to-v2.md | 222 ++++++++++----------------- 1 file changed, 81 insertions(+), 141 deletions(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index a4d74210c006e..fe8a1e3666467 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -57,26 +57,14 @@ The following is the recommended migration path: In v1, the `children` prop passed to layout was a function and needed to be executed. In v2, this is no longer the case. -Before: -```jsx -import React from "react" - -export default ({ children }) => ( -
- {children()} -
-) -``` - -After: - -```jsx{5} +```diff import React from "react" export default ({ children }) => (
- {children} +- {children()} ++ {children}
) ``` @@ -112,59 +100,51 @@ Since layout is no longer special, you now need to make use of v2’s StaticQuer > TODO: document StaticQuery and link to it from here -Before: +Replacing a layout's query with `StaticQuery`: -```jsx +```diff import React, { Fragment } from "react" import Helmet from "react-helmet" -export default ({ children, data }) => ( - <> - -
- {children()} -
- -) - -export const query = graphql` - query LayoutQuery { - site { - siteMetadata { - title - } - } - } -` -``` - -After: - -```jsx -import React, { Fragment } from "react" -import { StaticQuery } from "gatsby" - -export default ({ children }) => ( - ( - <> - -
- {children} -
- - )} - /> -) +- export default ({ children, data }) => ( +- <> +- +-
+- {children()} +-
+- +- ) +- +- export const query = graphql` +- query LayoutQuery { +- site { +- siteMetadata { +- title +- } +- } +- } +- ` ++ export default ({ children }) => ( ++ ( ++ <> ++ ++
++ {children} ++
++ ++ )} ++ /> ++ ) ``` ### 5. Pass `history`, `location`, and `match` props to layout @@ -211,45 +191,15 @@ Similar to `boundActionCreators` above, `pathContext` is deprecated in favor of The `sizes` and `resolutions` queries are deprecated in v2. These queries have been renamed to `fluid` and `fixed` to make them easier to understand. You can continue using the deprecated query names, but it's recommended that you update them. -Before: - -```jsx -const Example = ({ data }) => { -
- - -
-} - -export default Example +Update image query and fragment names: -export const pageQuery = graphql` - query IndexQuery { - foo: file(relativePath: { regex: "/foo.jpg/" }) { - childImageSharp { - sizes(maxWidth: 700) { - ...GatsbyImageSharpSizes_tracedSVG - } - } - } - bar: file(relativePath: { regex: "/bar.jpg/" }) { - childImageSharp { - resolutions(width: 500) { - ...GatsbyImageSharpResolutions_withWebp - } - } - } - } -` -``` - -After: - -```jsx{3-4,14-15,21-22} +```diff const Example = ({ data }) => {
- - +- +- ++ ++
} @@ -259,15 +209,19 @@ export const pageQuery = graphql` query IndexQuery { foo: file(relativePath: { regex: "/foo.jpg/" }) { childImageSharp { - fluid(maxWidth: 700) { - ...GatsbyImageSharpFluid_tracedSVG +- sizes(maxWidth: 700) { +- ...GatsbyImageSharpSizes_tracedSVG ++ fluid(maxWidth: 700) { ++ ...GatsbyImageSharpFluid_tracedSVG } } } bar: file(relativePath: { regex: "/bar.jpg/" }) { childImageSharp { - fixed(width: 500) { - ...GatsbyImageSharpFixed_withWebp +- resolutions(width: 500) { +- ...GatsbyImageSharpResolutions_withWebp ++ fixed(width: 500) { ++ ...GatsbyImageSharpFixed_withWebp } } } @@ -355,24 +309,18 @@ If your Gatsby v1 site included any polyfills, you can remove them. Gatsby v2 sh `modifyBabelrc` was renamed to [`onCreateBabelConfig`](/docs/node-apis/#modifyBabelrc) to bring it in line with the rest of Gatsby's API names. -Before: +Use `onCreateBabelConfig`: -```js -exports.modifyBabelrc = ({ babelrc }) => { - return { - ...babelrc, - plugins: babelrc.plugins.concat([`foo`]), - } -} -``` - -After: - -```js -exports.onCreateBabelConfig = ({ actions }) => { - actions.setBabelPlugin({ - name: `babel-plugin-foo`, - }) +```diff +- exports.modifyBabelrc = ({ babelrc }) => { +- return { +- ...babelrc, +- plugins: babelrc.plugins.concat([`foo`]), +- } ++ exports.onCreateBabelConfig = ({ actions }) => { ++ actions.setBabelPlugin({ ++ name: `babel-plugin-foo`, ++ }) } ``` @@ -384,33 +332,25 @@ See [Gatsby's babel docs for more details](/docs/babel) about configuring babel. `modifyWebpackConfig` was renamed to [`onCreateWebpackConfig`](/docs/node-apis/#onCreateWebpackConfig) to bring it in line with the rest of Gatsby's API names. -Before: +Use `onCreateWebpackConfig`: -```js -exports.modifyWebpackConfig = ({ config, stage }) => { +```diff +- exports.modifyWebpackConfig = ({ config, stage }) => { ++ exports.onCreateWebpackConfig = ({ stage, actions }) => { switch (stage) { case `build-javascript`: - config.plugin(`Foo`, webpackFooPlugin, null) - break - } - return config +- config.plugin(`Foo`, webpackFooPlugin, null) +- break +- } +- return config ++ actions.setWebpackConfig({ ++ plugins: [webpackFooPlugin], ++ }) ++ } } ``` -After: - -```js -exports.onCreateWebpackConfig = ({ stage, actions }) => { - switch (stage) { - case `build-javascript`: - actions.setWebpackConfig({ - plugins: [webpackFooPlugin], - }) - } -} -``` - Note usage of the new [`setWebpackConfig` action](/docs/actions/#setWebpackConfig). See [Gatsby's webpack docs for more details](/docs/add-custom-webpack-config) about configuring webpack. From ad474639bc154d3ec645dbde4c26b425a21f3e7c Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Mon, 4 Jun 2018 17:12:19 +0100 Subject: [PATCH 25/26] Add 'in-progress' note about babel polyfills --- docs/docs/migrating-from-v1-to-v2.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index fe8a1e3666467..6ad8880118795 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -305,6 +305,8 @@ Here's an example querying an image: If your Gatsby v1 site included any polyfills, you can remove them. Gatsby v2 ships with babel 7 and is configured to automatically include polyfills for your code. See [Gatsby's babel docs for more details](/docs/babel). +> Note: This works for your own code, but is not yet implemented for code imported from `node_modules`. Track progress of this feature at [bullet 5 of this issue](https://github.com/gatsbyjs/gatsby/issues/3870). + ## Change `modifyBabelrc` to `onCreateBabelConfig` `modifyBabelrc` was renamed to [`onCreateBabelConfig`](/docs/node-apis/#modifyBabelrc) to bring it in line with the rest of Gatsby's API names. From ed23990c28b3d2e21fa7bf12518e06270785a747 Mon Sep 17 00:00:00 2001 From: Mike Allanson Date: Mon, 4 Jun 2018 20:47:03 +0100 Subject: [PATCH 26/26] Add instructions on how to install Gatsby v2 --- docs/docs/migrating-from-v1-to-v2.md | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/docs/docs/migrating-from-v1-to-v2.md b/docs/docs/migrating-from-v1-to-v2.md index 6ad8880118795..90ddd489f5415 100644 --- a/docs/docs/migrating-from-v1-to-v2.md +++ b/docs/docs/migrating-from-v1-to-v2.md @@ -10,6 +10,7 @@ This is a reference for upgrading your site from Gatsby v1 to Gatsby v2. While t ## What we'll cover +* [Update Gatsby version](/docs/migrating-from-v1-to-v2/#update-gatsby-version) * [Manually install React](/docs/migrating-from-v1-to-v2/#manually-install-react) * [Manually install plugins’ peer dependencies](/docs/migrating-from-v1-to-v2/manually-install-plugins-peer-dependencies) * [Update layout component](/docs/migrating-from-v1-to-v2/#update-layout-component) @@ -24,7 +25,23 @@ This is a reference for upgrading your site from Gatsby v1 to Gatsby v2. While t * [Change `modifyWebpackConfig` to `onCreateWebpackConfig`](/docs/migrating-from-v1-to-v2/#change-modifywebpackconfig-to-oncreatewebpackconfig) * [Remove inlined CSS in `html.js`](/docs/migrating-from-v1-to-v2/#remove-inlined-css-in-htmljs) -You can start with a few of the most important steps - install peer dependencies and update your layout components. +You can start with a few of the most important steps - install Gatsby v2 dependencies and update your layout components. + +## Update Gatsby version + +Update your `package.json` to use the pre-release versions of Gatsby and any related packages. + +package.json: + +```json +"dependencies": { + "gatsby": "next", + "gatsby-image": "next", + "gatsby-plugin-sharp": "next" +} +``` + +> Note: Gatsby v2 is in pre-release so you may encounter further breaking changes. ## Manually install React