next/font classname/variable prop usage | Next.js | Page 1

latent obsidian Jul 12, 2025, 5:55 PM

#

Adding a classname to the className means it provides the font from here, not applying it. Am I right on this?

lofty gullBOT Jul 12, 2025, 5:55 PM

#

Hi @latent obsidian. I'm kapa.ai, your friendly support bot. I will try to answer your question by searching through the knowledge base. :wave:

#

When you use the className or variable property from next/font, you are applying the font style to the element. The className (e.g., inter.className) is a generated CSS class that, when added to an element, applies the font styles provided by next/font to that element. Similarly, the variable property (e.g., inter.variable) is used to define a CSS variable for the font, which you can then reference in your CSS.

So, adding the generated className or variable to an element's className does not just "provide" the font—it actually applies the font styles to that element or its children.

Example with className:

<p className={inter.className}>Hello, Next.js!</p>

This applies the Inter font to the paragraph.

Example with variable:

<html className={inter.variable}>
  <body>
    <p className="my-text">Hello World</p>
  </body>
</html>

And in your CSS:

.my-text {
  font-family: var(--font-inter);
}

This approach also applies the font, but via a CSS variable you can use in your stylesheets.

In summary: using className or variable from next/font applies the font, not just makes it available for later use.
See official docs for details.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@latent obsidian Kapa.ai is still learning and improving, please let me know how I did by reacting below.

latent obsidian Jul 12, 2025, 5:57 PM

#

@lofty gull so the document suggest contructing the font object in layout.tsx or page.tsx?

lofty gullBOT Jul 12, 2025, 5:57 PM

#

Let me check the knowledge base for you again. Give me one moment! :books:

#

The documentation suggests that you can construct the font object in either a layout file (such as layout.tsx) or a page file (such as page.tsx), depending on the scope where you want the font to be applied:

If you want the font to be applied globally (to your entire application), you should construct the font object in your root layout file (layout.tsx) and apply its className or variable to the <html> or <body> tag. This ensures the font is available throughout your app.
If you only want the font on a specific page, you can construct the font object in that page's file (page.tsx) and apply it locally.

For example, constructing and applying in layout.tsx:

import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en" className={inter.className}>
      <body>{children}</body>
    </html>
  )
}

See example in the docs

For page-level usage, you can import and use the font in page.tsx:

import { Inter } from 'next/font/google'

const inter = Inter({ subsets: ['latin'] })

export default function Page() {
  return (
    <div className={inter.className}>
      <p>Hello world</p>
    </div>
  )
}

See example in the docs

Summary:

Use layout.tsx for global font application.
Use page.tsx for page-specific font application.

#

The documentation also recommends using a font definitions file if you need to reuse the same font in multiple places, to avoid duplicating font instances see here.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@latent obsidian Kapa.ai is still learning and improving, please let me know how I did by reacting below.

latent obsidian Jul 18, 2025, 2:08 AM

#

@lofty gull would you suggest put the local fonts file in /public? if not, where it would be ?

lofty gullBOT Jul 18, 2025, 2:08 AM

#

Let me check the knowledge base for you again. Give me one moment! :books:

#

Based on the knowledge sources, it is not recommended to put your local font files in the /public folder for use with next/font/local. The documentation and community discussions highlight that font files should be colocated with your code, such as inside the app directory (e.g., app/fonts), rather than in /public. Using /public can lead to confusion and errors, such as "module not found," because next/font/local expects a relative path to the font file from where the loader is called, not a public URL or absolute path see discussion.

Recommended location:
Place your font files inside your project, for example:

/app/fonts/MyFont.woff2

and reference them like:

const myFont = localFont({ src: './fonts/MyFont.woff2' })

if your loader is in app/layout.tsx or a similar location see official docs.

Summary:

Do not put local font files in /public for use with next/font/local.
Do colocate them inside your app directory or another directory within your source code, and use a relative path.

This approach is both recommended and supported by the latest Next.js documentation and community feedback see discussion.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@latent obsidian Kapa.ai is still learning and improving, please let me know how I did by reacting below.

latent obsidian Jul 18, 2025, 2:11 AM

#

@lofty gull since it's in app/, would it be served on the app router?

lofty gullBOT Jul 18, 2025, 2:11 AM

#

Let me check the knowledge base for you again. Give me one moment! :books:

#

No, placing your font files inside the app/ directory does not make them publicly accessible or routable via the App Router. According to the documentation, only files like page.js or route.js make a route publicly accessible. Other files, such as assets (like fonts) colocated in the app/ directory, are not exposed to the client as public routes or static assets. They are used internally by your application and are not directly accessible via a URL see documentation.

This means you can safely colocate your font files in `app/fonts` (or similar) without worrying about them being served as public files or being routable by the App Router.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@latent obsidian Kapa.ai is still learning and improving, please let me know how I did by reacting below.

latent obsidian Jul 18, 2025, 2:16 AM

#

@lofty gull I have multiple font format, which is suitable for web?

lofty gullBOT Jul 18, 2025, 2:16 AM

#

Let me check the knowledge base for you again. Give me one moment! :books:

#

The knowledge sources indicate that for web usage, the most suitable font formats are WOFF2, WOFF, TTF, and OTF. Among these, WOFF2 is generally preferred for web because it offers the best compression and performance, but WOFF, TTF, and OTF are also supported and commonly used. For example, Next.js documentation and related guides show usage of .woff2, .woff, .ttf, and .otf files in their font loading examples see here.

If you are using Next.js's Open Graph (OG) image generation, only ttf, otf, and woff are supported, with a preference for ttf or otf for faster parsing see OG image generation limitations.

Summary:

WOFF2 (best for web, if available)
WOFF
TTF
OTF

Choose WOFF2 when possible for optimal web performance, but the others are also valid and supported in Next.js.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@latent obsidian Kapa.ai is still learning and improving, please let me know how I did by reacting below.

latent obsidian Jul 18, 2025, 2:50 AM

#

@lofty gull how do I know the path when using next/font/local

lofty gullBOT Jul 18, 2025, 2:50 AM

#

Let me check the knowledge base for you again. Give me one moment! :books:

#

When using next/font/local, the src (or path in an array) should be relative to the file where you call the font loader.

For example, if your font file is at app/fonts/MyFont.woff2 and you are calling localFont in app/layout.tsx, your path would be:

const myFont = localFont({ src: './fonts/MyFont.woff2' })

If your font file is in a different directory, adjust the path accordingly. For example, if your font is at styles/fonts/MyFont.ttf and you are calling from app/page.tsx, you would use:

const myFont = localFont({ src: '../styles/fonts/MyFont.ttf' })

Key point:

The path is always relative to the directory where the font loader function is called, not from the project root or the public folder see documentation.

If you use an incorrect path, you will get a "module not found" error see discussion.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@latent obsidian Kapa.ai is still learning and improving, please let me know how I did by reacting below.

latent obsidian Jul 18, 2025, 3:48 AM

#

@lofty gull my font is in app/fonts/,why it failed to build only when deploying to Vercelli?

lofty gullBOT Jul 18, 2025, 3:48 AM

#

Let me check the knowledge base for you again. Give me one moment! :books:

#

If your font is in app/fonts/ and your build fails only when deploying to Vercel, there are a few possible causes based on the knowledge sources:

Incorrect Path Reference
The src path in next/font/local must be relative to the file where you call the loader. If the path is incorrect, you will get a "module not found" error. This is a common issue, especially if the build works locally but fails in CI/CD or on Vercel, where the file structure or working directory might be different. Double-check that your path is correct and relative to the importing file see discussion.
Node.js Version Issues
There have been reports of font loading failures with certain Node.js versions, especially with next/font/local. For example, users have experienced "Unknown font format" or build errors with Node 23.x, which were resolved by upgrading to Node v23.5.0 or using a different version see issue.
Platform-Specific Issues
Some font loading or path resolution issues have been reported to be platform-specific (e.g., Windows vs. Linux). Since Vercel builds on Linux, a path that works on your local (Windows) machine might fail on Vercel if there are case sensitivity or path separator issues see issue.
Public vs. App Directory Confusion
Make sure you are not referencing the font as if it were in /public. The next/font/local loader does not expect fonts to be in /public, and the path should not start with a slash or reference /public see discussion.

#

What to check:

Ensure your src path is correct and relative to the file where you call localFont.
Verify your Node.js version on Vercel matches a version known to work with your Next.js version.
Check for case sensitivity and path separator issues.
Do not use /public in your font path.

If you have checked all of the above and the issue persists, please provide the exact error message from the Vercel build logs for more targeted help.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

#

@latent obsidian Kapa.ai is still learning and improving, please let me know how I did by reacting below.

latent obsidian Jul 18, 2025, 3:59 AM

#

@lofty gull I can build locally, fonts are in ~/app/fonts/JetBrainsMono, calling from ~/app/(index)/layout.tsxwith path: "../fonts/JetBrainsMono/JetBrainsMono-Regular.woff2" while vecel deploy output Module not found: Can't resolve '../fonts/JetBrainsMono/JetBrainsMono-Regular.woff2'

lofty gullBOT Jul 18, 2025, 3:59 AM

#

Let me check the knowledge base for you again. Give me one moment! :books:

#

Your issue—being able to build locally but getting Module not found: Can't resolve '../fonts/JetBrainsMono/JetBrainsMono-Regular.woff2' on Vercel—most likely comes from how the path is resolved by next/font/local and differences in case sensitivity or directory structure between your local environment and Vercel.

Key points from the knowledge sources:

The src (or path) for next/font/local must be relative to the file where you call the loader. So, from ~/app/(index)/layout.tsx, the path ../fonts/JetBrainsMono/JetBrainsMono-Regular.woff2 assumes that (index) is a folder inside app/, and fonts is a sibling of (index). If this is not the case, the path will fail on Vercel, which uses a case-sensitive filesystem see discussion.
Case sensitivity: Vercel's build environment is case-sensitive, so any mismatch in folder or file names (e.g., jetbrainsmono vs. JetBrainsMono) will cause a "module not found" error on Vercel, even if it works locally on a case-insensitive filesystem see guide.
The font files should not be in /public for use with next/font/local, and the path should not start with a slash see discussion.

What you should do:

#

Double-check the directory structure and casing in your repository. Make sure the path you use in layout.tsx exactly matches the actual folder and file names, including capitalization.
Ensure the path is correct relative to the file where you call the loader. For example, if your structure is:
```
app/
  (index)/
    layout.tsx
  fonts/
    JetBrainsMono/
      JetBrainsMono-Regular.woff2
```
Then ../fonts/JetBrainsMono/JetBrainsMono-Regular.woff2 is correct. But if (index) is not a folder, or if the casing is off, it will fail.
Check your Git settings: If you recently renamed files or folders to fix casing, make sure Git has actually committed those changes. Sometimes, Git on case-insensitive systems (like macOS or Windows) does not pick up casing changes unless you force it see guide.

Summary:
Your path is only correct if the directory structure and casing are exactly as you wrote. Vercel's case-sensitive filesystem will fail if there is any mismatch. Double-check both the path and the casing in your repo and in your import statement see discussion.

If you continue to have issues, try moving your font files to a simple path like `app/fonts/` and reference them with a straightforward relative path, ensuring all casing matches exactly.

#next/font classname/variable prop usage

In summary: using className or variable from next/font applies the font, not just makes it available for later use. See official docs for details.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

The documentation also recommends using a font definitions file if you need to reuse the same font in multiple places, to avoid duplicating font instances see here.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

This approach is both recommended and supported by the latest Next.js documentation and community feedback see discussion.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

This means you can safely colocate your font files in app/fonts (or similar) without worrying about them being served as public files or being routable by the App Router.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

Choose WOFF2 when possible for optimal web performance, but the others are also valid and supported in Next.js.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

If you use an incorrect path, you will get a "module not found" error see discussion.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

If you have checked all of the above and the issue persists, please provide the exact error message from the Vercel build logs for more targeted help.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

If you continue to have issues, try moving your font files to a simple path like app/fonts/ and reference them with a straightforward relative path, ensuring all casing matches exactly.

Note: you can ask me a follow up question by @ mentioning me again :speech_balloon:

In summary: using className or variable from next/font applies the font, not just makes it available for later use.
See official docs for details.

This means you can safely colocate your font files in `app/fonts` (or similar) without worrying about them being served as public files or being routable by the App Router.

If you continue to have issues, try moving your font files to a simple path like `app/fonts/` and reference them with a straightforward relative path, ensuring all casing matches exactly.