nextjs - ✅(Solved) Fix next/font/local custom font-family declaration causes mismatch between @font-face and className CSS [1 pull requests, 1 participants]

nextjs2026-01-22 10:45:26

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.

GitHub issue URL

Helpful · Quick feedback

GitHub stats

vercel/next.js#88894•Fetched 2026-04-08 02:03:43

View on GitHub

Comments

Participants

Timeline

Reactions

Author

oskari

Participants

oskari

Timeline (top)

labeled ×2cross-referenced ×1issue_type_added ×1mentioned ×1

Root Cause

The font doesn't apply because My Custom Font ≠ myCustomFont.

Fix Action

Fixed

Fixed by PR: fix(next-font): respect custom font-family declarations in local fonts (Turbopack) (https://github.com/vercel/next.js/pull/88895)

PR fix notes

PR #88895: fix(next-font): respect custom font-family declarations in local fonts (Turbopack)

Repository: vercel/next.js
Author: oskari
State: open | merged: False
Link: https://github.com/vercel/next.js/pull/88895

Description (problem / solution / changelog)

What?

Fixes a bug in Turbopack where next/font/local with a custom font-family declaration would generate mismatched CSS:

@font-face correctly used the custom declaration value (e.g., "My Custom Font")
But .className incorrectly used the JS variable name (e.g., "myCustomFont")

This caused the font not to apply because the names didn't match.

Why?

When users specify a custom font-family in declarations:

const myCustomFont = localFont({
  src: './font.woff2',
  declarations: [{ prop: 'font-family', value: 'My Custom Font' }]
})

The generated CSS had a mismatch:

@font-face { font-family: 'My Custom Font'; ... } ✅
.className { font-family: 'myCustomFont', ... } ❌

Note: This bug only affects Turbopack. The Webpack implementation already handles this correctly via postcss-next-font.

How?

Updated the Turbopack implementation to check for custom font-family declarations when building:

util.rs: build_font_family_string now checks declarations for a custom font-family value before falling back to the variable name
font_fallback.rs: get_font_fallbacks now uses the custom font-family for fallback naming (e.g., "My Custom Font Fallback" instead of "myCustomFont Fallback")

Test Plan

Added test fixture with custom font-family containing a space
Added test verifying fontFamily matches the custom declaration
Webpack: ✅ Already passes (not affected)
Turbopack: ✅ Now passes with fix

Fixes #88894

Changed files

crates/next-core/src/next_font/local/font_fallback.rs (modified, +15/-2)
crates/next-core/src/next_font/local/util.rs (modified, +16/-1)
test/e2e/next-font/app/pages/with-local-fonts.js (modified, +18/-0)
test/e2e/next-font/index.test.ts (modified, +33/-0)

Code Example

/* @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! */
}

---

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

.mycustomfont_abc123__className {
  font-family: 'My Custom Font', sans-serif;
}

---

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

RAW_BUFFERClick to expand / collapse

Link to the code that reproduces this issue

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

To Reproduce

Clone the repo
Run npm install && npm run dev
Open browser DevTools → Elements → Styles
Inspect the <h1> element
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 Font ≠ myCustomFont.

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/:

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

extent analysis

TL;DR

Update the build_font_family_string function in util.rs to use the custom font-family declaration instead of the JS variable name.

Guidance

Review the util.rs file in crates/next-core/src/next_font/local/ to understand how the build_font_family_string function is currently implemented.
Modify the build_font_family_string function to prioritize the custom font-family declaration over the JS variable name.
Verify that the updated function correctly generates the CSS with matching font-family names for @font-face and the class.
Test the changes by running npm run dev and inspecting the generated CSS in the browser DevTools.

Example

// Expected output after updating build_font_family_string
@font-face {
  font-family: 'My Custom Font';
  src: url(...) format("woff2");
}

.mycustomfont_abc123__className {
  font-family: 'My Custom Font', sans-serif;
}

Notes

The issue seems to be specific to the Turbopack implementation in Next.js, and updating the build_font_family_string function should resolve the font-family mismatch.

Recommendation

Apply workaround: Update the build_font_family_string function to use the custom font-family declaration, as this is a targeted fix for the identified root cause.

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?

#integration issue #index setup #retrieval issue #search optimization #API routing

Still need to ship something?

×6

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