From 4a0da37efca063d17178b5e875faa88ca1924203 Mon Sep 17 00:00:00 2001 From: Lennart Date: Mon, 8 Mar 2021 11:39:14 +0100 Subject: [PATCH 1/2] chore(docs): Add version mismatch info to migration guide --- .../release-notes/migrating-from-v2-to-v3.md | 14 ++++++++++++-- 1 file changed, 12 insertions(+), 2 deletions(-) diff --git a/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md b/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md index 9b4421c4bf1e4..add74055a293d 100644 --- a/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md +++ b/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md @@ -119,6 +119,16 @@ The specific resolutions we recommend at this time are found below: } ``` +### Handling version mismatches + +When upgrading an already existing project (that has an existing `node_modules` folder and `package-lock.json` file) you might run into version mismatches for your packages as npm/yarn don't resolve to the latest/correct version. An example would be a version mismatch of `webpack@4` and `webpack@5` that can throw an error like this: + +```shell +Error: NormalModuleFactory.afterResolve (ReactRefreshPlugin) is no longer a waterfall hook, but a bailing hook instead. +``` + +An effective way to get around this issue is deleting `node_modules` and `package-lock.json` and then running `npm install` again. Alternatively, you can use `npm dedupe`. + ## Handling Breaking Changes This section explains breaking changes that were made for Gatsby v3. Most, if not all, of those changes had a deprecation message in v2. In order to successfully update, you'll need to resolve these changes. @@ -400,7 +410,7 @@ const Layout = ({ children, font }) => ( export default Layout ``` -### Webpack 5 node configuration changed (node.fs, node.path, ...) +### webpack 5 node configuration changed (node.fs, node.path, ...) Some components need you to patch/disable node APIs in the browser, like `path` or `fs`. webpack removed these automatic polyfills. You now have to manually set them in your configurations: @@ -427,7 +437,7 @@ If it's still not resolved, the error message should guide you on what else you #### process is not defined -A common error is `process is not defined`. Webpack 4 polyfilled process automatically in the browser, but with v5 it's not the case anymore. +A common error is `process is not defined`. webpack 4 polyfilled process automatically in the browser, but with v5 it's not the case anymore. If you're using `process.browser` in your components, you should switch to a window is not undefined check. From 5289a53482e60d7b8d61fb9379bd21ad2bfebf6b Mon Sep 17 00:00:00 2001 From: gatsbybot Date: Mon, 8 Mar 2021 10:52:39 +0000 Subject: [PATCH 2/2] chore: format --- docs/docs/reference/release-notes/migrating-from-v2-to-v3.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md b/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md index add74055a293d..335d995631c16 100644 --- a/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md +++ b/docs/docs/reference/release-notes/migrating-from-v2-to-v3.md @@ -127,7 +127,7 @@ When upgrading an already existing project (that has an existing `node_modules` Error: NormalModuleFactory.afterResolve (ReactRefreshPlugin) is no longer a waterfall hook, but a bailing hook instead. ``` -An effective way to get around this issue is deleting `node_modules` and `package-lock.json` and then running `npm install` again. Alternatively, you can use `npm dedupe`. +An effective way to get around this issue is deleting `node_modules` and `package-lock.json` and then running `npm install` again. Alternatively, you can use `npm dedupe`. ## Handling Breaking Changes