oxc-project/oxc · warning · OxcDiagnostic

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

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.

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)

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.