oxc-project/oxc · warning · OxcDiagnostic
`styled-jsx` should not be used in `pages/_document.js`
Error message
`styled-jsx` should not be used in `pages/_document.js`
What it means
Warning from oxlint rule `nextjs/no-styled-jsx-in-document`. `pages/_document.js` is the server-rendered shell; styled-jsx styles are scoped and applied at render time, so `<style jsx>` there has no effect or leaks across pages. The rule flags styled-jsx style elements inside the custom document.
Source
Thrown at crates/oxc_linter/src/rules/nextjs/no_styled_jsx_in_document.rs:12
use oxc_ast::{
AstKind,
ast::{JSXAttributeItem, JSXElementName},
};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
use crate::{AstNode, context::LintContext, rule::Rule};
fn no_styled_jsx_in_document_diagnostic(span: Span) -> OxcDiagnostic {
OxcDiagnostic::warn("`styled-jsx` should not be used in `pages/_document.js`")
.with_help("Possible to fix it please see: https://nextjs.org/docs/messages/no-styled-jsx-in-document#possible-ways-to-fix-it")
.with_label(span)
}
#[derive(Debug, Default, Clone)]
pub struct NoStyledJsxInDocument;
declare_oxc_lint!(
/// ### What it does
///
/// Prevent usage of styled-jsx in `pages/_document.js`.
///
/// ### Why is this bad?
///
/// Custom CSS like styled-jsx is not allowed in a [Custom Document](https://nextjs.org/docs/pages/building-your-application/routing/custom-document).
///
/// ### Examples
///View on GitHub (pinned to e1e7af627c)
Solutions
- Move the styled-jsx block to `pages/_app.js` or the component that needs it.
- For true global CSS, `import './globals.css'` in `_app.js` instead of any inline style element.
Example fix
// before (pages/_document.js)
<style jsx global>{`body { margin: 0 }`}</style>
// after (pages/_app.js)
import './globals.css'; // body { margin: 0 } Defensive patterns
Strategy: validation
Validate before calling
// styled-jsx inside the custom document: // rg -n '<style jsx' pages/_document.*
Prevention
- Global styles belong in a CSS file imported from `_app.js`, not styled-jsx in `_document.js`.
- Keep `_document.js` free of anything but Html/Head/Body/Main/NextScript structure.
- Lint `_document.js` with the nextjs plugin in CI.
When it happens
Trigger: A `<style jsx>` (styled-jsx attributed) element rendered anywhere in `pages/_document.js`.
Common situations: Trying to set global reset styles directly on the document; moving shared styles 'up' to the wrong root file while consolidating CSS.
Related errors
- next/script's `beforeInteractive` strategy should not be use
- `<Document />` from `next/document` should not be imported o
- Do not include multiple instances of `<Head/>`
- Do not use `<head>` element. Use `<Head />` from `next/head`
- Prevent usage of `next/head` in `pages/_document.js`.
AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20).
Data as JSON: /api/errors/4017df6589052263.
Report an issue: GitHub.