Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Warn in dev mode when stylesheets are added using next/head (#34004)
This commit adds a development mode warning in the console if you try to include <link rel="stylesheet"> tags in next/head, e.g. ``` <Head> <link ref="stylesheet" href="..." /> </Head> ``` The warning message explains that this pattern will not work well with Suspense/streaming and recommends using a custom Document component instead. ## Feature - [x] Implements an existing feature request or RFC. Make sure the feature request has been accepted for implementation before opening a PR. - [ ] Related issues linked using `fixes #number` - [x] Integration tests added - [x] Documentation added - [ ] Telemetry added. In case of a feature if it's used or not. - [x] Errors have helpful link attached, see `contributing.md` Co-authored-by: JJ Kasper <22380829+ijjk@users.noreply.github.com>
- Loading branch information
Showing
4 changed files
with
82 additions
and
5 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,42 @@ | ||
# No Stylesheets In Head Component | ||
|
||
### Why This Error Occurred | ||
|
||
A `<link rel="stylesheet">` 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 ( | ||
<Html> | ||
<Head> | ||
<link rel="stylesheet" href="..." /> | ||
</Head> | ||
<body> | ||
<Main /> | ||
<NextScript /> | ||
</body> | ||
</Html> | ||
) | ||
} | ||
``` | ||
|
||
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) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters