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..3e3901a682ddd8f --- /dev/null +++ b/errors/no-stylesheets-in-head-component.md @@ -0,0 +1,42 @@ +# 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' + +export default function Document() { + return ( + + + + + +
+ + + + ) +} +``` + +Note that the functional syntax for `Document` above is preferred over the `class` syntax, so that it will be compatible with React Server Components down the line. + +### 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..31d86fc503d7c26 100644 --- a/packages/next/shared/lib/head.tsx +++ b/packages/next/shared/lib/head.tsx @@ -161,11 +161,19 @@ 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