CtrlK
BlogDocsLog inGet started
Tessl Logo

tessl/npm-next--font

Built-in automatic self-hosting for any font file with optimal loading and zero layout shift

—

Pending
Quality

Pending

Does it follow best practices?

Impact

Pending

No eval scenarios have been run

SecuritybySnyk

Pending

The risk profile of this skill

Overview
Eval results
Files

local-fonts.mddocs/

Local Fonts

Universal font loader for custom font files with automatic fallback generation and optimal loading performance. Supports all major font formats and provides comprehensive configuration options.

Capabilities

Local Font Function

/**
 * Load custom local font files with optimal performance
 * @param options - Local font configuration
 * @returns Font object with className, style, and optional variable property
 */
function localFont<T extends CssVariable | undefined = undefined>(
  options: LocalFont<T>
): T extends undefined ? NextFont : NextFontWithVariable;

Local Font Configuration

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 }>;
}

Source Configuration

The src property accepts either a single font file or an array of font files with different weights and styles.

Single Font File

src: string;

Path to a single font file. All font formats are supported (woff2, woff, ttf, otf, eot).

Multiple Font Files

src: Array<{
  path: string;
  weight?: string;
  style?: string;
}>;

Array of font descriptors for different weights and styles:

  • path: Path to the font file
  • weight: Font weight (e.g., '400', '700', 'bold')
  • style: Font style ('normal', 'italic')

Font Properties

Display Property

display?: Display;

Controls CSS font-display behavior:

  • 'auto': Browser default
  • 'block': Block until font loads
  • 'swap': Show fallback, swap when ready (recommended)
  • 'fallback': Brief block, then fallback
  • 'optional': Use fallback if font loads slowly

Weight and Style

weight?: string;
style?: string;

Default weight and style for the font family:

  • weight: CSS font-weight value ('400', '700', 'bold', etc.)
  • style: CSS font-style value ('normal', 'italic', 'oblique')

Fallback Configuration

adjustFontFallback?: 'Arial' | 'Times New Roman' | false;
fallback?: string[];
  • adjustFontFallback: Automatically calculate fallback metrics using Arial or Times New Roman as reference
  • fallback: Array of fallback font names to use if custom font fails to load

Variable Fonts

variable?: T;

CSS custom property name for the font family. Enables using the font via CSS variables.

Preloading

preload?: boolean;

Whether to preload the font file for faster initial rendering.

Custom Declarations

declarations?: Array<{ prop: string; value: string }>;

Additional CSS properties to include in the @font-face declaration:

  • prop: CSS property name
  • value: CSS property value

Usage Examples

Single Font File

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

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

export default function Page() {
  return (
    <div className={myFont.className}>
      <h1>Custom Font Text</h1>
    </div>
  );
}

Multiple Font Files (Font Family)

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

const myFontFamily = localFont({
  src: [
    {
      path: './fonts/my-font-regular.woff2',
      weight: '400',
      style: 'normal',
    },
    {
      path: './fonts/my-font-italic.woff2',
      weight: '400',
      style: 'italic',
    },
    {
      path: './fonts/my-font-bold.woff2',
      weight: '700',
      style: 'normal',
    },
  ],
  display: 'swap',
});

Variable Font with CSS Custom Property

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

const myVariableFont = localFont({
  src: './fonts/my-variable-font.woff2',
  variable: '--font-custom',
  weight: '100 900', // Variable font weight range
});

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

Fallback Configuration

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

const customSerif = localFont({
  src: './fonts/custom-serif.woff2',
  fallback: ['Georgia', 'Times New Roman', 'serif'],
  adjustFontFallback: 'Times New Roman', // Use Times New Roman metrics for fallback adjustment
  display: 'swap',
});

Font with Custom CSS Declarations

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

const customFont = localFont({
  src: './fonts/custom-font.woff2',
  declarations: [
    { prop: 'font-feature-settings', value: '"liga" 1, "calt" 1' },
    { prop: 'font-variation-settings', value: '"wght" 400' },
  ],
});

Preloading Critical Fonts

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

const headingFont = localFont({
  src: './fonts/heading-font.woff2',
  preload: true, // Preload for above-the-fold content
  display: 'block', // Block rendering until font loads
});

Supported Font Formats

@next/font supports all major web font formats:

Modern Formats (Recommended)

  • WOFF2 (.woff2) - Best compression, widely supported
  • WOFF (.woff) - Good compression, universal support

Legacy Formats

  • TrueType (.ttf) - Uncompressed, large file sizes
  • OpenType (.otf) - Supports advanced typography features
  • EOT (.eot) - Internet Explorer legacy support

Font File Organization

Recommended Structure

public/
  fonts/
    my-font-regular.woff2
    my-font-bold.woff2
    my-font-italic.woff2

Relative Path Usage

Font paths are relative to the public directory:

const myFont = localFont({
  src: './fonts/my-font.woff2', // Resolves to public/fonts/my-font.woff2
});

Performance Optimization

Format Priority

  1. WOFF2: Use as primary format for best compression
  2. WOFF: Use as fallback for older browsers
  3. TTF/OTF: Avoid in production due to large file sizes

Loading Strategy

  • Preload: Critical fonts used above the fold
  • Swap display: Non-critical fonts to prevent render blocking
  • Subset fonts: Remove unused characters to reduce file size
  • Variable fonts: Single file for multiple weights/styles

Fallback Optimization

const optimizedFont = localFont({
  src: './fonts/custom-font.woff2',
  adjustFontFallback: 'Arial', // Prevents layout shift
  fallback: ['system-ui', 'Arial', 'sans-serif'],
  display: 'swap',
});

Error Handling

Local fonts handle various error scenarios:

Missing Font Files

  • Development: Shows error message with file path
  • Production: Falls back to specified fallback fonts

Invalid Font Formats

  • Unsupported formats are ignored
  • Falls back to next format in the array or fallback fonts

Network Issues

  • Self-hosted fonts avoid external network dependencies
  • Files served from Next.js static assets

docs

google-fonts.md

index.md

local-fonts.md

tile.json