oxc-project/oxc · warning · OxcDiagnostic

Using `<link />` outside of `<Head>` will disable automatic

Error message

Using `<link />` outside of `<Head>` will disable automatic font optimization. This is discouraged.

What it means

Warning from oxlint rule `nextjs/no-page-custom-font` (diagnostic `link_outside_of_head`). Next.js can automatically preload and inline font stylesheets, but only when the font `<link>` sits inside a `<Head>` from `next/head`. Rendered elsewhere in the tree, that optimization is disabled and the font becomes late or render-blocking.

Source

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

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.
    ///
    /// ### Why is this bad?
    ///
    /// * The custom font you're adding was added to a page - this only adds the font to the specific page and not the entire application.
    /// * The custom font you're adding was added to a separate component within `pages/_document.js` - this disables automatic font optimization.
    ///
    /// ### Examples

View on GitHub (pinned to e1e7af627c)

Solutions

Wrap the `<link>` in `<Head>` from `next/head` in the page that needs the font.
Or centralize the link in `pages/_document.js`, or replace it with `next/font` as the sibling diagnostic suggests.

Example fix

// before
<div>
  <link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
  <Content />
</div>

// after
import Head from 'next/head';
<div>
  <Head>
    <link href="https://fonts.googleapis.com/css2?family=Inter" rel="stylesheet" />
  </Head>
  <Content />
</div>

Defensive patterns

Strategy: validation

Validate before calling

// font links not wrapped in next/head:
// rg -n -B2 'fonts\.googleapis\.com' -g '*.tsx' src | rg -v 'Head'

Prevention

Font links go inside `<Head>` from `next/head`, never bare in page JSX.
When extracting components, keep the `<link>` and its `<Head>` wrapper together.
Run the nextjs oxlint rules on every PR so a refactor cannot silently unwrap Head.

When it happens

Trigger: A Google Fonts `<link>` whose ancestor chain does not include a `Head` component imported from `next/head` — e.g. placed directly in page JSX or a nested wrapper component — in a file that is not `pages/_document.js`.

Common situations: Wrapping font links in a custom `<FontWrapper>` that forgot the `Head`; moving markup around during refactors until the link escapes the Head tree.

Related errors

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