oxc-project/oxc · warning · OxcDiagnostic

Custom fonts not added in `pages/_document.js` will only…

Error message

Custom fonts not added in `pages/_document.js` will only load for a single page. This is discouraged.

What it means

Warning from oxlint rule `nextjs/no-page-custom-font` (diagnostic `not_added_in_document`). Google-Font `<link>` tags placed in a page component instead of `pages/_document.js` only load for that one route, so the font flashes or misses entirely on navigation. The rule detects Google Fonts stylesheet links outside the custom document.

Solutions

Move the font link into `pages/_document.js`'s `<Head>` so it loads app-wide.
Prefer `next/font/google` (`import { Inter } from 'next/font/google'`), which self-hosts and preloads the font with no link tag at all.

Example fix

// before (pages/index.js)
<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />

// after (pages/_document.js, inside <Head>)
<link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />

Defensive patterns

Strategy: validation

Validate before calling

// Google Fonts link tags outside _document.js:
// rg -n 'fonts\.googleapis\.com' pages components app -g '!**/_document.*'

Prevention

Prefer `next/font/google` over any `<link>`; it self-hosts, preloads, and removes the rule entirely.
If you keep link tags, they belong in `pages/_document.js`'s `<Head>` only.
Codemod rule of thumb: any fonts.googleapis.com href outside _document.js is a bug.

When it happens

Trigger: A `<link href="https://fonts.googleapis.com/css...">` rendered in any file other than `pages/_document.js`.

Common situations: Pasting the `<link>` that Google Fonts gives you into a page's JSX instead of `_document.js`; per-landing-page custom fonts.

Related errors

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

Appendix: source

Thrown at crates/oxc_linter/src/rules/nextjs/no_page_custom_font.rs:12

use oxc_ast::{
    AstKind,
    ast::{Class, Function, JSXAttributeItem, JSXAttributeValue, JSXElementName},
};
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::{GetSpan, Span};

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

fn not_added_in_document(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Custom fonts not added in `pages/_document.js` will only load for a single page. This is discouraged.")
        .with_help("See: https://nextjs.org/docs/messages/no-page-custom-font")
        .with_label(span)
}

fn link_outside_of_head(span: Span) -> OxcDiagnostic {
    OxcDiagnostic::warn("Using `<link />` outside of `<Head>` will disable automatic font optimization. This is discouraged.")
        .with_help("See: 'https://nextjs.org/docs/messages/no-page-custom-font")
        .with_label(span)
}

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

declare_oxc_lint!(
    /// ### What it does
    ///
    /// Prevent page-only custom fonts.
    ///

View on GitHub (pinned to e1e7af627c)