{"record":{"id":"23ca771097fd1e67","repo":"oxc-project/oxc","slug":"prevent-usage-of-next-head-in-pages-document-j","errorCode":null,"errorMessage":"Prevent usage of `next/head` in `pages/_document.js`.","messagePattern":"Prevent usage of `next/head` in `pages/_document\\.js`\\.","errorType":"validation","errorClass":"OxcDiagnostic","httpStatus":null,"severity":"warning","filePath":"crates/oxc_linter/src/rules/nextjs/no_head_import_in_document.rs","lineNumber":13,"sourceCode":"use oxc_ast::AstKind;\nuse oxc_diagnostics::OxcDiagnostic;\nuse oxc_macros::declare_oxc_lint;\nuse oxc_span::Span;\n\nuse crate::{\n    AstNode,\n    context::{ContextHost, LintContext},\n    rule::Rule,\n};\n\nfn no_head_import_in_document_diagnostic(span: Span) -> OxcDiagnostic {\n    OxcDiagnostic::warn(\"Prevent usage of `next/head` in `pages/_document.js`.\")\n        .with_help(\"See https://nextjs.org/docs/messages/no-head-import-in-document\")\n        .with_label(span)\n}\n\n#[derive(Debug, Default, Clone)]\npub struct NoHeadImportInDocument;\n\ndeclare_oxc_lint!(\n    /// ### What it does\n    ///\n    /// Prevents the usage of `next/head` inside a Next.js document.\n    ///\n    /// ### Why is this bad?\n    ///\n    /// Importing `next/head` inside `pages/_document.js` can cause\n    /// unexpected issues in your Next.js application.\n    ///\n    /// ### Examples","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/oxc-project/oxc/blob/e1e7af627c8843ab64044ed466b128fcc21a035b/crates/oxc_linter/src/rules/nextjs/no_head_import_in_document.rs#L1-L31","documentation":"Warning from oxlint rule `nextjs/no-head-import-in-document`. Inside `pages/_document.js`, `next/head` does not work: the document is rendered outside the normal page tree, and using `next/head` there can duplicate head output on every request. Next.js provides `Head` from `next/document` for that file, and the rule enforces the distinction.","triggerScenarios":"An import of `next/head` in a file identified as `pages/_document.js`.","commonSituations":"Copying a page's head import into `_document.js` while scaffolding; IDE auto-import choosing the wrong `Head`.","solutions":["Replace `import Head from 'next/head'` with `import { Head } from 'next/document'` in `_document.js`.","Keep `next/head` imports only in individual pages."],"exampleFix":"// before (pages/_document.js)\nimport Head from 'next/head';\n\n// after\nimport { Head } from 'next/document';","handlingStrategy":"validation","validationCode":"// next/head imported into the document:\n// rg -n \"from 'next/head'\" pages/_document.*","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Only two valid head imports: `next/head` in pages, `next/document`'s named `Head` in `_document.js`.","When scaffolding the custom document, start from the official template.","Run oxlint with the nextjs plugin so the wrong import is flagged instantly."],"tags":["nextjs","pages-router","imports","lint"],"backgroundTag":"lint-wrong-import-source","analyzedSha":"e1e7af627c8843ab64044ed466b128fcc21a035b","analyzedAt":"2026-08-20T07:01:07.079Z","contentChangedAt":"2026-08-20T07:01:07.079Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}