From 1722e7da86577cbf361eb189c68d0198c9f91461 Mon Sep 17 00:00:00 2001 From: Kara Erickson Date: Thu, 3 Feb 2022 20:33:08 -0800 Subject: [PATCH 1/4] Warn in dev mode when stylesheets are added using next/head This commit adds a development mode warning in the console if you try to include tags in next/head, e.g. ``` ``` The warning message explains that this pattern will not work well with Suspense/streaming and recommends using a custom Document component instead. --- errors/manifest.json | 4 ++ errors/no-stylesheets-in-head-component.md | 44 +++++++++++++++++++ packages/next/shared/lib/head.tsx | 15 ++++--- .../client-navigation/test/index.test.js | 23 ++++++++++ 4 files changed, 81 insertions(+), 5 deletions(-) create mode 100644 errors/no-stylesheets-in-head-component.md diff --git a/errors/manifest.json b/errors/manifest.json index 4b0e39c5251d8a2..568ca2fffdafb35 100644 --- a/errors/manifest.json +++ b/errors/manifest.json @@ -488,6 +488,10 @@ "title": "script-tags-in-head-component", "path": "/errors/no-script-tags-in-head-component.md" }, + { + "title": "stylesheets-in-head-component", + "path": "/errors/no-stylesheets-in-head-component.md" + }, { "title": "max-custom-routes-reached", "path": "/errors/max-custom-routes-reached.md" diff --git a/errors/no-stylesheets-in-head-component.md b/errors/no-stylesheets-in-head-component.md new file mode 100644 index 000000000000000..9da7d0c8bc5ff30 --- /dev/null +++ b/errors/no-stylesheets-in-head-component.md @@ -0,0 +1,44 @@ +# No Stylesheets In Head Component + +### Why This Error Occurred + +A `` tag was added using the `next/head` component. + +We don't recommend this pattern because it will potentially break when used with Suspense and/or streaming. In these contexts, `next/head` tags aren't: + +- guaranteed to be included in the initial SSR response, so loading could be delayed until client-side rendering, regressing performance. + +- loaded in any particular order. The order that the app's Suspense boundaries resolve will determine the loading order of your stylesheets. + +### Possible Ways to Fix It + +#### Document + +Add the stylesheet in a custom `Document` component: + +```jsx +// pages/_document.js +import Document, { Html, Head, Main, NextScript } from 'next/document' + +class MyDocument extends Document { + render() { + return ( + + + + + +
+ + + + ) + } +} + +export default MyDocument +``` + +### Useful Links + +- [Custom Document](https://nextjs.org/docs/advanced-features/custom-document) diff --git a/packages/next/shared/lib/head.tsx b/packages/next/shared/lib/head.tsx index 25bbac4b8711e14..2397dae6647307e 100644 --- a/packages/next/shared/lib/head.tsx +++ b/packages/next/shared/lib/head.tsx @@ -161,11 +161,16 @@ function reduceComponents( return React.cloneElement(c, newProps) } } - // TODO(kara): warn for stylesheets as well as scripts - if (process.env.NODE_ENV === 'development' && c.type === 'script') { - console.warn( - `Do not add