Optimizing fonts

The tea shop gets its own font

A web font is a font file the browser downloads, so a page can show text in a font the visitor's computer doesn't have. The tea shop wants Lora, a serif font from Google Fonts, Google's free library of fonts. The usual way to add one is a <link> to Google's servers. Then every visitor's browser asks Google for the font, and the text waits, or jumps, while it arrives.

Next.js has its own way: next/font. You import the font as a function, call it, and put the class it gives you on an element. Here is the shop with Lora. It was built with real Next.js 16.4.3 and run with next start, and the page was opened in real Chrome, in a window 800 px wide. The Browser tab shows Chrome's picture of it.

The tea shop, in Lora from next/font/googleNext.js

app/globals.csslayout.tsxpage.tsxnext.config.tscreate-next-apppackage.jsoncreate-next-apptsconfig.jsoncreate-next-app

app/layout.tsx

1import { Lora } from "next/font/google";2import "./globals.css";3 4const lora = Lora({5  subsets: ["latin"],6});7 8export const metadata = { title: "Tea shop" };9 10export default function RootLayout({ children }: LayoutProps<"/">) {11  return (12    <html lang="en">13      <body className={lora.className}>{children}</body>14    </html>15  );16}

BrowserStepsTerminalNetwork

Recorded from Next.js 16.4.3

localhost:3000/Tea shop

A picture of the page in real Chrome, in a window 800 px wide, taken once the page had loaded with its styles. Open it full size

Line 1 of app/layout.tsx imports Lora from next/font/google. Every Google font is there as a function, named after the font. Lines 4 to 6 call it: subsets: ["latin"] says the shop is written in latin letters. The call returns an object, and line 13 puts its className on <body>, so all the shop's text is in Lora. The call is at the top of the file, outside the component, and saved in a const: next/font needs it there, because it reads the call while the app builds.

Now look at what the visitor gets. Open the Network tab:

• A class. The body has class="LwFUCa_className", a name next/font made up for this build. In the CSS, that class says font-family:Lora,Lora Fallback.
• The font, in the shop's own CSS. The stylesheet has @font-face rules: the CSS that tells the browser where a font's file is. Each src points at ../media/, a file in /_next/static/media/ on the shop's own site. There's no Google address in it.
• A preload. The response has a link header with rel=preload; as="font". A preload tells the browser to start downloading a file now, before it reads the CSS that needs it.

Then open the Steps tab. It lists every file Chrome asked for while it opened the page: the page itself, then the font, then the stylesheet and the page's scripts. Every address is on the shop's own site. The browser never asked Google for anything.

That's because the shop got Lora long before: next build asked Google Fonts for the CSS and the font files, saved the files with the app's other files, and wrote CSS that points at them. Next.js calls this self-hosting: your site hosts the font itself.

A Google font, downloaded when you build

Each Google font is a function in next/font/google, named after the font. A font with a space in its name has an underscore instead: Roboto Mono is Roboto_Mono. Call it at the top of a file, outside any component, and save what it returns in a variable. Each row is one option you can pass:

subsets: which letters to preload

Google splits each font into subsets: one file for latin letters, one for Cyrillic, one for Vietnamese, and so on. The recorded CSS has an @font-face rule for each of Lora's subsets, and each rule has a unicode-range: the letters its file covers. subsets: ["latin"] doesn't remove the others; it picks which files to preload. In the recording, only the latin file is in the link header, so the browser starts downloading it right away, whatever letters the page has. A file that isn't preloaded is downloaded only when the page has a letter in its unicode-range. Next.js's docs say it warns you if you leave subsets out while preload is on.

display: what shows while the font downloads

Every rule in the recorded CSS says font-display:swap, next/font's default. It means: show the text at once in the fallback font, and swap to Lora when it arrives. The other values come from CSS: optional, for example, uses the font only if it arrives very quickly, and keeps the fallback otherwise.

Whom the browser asks

Compare the two ways to load Lora. Before you switch, guess: which version's page asks another site for something?

1import "./globals.css";2 3export const metadata = { title: "Tea shop" };4 5export default function RootLayout({ children }: LayoutProps<"/">) {6  return (7    <html lang="en">8      <head>9        <link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Lora:wght@400..700&display=swap" />10      </head>11      <body>{children}</body>12    </html>13  );14}

With the <link>, the page's requests include fonts.googleapis.com: each visitor's browser asks Google for the CSS, and then for the font files on Google's servers. That's another site to connect to before the text can change, and Google sees each visitor's address. In these recordings, Chrome never reached Google: the recorder stops every request to another site before it leaves, and the list shows it as not sent. With next/font, the list has only the shop's own addresses.

Weights, and fonts that hold them all

A font's weight is how thick its letters are: 400 is regular, 700 is bold. Most fonts are a set of files, one per weight. A variable font is one file that holds a range of weights, and the browser draws any weight in that range from it. Lora is variable, from 400 to 700, so the shop's Lora call needed no weight: every recorded Lora rule says font-weight:400 700, and the bold heading and the regular text come from the same file. Next.js's docs recommend variable fonts for that reason.

Poppins isn't variable. Try it without a weight, then with two:

1import { Poppins } from "next/font/google";2import "./globals.css";3 4const poppins = Poppins({5  subsets: ["latin"],6});7 8export const metadata = { title: "Tea shop" };9 10export default function RootLayout({ children }: LayoutProps<"/">) {11  return (12    <html lang="en">13      <body className={poppins.className}>{children}</body>14    </html>15  );16}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ... > Build error occurredError: Turbopack build failed with 1 error:./app/layout.tsxError: Module not found: Can't resolve 'next/font/google/target.css'Missing weight for Poppins. Available weights: 100, 200, 300, 400, 500, 600, 700, 800, 900 Debug info:- Execution of <ModuleAssetContext as AssetContext>::resolve_asset failed- Execution of resolve failed- Execution of resolve_internal failed- Execution of NextFontGoogleReplacer::import_map_result failed- Execution of *get_font_css_properties failed- Execution of font_options_from_query_map failed- Missing weight for Poppins. Available weights: 100, 200, 300, 400, 500, 600, 700, 800, 900Error while looking up import map: Missing weight for Poppins. Available weights: 100, 200, 300, 400, 500, 600, 700, 800, 900 Debug info:- Execution of NextFontGoogleReplacer::import_map_result failed- Execution of *get_font_css_properties failed- Execution of font_options_from_query_map failed- Missing weight for Poppins. Available weights: 100, 200, 300, 400, 500, 600, 700, 800, 900 https://nextjs.org/docs/messages/module-not-found     at <unknown> (https://nextjs.org/docs/messages/module-not-found)

Without a weight, the build stops: Missing weight for Poppins. Available weights: 100, 200, 300, 400, 500, 600, 700, 800, 900. Next.js can't guess which files you want. With weight: ["400", "700"] on line 6, it builds, and the CSS has rules for weight 400 and for weight 700, each with its own file. Every weight you add means more files in the build, and more for the browser to download when a page uses it, so ask only for the ones the design uses. A variable font can also take weight, as a range like "400 700".

The fallback that keeps text from jumping

Until Lora arrives, the browser shows the text in a fallback font, one already on the computer. When Lora arrives, it swaps. If the two fonts take different room, every line changes length, and the text below moves: the page shifts. Visitors lose their place, or click the wrong thing. It has a name, Cumulative Layout Shift, and it's one of the Core Web Vitals, the numbers Google measures for how a page feels to use.

next/font makes a fallback that takes the font's room. The shop's recorded CSS, at the top of the page, has this rule after Lora's:

• font-family:Lora Fallback and src:local(Times New Roman): a font named Lora Fallback, which is Times New Roman from the visitor's computer. next/font picks Times New Roman for a serif font like Lora, and Arial for a sans-serif one.
• size-adjust:115.2%: draw it 15.2% bigger, so its letters are as wide as Lora's, on average.
• ascent-override:87.33%, descent-override:23.78% and line-gap-override:0.0%: how much room each line takes above and below the letters, set to Lora's.

The class says font-family:Lora,Lora Fallback: Lora when it has arrived, the resized Times New Roman until then. The numbers come from measurements of each font that Next.js ships with. To see the difference, the shop's comparison page draws one sentence three times, each in one font, with a box around it:

One sentence in Lora, in Lora Fallback, and in Times New RomanNext.js

app/compare/compare.module.csspage.tsxglobals.csslayout.tsxpage.tsxnext.config.tscreate-next-apppackage.jsoncreate-next-apptsconfig.jsoncreate-next-app

app/compare/page.tsx

1import styles from "./compare.module.css";2 3const sentence = "Green tea, mint tea and oolong";4 5export default function ComparePage() {6  return (7    <main>8      <p className={styles.label}>Lora, once it has loaded</p>9      <p className={styles.lora}>{sentence}</p>10      <p className={styles.label}>Lora Fallback: Times New Roman, resized</p>11      <p className={styles.fallback}>{sentence}</p>12      <p className={styles.label}>Times New Roman as it is</p>13      <p className={styles.plain}>{sentence}</p>14    </main>15  );16}

BrowserTerminalNetwork

Recorded from Next.js 16.4.3

localhost:3000/compareTea shop

A picture of the page in real Chrome, in a window 800 px wide, taken once the page had loaded with its styles. Open it full size

In app/compare/page.tsx, lines 9, 11 and 13 draw the sentence with three classes from compare.module.css, a CSS Module. Lines 14 to 16 of the CSS Module name "Lora Fallback" directly, only to show it on its own. Real Chrome's picture shows the result: the resized fallback's box is almost exactly as wide and as tall as Lora's, and plain Times New Roman's is clearly narrower and shorter. Swap the second line for the first and almost nothing moves. Swap the third for the first and the line grows.

You get this without asking. Two options change it, and they're easy to mix up:

• adjustFontFallback is meant to control the resized fallback itself. For a Google font it's true or false, and true by default. webpack honours it, but with Turbopack, the default, 16.4.3 ignores it for a Google font: the Rust code that reads the options expects adjust_font_fallback (issue 74134), so adjustFontFallback: false stays true. Images and fonts under the hood records it. For a local font it names the font to resize: "Arial" (the default), "Times New Roman", or false for none.
• fallback is a list of font families of your own, for the CSS to try when the font isn't there, like ["Georgia", "serif"].

Here is Lora with fallback, built the same way:

1import { Lora } from "next/font/google";2import "./globals.css";3 4const lora = Lora({5  subsets: ["latin"],6  fallback: ["Georgia", "serif"],7});8 9export const metadata = { title: "Tea shop" };10 11export default function RootLayout({ children }: LayoutProps<"/">) {12  return (13    <html lang="en">14      <body className={lora.className}>{children}</body>15    </html>16  );17}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="/_next/static/chunks/2b4wod6nsrv18.css" data-precedence="next">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/3cfn99dbrcvvp.js">
    <script src="/_next/static/chunks/1j_b1xq_woyiy.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/1tq6ppe__m8m-.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body class="_9nL0yG_className">
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <!--&-->
    <main>
      <h1>Tea shop</h1>
      <p>Fresh tea, sent to your door. Every box is packed by hand.</p>
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/3cfn99dbrcvvp.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
  </body>
</html>

Line 6 of app/layout.tsx passes fallback: ["Georgia", "serif"]. In the Network tab, the class says font-family:Lora,Georgia,serif, and the CSS has no Lora Fallback rule: in this recorded build, with Turbopack, the families you list took the resized fallback's place. How the two combine depends on the bundler in Next.js 16.4.3: Turbopack uses your list instead (font_fallback.rs, lines 67 and 68), while the webpack loader keeps the resized fallback and adds your families after it (postcss-next-font.ts, lines 132 to 136). To keep text from jumping, leave fallback out.

A font file of your own

The shop's tea of the day is written in Caveat, a handwriting font, from a file the shop keeps in its project. (Caveat is free to share under the SIL Open Font License; the license travels with the file.) For a font file, use localFont from next/font/local. The shop keeps its fonts in one file, app/fonts.ts, and imports them where they're used:

Caveat from a font file, on the teas pageNext.js

app/fonts/Caveat.woff2teas/page.tsxfonts.tsglobals.csslayout.tsxpage.tsxnext.config.tscreate-next-apppackage.jsoncreate-next-apptsconfig.jsoncreate-next-app

app/fonts.ts

1import localFont from "next/font/local";2 3export const caveat = localFont({4  src: "./fonts/Caveat.woff2",5  weight: "400 700",6});

BrowserTerminalNetwork

Recorded from Next.js 16.4.3

//teas

localhost:3000/teasTea shop

A picture of the page in real Chrome, in a window 800 px wide, taken once the page had loaded with its styles. Open it full size

Line 1 of app/fonts.ts imports localFont. Lines 3 to 6 call it and export the result as caveat. Line 4 is the file's path, relative to app/fonts.ts: the file is app/fonts/Caveat.woff2 in the tree. (WOFF2 is the compressed font format every current browser reads.) Caveat is a variable font, so line 5 gives its range of weights, "400 700". For a font that comes as several files, like a regular and a bold one, src takes a list, with a path, weight and style for each. In app/teas/page.tsx, line 1 imports caveat, and line 6 puts its className on the heading.

Open the Network tab, and pick each page above the HTML:

• The CSS has an @font-face rule whose src is a copy of the file in /_next/static/media/, with font-weight:400 700, and a fallback rule: src:local(Arial) with size-adjust:74.77%. For a local font, next/font measures the file itself while it builds, and uses Arial unless you say otherwise.
• /teas's link header preloads two fonts: Caveat and Lora. /'s preloads only Lora. Next.js preloads a font on the routes whose files use it: Lora is in the root layout, so every route preloads it; Caveat is only in the teas page.

The rules are the same as for a Google font, without the download: the build copies the file, writes the CSS, preloads it, and sizes a fallback. Load each font once, in one place like app/fonts.ts, and import it where you need it: each call of a font function adds the font to the app again.

Fonts as CSS variables

className sets the font on one element. A shop with two fonts usually wants them in its CSS instead: Lora for the text, Caveat for every heading. For that, give each font a variable. Each row is one way to apply a font:

Both fonts as CSS variables, used from globals.cssNext.js

app/fonts/Caveat.woff2fonts.tsglobals.csslayout.tsxpage.tsxnext.config.tscreate-next-apppackage.jsoncreate-next-apptsconfig.jsoncreate-next-app

app/fonts.ts

1import { Lora } from "next/font/google";2import localFont from "next/font/local";3 4export const lora = Lora({5  subsets: ["latin"],6  variable: "--font-lora",7});8 9export const caveat = localFont({10  src: "./fonts/Caveat.woff2",11  weight: "400 700",12  variable: "--font-caveat",13});

BrowserTerminalNetwork

Recorded from Next.js 16.4.3

localhost:3000/Tea shop

A picture of the page in real Chrome, in a window 800 px wide, taken once the page had loaded with its styles. Open it full size

In app/fonts.ts, line 6 names Lora's variable --font-lora, and line 12 names Caveat's --font-caveat. Now lora.variable is a class that defines --font-lora. Line 8 of app/layout.tsx puts both classes on <html>. In app/globals.css, line 6 gives the body var(--font-lora), and line 10 gives every h1 var(--font-caveat). The Network tab shows the variables' classes (their names made up for this build), like .fAxLeq_variable{--font-lora:"Lora", "Lora Fallback"}: the value is the font and its fallback. Caveat's class sets --font-caveat:"caveat", "caveat Fallback" the same way, with the family names next/font gave the local font in this build.

A variable is just CSS, so it works from a CSS Module too, as font-family: var(--font-lora) in any class. It also works with Tailwind CSS. Tailwind CSS in Next.js pointed font-sans at Geist this way. A theme variable in Tailwind CSS's --font-* namespace makes a class of its own, so the shop can have a font-hand class for Caveat:

The two fonts as Tailwind CSS's font-serif and font-handNext.js

app/fonts/Caveat.woff2fonts.tsglobals.csslayout.tsxpage.tsxnext.config.tspackage.jsontsconfig.jsoncreate-next-app

app/globals.css

1@import "tailwindcss";2 3@theme inline {4  --font-serif: var(--font-lora);5  --font-hand: var(--font-caveat);6}

BrowserTerminalNetwork

Recorded from Next.js 16.4.3

localhost:3000/Tea shop

A picture of the page in real Chrome, in a window 800 px wide, taken once the page had loaded with its styles. Open it full size

Lines 3 to 6 of app/globals.css point --font-serif at Lora's variable and add --font-hand for Caveat's. The Network tab has .font-hand{font-family:var(--font-caveat)} and .font-serif{font-family:var(--font-lora)}, and the layout's body uses font-serif. Line 4 of app/page.tsx gives the heading font-hand, and the picture shows it in Caveat. app/fonts.ts and app/layout.tsx are the same as before.

Does the visitor's browser ask Google?

Fonts reach a page in many ways. Sort these: does each one make the visitor's browser ask Google, or only the shop's own site?

Common mix-ups

• "next/font/google loads the font from Google in the browser." No. The build downloads it, and the visitor's browser gets it from your site. The recorded visit asked no other site.
• "subsets removes every other alphabet." No. The CSS still has a rule for each subset; subsets picks which file to preload.
• "Every font needs a weight." Only fonts that aren't variable. A variable font like Lora has every weight in its range in one file.
• "The fallback font is a second download." No. It's a font already on the computer, like Times New Roman or Arial, resized with size-adjust.
• "Calling the font function inside a component is fine." Call it once, at the top of a file, and import the result. Each call adds the font to the app again.
• "A font in the root layout and a font in one page are preloaded the same way." No. A font is preloaded on the routes that use it: the root layout's on every route, a page's only on that page.
• "variable gives you the font's name." It gives you a class name. The class defines the CSS variable, so put it on an element around the text.

Practice exercises

A Next.js project can't run inside this page, so answer first, then use the hints.

import { Lora } from "next/font/google";
import "./globals.css";

const lora = Lora({
  subsets: ["latin"],
});

export const metadata = { title: "Tea shop" };

export default function RootLayout({ children }: LayoutProps<"/">) {
  return (
    <html lang="en">
      <body className={lora.className}>{children}</body>
    </html>
  );
}

import { Poppins } from "next/font/google";
import "./globals.css";

const poppins = Poppins({
  subsets: ["latin"],
});

export const metadata = { title: "Tea shop" };

export default function RootLayout({ children }: LayoutProps<"/">) {
  return (
    <html lang="en">
      <body className={poppins.className}>{children}</body>
    </html>
  );
}

import { Poppins } from "next/font/google";
import "./globals.css";

const poppins = Poppins({
  subsets: ["latin"],
  weight: ["400", "700"],
});

export const metadata = { title: "Tea shop" };

export default function RootLayout({ children }: LayoutProps<"/">) {
  return (
    <html lang="en">
      <body className={poppins.className}>{children}</body>
    </html>
  );
}

import { caveat } from "../fonts";

export default function TeasPage() {
  return (
    <main>
      <h1 className={caveat.className}>Tea of the day: mint</h1>
      <p>Picked this morning, packed by hand.</p>
    </main>
  );
}

body {
  font-family: var(--font-lora);
}

h1 {
  font-family: /* Caveat goes here */;
  font-size: 48px;
}

body {
  margin: 0;
  padding: 24px 32px;
  background: #f6f3ea;
  color: #2f3b2f;
  font-family: var(--font-lora);
}

h1 {
  font-family: var(--font-caveat);
  font-size: 48px;
}

@import "tailwindcss";

@theme inline {
  --font-serif: var(--font-lora);
}

@import "tailwindcss";

@theme inline {
  --font-serif: var(--font-lora);
  --font-hand: var(--font-caveat);
}

Check your understanding

For each question, ask when the font is downloaded, by whom, and what the browser shows until it arrives.

Key takeaways

• next/font/google downloads a Google font during next build, and your site serves it from /_next/static/media/. The visitor's browser never asks Google.
• Call a font function once, at the top of a file, and use its className, style or variable. Put fonts you share in one file, like app/fonts.ts.
• subsets picks the file to preload. A variable font needs no weight; any other font needs at least one, and each weight is another file.
• next/font adds a fallback font sized like yours, with size-adjust and the line overrides, so text barely moves when the font arrives. display is swap by default.
• next/font/local does the same for a font file of your own. A font is preloaded on the routes that use it.
• With variable, a font becomes a CSS variable that global CSS, CSS Modules and Tailwind CSS's @theme can use.

Coming next: Scripts and third-party code. It loads analytics, a chat widget, a map and a video with next/script, and records when each one loads.