vercel / vercel/next.js

next/font/local custom font-family declaration causes mismatch between @font-face and className CSS

Open
#88,894 0 comments 3 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Font (next/font) Turbopack
Dominant language
JavaScript
Stars
142k
Forks
32.4k
Avg merge
2d 14h
Merged PRs (30d)
351

Description

Link to the code that reproduces this issue

https://github.com/oskari/next-local-font-family-mismatch

To Reproduce
  1. Clone the repo
  2. Run npm install && npm run dev
  3. Open browser DevTools → Elements → Styles
  4. Inspect the <h1> element
  5. Note: @font-face has font-family: "My Custom Font"
    but the class has font-family: myCustomFont (mismatch!)
Current vs. Expected behavior

Current (broken):

The generated CSS has mismatched font-family names:

/* @font-face uses the custom declaration value (correct) */
@font-face {
  font-family: My Custom Font;
  src: url(...) format("woff2");
}

/* But .className uses the JS variable name (wrong!) */
.mycustomfont_abc123__className {
  font-family: myCustomFont, sans-serif;  /* Note: no space, uses variable name! */
}

The font doesn't apply because My Custom FontmyCustomFont.

Expected:

Both should use the same font-family name from the custom declaration:

@font-face {
  font-family: 'My Custom Font';
  src: url(...) format("woff2");
}

.mycustomfont_abc123__className {
  font-family: 'My Custom Font', sans-serif;
}
Provide environment information
Operating System:
  Platform: darwin
  Arch: arm64
  Version: Darwin Kernel Version 25.2.0: Tue Nov 18 21:09:40 PST 2025; root:xnu-12377.61.12~1/RELEASE_ARM64_T6000
  Available memory (MB): 32768
  Available CPU cores: 10
Binaries:
  Node: 22.21.0
  npm: 10.9.4
  Yarn: 1.22.22
  pnpm: 10.8.0
Relevant Packages:
  next: 16.2.0-canary.1 // Latest available version is detected (16.2.0-canary.1).
  eslint-config-next: N/A
  react: 19.2.3
  react-dom: 19.2.3
  typescript: 5.9.3
Next.js Config:
  output: N/A
Which area(s) are affected? (Select all that apply)

Font (next/font)

Which stage(s) are affected? (Select all that apply)

next dev (local), next build (local)

Additional context

Root Cause (Turbopack):

In crates/next-core/src/next_font/local/:

  1. stylesheet.rs correctly uses the custom font-family declaration for @font-face rules
  2. But util.rs (build_font_family_string) always uses options.font_family() which returns the JS variable name, ignoring custom declarations
  3. Similarly, font_fallback.rs uses the variable name for fallback font naming

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with crates/next-core/src/next_font/local/util.rs and inspect build_font_family_string, then compare it with stylesheet.rs and font_fallback.rs. Run the linked reproduction with npm install && npm run dev and inspect the generated CSS; done means the custom font-family declaration is used consistently by both @font-face and the className CSS.

Written by the indexing model from the issue text.

Assessment

Tech stack
javascript, next.js, rust
Domain
build-system, frontend
Issue type
Bug
Difficulty
4/5
Estimated time
3-5 days
Activity status
Stale
Clarity
Clearly specified
Newbie friendliness
50/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.