@next/font

@next/font provides built-in automatic self-hosting for web fonts with optimal loading performance and zero layout shift. It enables convenient use of Google Fonts and local font files with performance and privacy optimizations, automatically downloading CSS and font files at build time for self-hosting.

Package Information

• Package Name: @next/font
• Package Type: npm
• Language: TypeScript
• Installation: pnpm add @next/font (included with Next.js 13+)

Core Imports

For Google Fonts:

import { Inter, Roboto, Open_Sans } from "@next/font/google";

For Local Fonts:

import localFont from "@next/font/local";

For CommonJS:

const { Inter, Roboto } = require("@next/font/google");
const localFont = require("@next/font/local").default;

Basic Usage

import { Inter } from "@next/font/google";
import localFont from "@next/font/local";

// Google Font
const inter = Inter({
  subsets: ["latin"],
  variable: "--font-inter",
});

// Local Font
const myFont = localFont({
  src: "./my-font.woff2",
  display: "swap",
});

// Use in JSX
export default function Page() {
  return (
    <div className={inter.className}>
      <h1 className={myFont.className}>Hello World</h1>
    </div>
  );
}

Architecture

@next/font is built around several key components:

• Google Fonts Integration: 1625+ pre-configured Google Font functions with automatic optimization
• Local Font Support: Universal loader for custom font files with fallback generation
• Build-time Processing: Downloads and processes fonts during build for optimal performance
• CSS Variable Support: Optional CSS custom properties for variable fonts and theme switching
• Fallback Generation: Automatic fallback font metrics calculation to prevent layout shift
• Self-hosting: Downloads and serves all fonts from Next.js static assets

Capabilities

Google Fonts

Access to 1625+ Google Fonts with automatic optimization, self-hosting, and zero layout shift. Each font is available as a named export with TypeScript support and configurable options.

// Generic Google Font function signature
function GoogleFont<T extends CssVariable | undefined = undefined>(options?: {
  weight?: string | string[] | 'variable';
  style?: string | string[];
  display?: Display;
  variable?: T;
  preload?: boolean;
  fallback?: string[];
  adjustFontFallback?: boolean;
  subsets?: string[];
}): T extends undefined ? NextFont : NextFontWithVariable;

type Display = 'auto' | 'block' | 'swap' | 'fallback' | 'optional';

Google Fonts

Local Fonts

Universal font loader for custom font files with automatic fallback generation and optimal loading performance.

function localFont<T extends CssVariable | undefined = undefined>(
  options: LocalFont<T>
): T extends undefined ? NextFont : NextFontWithVariable;

interface LocalFont<T extends CssVariable | undefined = undefined> {
  src: string | Array<{
    path: string;
    weight?: string;
    style?: string;
  }>;
  display?: Display;
  weight?: string;
  style?: string;
  adjustFontFallback?: 'Arial' | 'Times New Roman' | false;
  fallback?: string[];
  preload?: boolean;
  variable?: T;
  declarations?: Array<{ prop: string; value: string }>;
}

Local Fonts

Core Types

type CssVariable = `--${string}`;

type Display = 'auto' | 'block' | 'swap' | 'fallback' | 'optional';

interface NextFont {
  className: string;
  style: { 
    fontFamily: string; 
    fontWeight?: number; 
    fontStyle?: string; 
  };
}

interface NextFontWithVariable extends NextFont {
  variable: string;
}

Error Handling

@next/font throws NextFontError instances for configuration and loading issues. These errors are automatically caught and formatted by Next.js during development and build processes.

Common error scenarios include:

• Invalid font configuration options (invalid weight, style, or subset values)
• Network failures during font fetching in development mode
• Incompatible Next.js versions (requires Next.js 13+)
• Missing required font subsets or weights for specific Google Fonts
• Invalid local font file paths or unsupported font formats