From 0384a91d4a495021b5d1124d0087196621df30bd Mon Sep 17 00:00:00 2001 From: Lennart Date: Tue, 2 Aug 2022 06:19:45 +0200 Subject: [PATCH] fix(gatsby): Add DEV_SSR note to 95312 error (#36295) (cherry picked from commit db531f86f9e89d1da72d44399ad5fb72092be454) --- docs/docs/debugging-html-builds.md | 19 ++++++++++++++++++- docs/docs/glossary/server-side-rendering.md | 2 +- .../troubleshooting-common-errors.md | 4 ++-- .../gatsby-cli/__tests__/build-ssr-errors.js | 2 +- .../__tests__/__snapshots__/index.ts.snap | 2 +- .../src/structured-errors/error-map.ts | 2 +- packages/gatsby/src/utils/flags.ts | 2 +- 7 files changed, 25 insertions(+), 8 deletions(-) diff --git a/docs/docs/debugging-html-builds.md b/docs/docs/debugging-html-builds.md index 915980b30cabf..b273cccefa308 100644 --- a/docs/docs/debugging-html-builds.md +++ b/docs/docs/debugging-html-builds.md @@ -35,7 +35,7 @@ Errors while building static HTML files (the build-time React SSR process) or wh 5. Some other reason :-) #1 is the most common reason building static files fail. If it's another reason, you have to be a bit more creative in figuring - out the problem. + out the problem. The [`DEV_SSR` feature](#ssr-during-gatsby-develop) can help you with this. ## How to check if `window` is defined @@ -106,3 +106,20 @@ exports.onCreateWebpackConfig = ({ stage, loaders, actions }) => { ``` Another solution is to use a package like [loadable-components](https://github.com/gregberge/loadable-components). The module that tries to use `window` will be dynamically loaded only on the client side (and not during SSR). + +## SSR during `gatsby develop` + +Server-Side render (SSR) pages on full reloads during `gatsby develop`. This helps you detect SSR bugs and fix them without needing to do full builds with `gatsby build`. Once enabled, go to your desired page and do a full reload (e.g. Ctrl + R or F5). + +Add the `DEV_SSR` flag to your `gatsby-config.js`: + +```js:title=gatsby-config.js +module.exports = { + flags: { + DEV_SSR: true + }, + plugins: [...] +} +``` + +Please give feedback in the [DEV_SSR umbrella discussion](https://github.com/gatsbyjs/gatsby/discussions/28138). diff --git a/docs/docs/glossary/server-side-rendering.md b/docs/docs/glossary/server-side-rendering.md index fefca70c2b7e0..abd479032702b 100644 --- a/docs/docs/glossary/server-side-rendering.md +++ b/docs/docs/glossary/server-side-rendering.md @@ -1,5 +1,5 @@ --- -title: Server Side Rendering +title: Server-Side Rendering disableTableOfContents: true --- diff --git a/docs/docs/how-to/local-development/troubleshooting-common-errors.md b/docs/docs/how-to/local-development/troubleshooting-common-errors.md index dfdd8ec186532..8f7cec8398594 100644 --- a/docs/docs/how-to/local-development/troubleshooting-common-errors.md +++ b/docs/docs/how-to/local-development/troubleshooting-common-errors.md @@ -91,12 +91,12 @@ The following errors are related to styles in your site, using CSS, preprocessor ### Inconsistent CSS styles between develop and build using styled-components or emotion -_NOTE: We're in process of adding SSR support to the develop server. To use it now, enable the `DEV_SSR` flag in your gatsby-config.js — https://github.com/gatsbyjs/gatsby/discussions/28138_ - A common problem that trips up users that install and begin to use styled-components or emotion is not including the related plugin in the config. Because `gatsby develop` doesn't run server-side rendering, the build may look different if the plugin is not included to tell Gatsby to server-side render the styles for the CSS-in-JS solution being used. Adding `gatsby-plugin-styled-components` (in the case of styled-components) or `gatsby-plugin-emotion` (in the case of emotion) to `gatsby-config.js` will inform Gatsby to process the styles server-side so they display correctly in the final build. +You can use the [`DEV_SSR` feature flag](/docs/debugging-html-builds#ssr-during-gatsby-develop) inside your `gatsby-config` to enable SSR support during `gatsby develop` which can help you debug such issues. + ## Errors with GraphQL Gatsby's GraphQL data layer provides access to build time data, there are sometimes errors you may encounter while implementing plugins that are sourcing data or adding nodes to the schema yourself. diff --git a/integration-tests/gatsby-cli/__tests__/build-ssr-errors.js b/integration-tests/gatsby-cli/__tests__/build-ssr-errors.js index d6c5a13758341..a1a96319c393c 100644 --- a/integration-tests/gatsby-cli/__tests__/build-ssr-errors.js +++ b/integration-tests/gatsby-cli/__tests__/build-ssr-errors.js @@ -16,7 +16,7 @@ describe(`gatsby build (SSR errors)`, () => { logs.should.contain(`failed Building static HTML for pages`) logs.should.contain(`ERROR #95312`) logs.should.contain( - `"window" is not available during server side rendering.` + `"window" is not available during Server-Side Rendering.` ) logs.should.contain( `See our docs page for more info on this error: https://gatsby.dev/debug-html` diff --git a/packages/gatsby-cli/src/reporter/__tests__/__snapshots__/index.ts.snap b/packages/gatsby-cli/src/reporter/__tests__/__snapshots__/index.ts.snap index 67e09c8571889..73625445e5fd0 100644 --- a/packages/gatsby-cli/src/reporter/__tests__/__snapshots__/index.ts.snap +++ b/packages/gatsby-cli/src/reporter/__tests__/__snapshots__/index.ts.snap @@ -130,7 +130,7 @@ Object { "docsUrl": "https://gatsby.dev/debug-html", "level": "ERROR", "stack": Array [], - "text": "\\"navigator\\" is not available during server side rendering.", + "text": "\\"navigator\\" is not available during Server-Side Rendering. Enable \\"DEV_SSR\\" to debug this during \\"gatsby develop\\".", } `; diff --git a/packages/gatsby-cli/src/structured-errors/error-map.ts b/packages/gatsby-cli/src/structured-errors/error-map.ts index bd8ff14637580..3821e2c1c132c 100644 --- a/packages/gatsby-cli/src/structured-errors/error-map.ts +++ b/packages/gatsby-cli/src/structured-errors/error-map.ts @@ -34,7 +34,7 @@ const errors = { }, "95312": { text: (context): string => - `"${context.ref}" is not available during server side rendering.`, + `"${context.ref}" is not available during Server-Side Rendering. Enable "DEV_SSR" to debug this during "gatsby develop".`, level: Level.ERROR, docsUrl: `https://gatsby.dev/debug-html`, category: ErrorCategory.USER, diff --git a/packages/gatsby/src/utils/flags.ts b/packages/gatsby/src/utils/flags.ts index ef6ea0108e498..7ac11b99fb762 100644 --- a/packages/gatsby/src/utils/flags.ts +++ b/packages/gatsby/src/utils/flags.ts @@ -97,7 +97,7 @@ const activeFlags: Array = [ command: `develop`, telemetryId: `DevSsr`, experimental: false, - description: `Server Side Render (SSR) pages on full reloads during develop. Helps you detect SSR bugs and fix them without needing to do full builds. See umbrella issue for how to update custom webpack config.`, + description: `Server Side Render (SSR) pages on full reloads during develop. Helps you detect SSR bugs and fix them without needing to do full builds.`, umbrellaIssue: `https://gatsby.dev/dev-ssr-feedback`, testFitness: (): fitnessEnum => true, },