Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

fix(gatsby): Add DEV_SSR note to 95312 error #36295

Merged
merged 3 commits into from
Aug 2, 2022
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
19 changes: 18 additions & 1 deletion docs/docs/debugging-html-builds.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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).
2 changes: 1 addition & 1 deletion docs/docs/glossary/server-side-rendering.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
---
title: Server Side Rendering
title: Server-Side Rendering
disableTableOfContents: true
---

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion integration-tests/gatsby-cli/__tests__/build-ssr-errors.js
Original file line number Diff line number Diff line change
Expand Up @@ -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`
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -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\\".",
}
`;

Expand Down
2 changes: 1 addition & 1 deletion packages/gatsby-cli/src/structured-errors/error-map.ts
Original file line number Diff line number Diff line change
Expand Up @@ -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,
Expand Down
2 changes: 1 addition & 1 deletion packages/gatsby/src/utils/flags.ts
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ const activeFlags: Array<IFlag> = [
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,
},
Expand Down