Issue Station
Sign In
Tools hereToolbox

nextjs - ✅(Solved) Fix Docs: Wrong example on Pages router with Fonts in _document.tsx [1 pull requests, 1 comments, 2 participants]

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…
GitHub stats
vercel/next.js#88832•Fetched 2026-04-08 02:03:51
View on GitHub
Comments
1
Participants
2
Timeline
11
Reactions
1
Author
ackvfackvf
Participants
ackvfackvfgithub-actions[bot]github-actions[bot]
Assignees
icyJosephicyJoseph
Timeline (top)
labeled ×2renamed ×2assigned ×1closed ×1

Error Message

However, that raises an error:

Error Type

Build Error

Error Message

next/font: error: next/font: error:

Fix Action

Fixed

PR fix notes

PR #91346: docs: remove incorrect _document.tsx font example

Description (problem / solution / changelog)

saw the issue about the _document.tsx example not working. next/font cant be used in _document.tsx, it throws an error. removed that section from the docs since _app.tsx already has the correct example.

fixes #88832

Changed files

  • docs/01-app/01-getting-started/13-fonts.mdx (modified, +0/-44)

Code Example

import { Html, Head, Main, NextScript } from 'next/document'
import { Geist } from 'next/font/google'
 
const geist = Geist({
  subsets: ['latin'],
})
 
export default function Document() {
  return (
    <Html lang="en" className={geist.className}>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

---

import { Geist, Geist_Mono } from 'next/font/google'
import type { AppProps } from 'next/app'
 
const geist = Geist({
  variable: "--font-geist-sans",
  subsets: ['latin'],
})

const geistMono= Geist_Mono({
  variable: "--font-geist-mono",
  subsets: ["latin"],
  weight: ["400", "700"],
})

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <main className={`${geist.variable} ${geistMono.variable} font-sans`}>
      <Component {...pageProps} />
    </main>
  )
}

---

@theme inline {
  --font-sans: var(--font-geist-sans);
  --font-mono: var(--font-geist-mono);
}

---

<html class="font-sans">  // gives "--font-geist-sans is not defined
  <body class="font-sans">  // gives "--font-geist-sans is not defined
    <div id="__next">
      <div id="App" class="font-sans geist-module__variable">  // --font-geist-sans is defined
        // Font works correctly here
        // ...
RAW_BUFFERClick to expand / collapse

What is the documentation issue?

Thank you for fixing the issue so quickly after I have raised it in #88291, however, it is still incorrect.

It suggests defining fonts in the _document.tsx page with

import { Html, Head, Main, NextScript } from 'next/document'
import { Geist } from 'next/font/google'
 
const geist = Geist({
  subsets: ['latin'],
})
 
export default function Document() {
  return (
    <Html lang="en" className={geist.className}>
      <Head />
      <body>
        <Main />
        <NextScript />
      </body>
    </Html>
  )
}

However, that raises an error:

Error Type

Build Error

Error Message

next/font: error:

Build Output

./fe/_document.tsx next/font: error: Cannot be used within _document.tsx

Next.js version: 16.0.8 (Turbopack)

Is there any context that might help us understand?

related: https://github.com/vercel/next.js/issues/88291, https://stackoverflow.com/a/79863801/985454

I found a better way to define and use the fonts natively with tailwind as mentioned in the linked SO QA. It allows to use multiple fonts and refer to them via variables.

Instead of .className it utilizes the .variable output.

The required part that made it work together was to specify the default font class together with the definition.

  • Add font-sans to the same element or after the fonts are defined with .variable.

_app.tsx

import { Geist, Geist_Mono } from 'next/font/google'
import type { AppProps } from 'next/app'
 
const geist = Geist({
  variable: "--font-geist-sans",
  subsets: ['latin'],
})

const geistMono= Geist_Mono({
  variable: "--font-geist-mono",
  subsets: ["latin"],
  weight: ["400", "700"],
})

export default function MyApp({ Component, pageProps }: AppProps) {
  return (
    <main className={`${geist.variable} ${geistMono.variable} font-sans`}>
      <Component {...pageProps} />
    </main>
  )
}

globals.css

This defines the utility classes for later use, e.g. className="font-sans"

@theme inline {
  --font-sans: var(--font-geist-sans);
  --font-mono: var(--font-geist-mono);
}

This explains how it works:

<html> - this is where tailwind defines its utility classes, so that we can use font-sans and font-mono as declared in globals.css, however, the variables for the referenced fonts are not yet defined, so they end up unresolved.

<img width="524" height="71" alt="Image" src="https://github.com/user-attachments/assets/89b37e54-8fe5-4482-9dc6-622e5df17ca2" /> 
<html class="font-sans">  // gives "--font-geist-sans is not defined
  <body class="font-sans">  // gives "--font-geist-sans is not defined
    <div id="__next">
      <div id="App" class="font-sans geist-module__variable">  // --font-geist-sans is defined
        // Font works correctly here
        // ...

Does the docs page already exist? Please link to it.

https://nextjs.org/docs/pages/getting-started/fonts#with-tailwind-css

extent analysis

TL;DR

To fix the issue, define fonts in _app.tsx instead of _document.tsx and use the .variable output to refer to them via variables in Tailwind CSS.

Guidance

  • The error occurs because next/font cannot be used within _document.tsx, so it's necessary to define fonts in _app.tsx.
  • Use the .variable output to define fonts as CSS variables, and then reference these variables in your Tailwind CSS configuration.
  • Make sure to specify the default font class (e.g., font-sans) together with the font definition using .variable.
  • Verify that the fonts are correctly applied by checking the CSS variables in the browser's developer tools.

Example

// _app.tsx
import { Geist } from 'next/font/google'

const geist = Geist({
  variable: "--font-geist-sans",
  subsets: ['latin'],
})

export default function MyApp({ Component, pageProps }) {
  return (
    <main className={`${geist.variable} font-sans`}>
      <Component {...pageProps} />
    </main>
  )
}

Notes

  • This solution assumes that you are using Next.js with Tailwind CSS and next/font for font management.
  • The provided example is based on the code snippets in the issue description and may need to be adapted to your specific use case.

Recommendation

Apply workaround: Define fonts in _app.tsx instead of _document.tsx and use the .variable output to refer to them via variables in Tailwind CSS, as this approach allows for correct font rendering and avoids the error caused by using next/font in _document.tsx.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…
#API middleware#SSR setup#ISR setup#authentication setup#request error

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING