oxc-project/oxc · warning · OxcDiagnostic

`<Document />` from `next/document` should not be imported o

Error message

`<Document />` from `next/document` should not be imported outside of `pages/_document.js`. See: https://nextjs.org/docs/messages/no-document-import-in-page

What it means

Warning from oxlint rule `nextjs/no-document-import-in-page`. `next/document` defines the server-rendered shell for the whole app and is only valid in `pages/_document.js`; importing it in any other file breaks rendering assumptions. The rule tracks import declarations resolving to `next/document` and reports them everywhere else.

Source

Thrown at crates/oxc_linter/src/rules/nextjs/no_document_import_in_page.rs:14

use oxc_ast::AstKind;
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;

use crate::{
    AstNode,
    context::{ContextHost, LintContext},
    rule::Rule,
    utils::is_document_page,
};

fn no_document_import_in_page_diagnostic(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("`<Document />` from `next/document` should not be imported outside of `pages/_document.js`. See: https://nextjs.org/docs/messages/no-document-import-in-page").with_help("Prevent importing `next/document` outside of `pages/_document.js`.").with_label(span)
}

#[derive(Debug, Default, Clone)]
pub struct NoDocumentImportInPage;

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Prevent importing `next/document` outside of `pages/_document.js`.
    ///
    /// ### Why is this bad?
    ///
    /// Importing `next/document` outside of `pages/_document.js` can cause
    /// unexpected issues in your Next.js application.
    ///
    /// ### Examples
    ///
    /// Examples of **incorrect** code for this rule:

View on GitHub (pinned to e1e7af627c)

Solutions

Delete the import; only `_document.js` may use `next/document`.
For per-page head tags in the pages router use `import Head from 'next/head'`.
In the app router, render tags in `app/layout.tsx` or use the `metadata` API.

Example fix

// before (in pages/index.tsx)
import { Head } from 'next/document';

// after
import Head from 'next/head';

Defensive patterns

Strategy: validation

Validate before calling

// next/document imports outside _document.js:
// rg -n "from 'next/document'" pages app components -g '!pages/_document.*'

Prevention

Memorize the split: `next/document` only in `pages/_document.js`; `next/head` in pages.
Fix IDE auto-imports immediately when they suggest `next/document` outside the document.
Run oxlint with the nextjs plugin in CI to catch stray imports.

When it happens

Trigger: An `import ... from 'next/document'` (default, named, namespace, or side-effect form) in any module other than `pages/_document.js`.

Common situations: Wanting `<Html>`/`<Head>`/`<NextScript>` pieces in a regular page; copy-pasting from `_document.js` into a layout; IDE auto-import picking `next/document`'s `Head`.

Related errors

AI-assisted analysis of oxc-project/oxc@e1e7af627c (2026-08-20). Data as JSON: /api/errors/811857be260dd594. Report an issue: GitHub.