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

google-fonts.mddocs/

Google Fonts

Google Fonts integration providing access to 1625+ Google Font families with automatic optimization, self-hosting, and zero layout shift. Each font is available as a named export with full TypeScript support.

Capabilities

Font Functions

Every Google Font is available as a named export function. Font names are transformed from their Google Fonts names by replacing spaces and special characters with underscores.

/**
 * Generic Google Font function signature
 * @param options - Font configuration options
 * @returns Font object with className, style, and optional variable property
 */
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;

Popular Font Examples:

// Inter - Variable font
function Inter<T extends CssVariable | undefined = undefined>(options?: {
  weight?: 'variable' | '100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900' | Array<'100' | '200' | '300' | '400' | '500' | '600' | '700' | '800' | '900'>;
  style?: 'normal' | Array<'normal'>;
  display?: Display;
  variable?: T;
  preload?: boolean;
  fallback?: string[];
  adjustFontFallback?: boolean;
  subsets?: Array<'cyrillic' | 'cyrillic-ext' | 'greek' | 'greek-ext' | 'latin' | 'latin-ext' | 'vietnamese'>;
}): T extends undefined ? NextFont : NextFontWithVariable;

// Roboto - Standard weights
function Roboto<T extends CssVariable | undefined = undefined>(options: {
  weight: '100' | '300' | '400' | '500' | '700' | '900' | Array<'100' | '300' | '400' | '500' | '700' | '900'>;
  style?: 'normal' | 'italic' | Array<'normal' | 'italic'>;
  display?: Display;
  variable?: T;
  preload?: boolean;
  fallback?: string[];
  adjustFontFallback?: boolean;
  subsets?: Array<'cyrillic' | 'cyrillic-ext' | 'greek' | 'greek-ext' | 'latin' | 'latin-ext' | 'vietnamese'>;
}): T extends undefined ? NextFont : NextFontWithVariable;

// Open_Sans - Variable font with named instance weights
function Open_Sans<T extends CssVariable | undefined = undefined>(options?: {
  weight?: 'variable' | '300' | '400' | '500' | '600' | '700' | '800' | Array<'300' | '400' | '500' | '600' | '700' | '800'>;
  style?: 'normal' | 'italic' | Array<'normal' | 'italic'>;
  display?: Display;
  variable?: T;
  preload?: boolean;
  fallback?: string[];
  adjustFontFallback?: boolean;
  subsets?: Array<'cyrillic' | 'cyrillic-ext' | 'greek' | 'greek-ext' | 'hebrew' | 'latin' | 'latin-ext' | 'math' | 'symbols' | 'vietnamese'>;
}): T extends undefined ? NextFont : NextFontWithVariable;

Font Options

Weight Configuration

weight?: string | string[] | 'variable';
  • Single weight: '400', '700' - Loads specific font weight
  • Multiple weights: ['400', '700'] - Loads multiple weights
  • Variable fonts: 'variable' - Loads the variable font version if available
  • Required for some fonts: Fonts like Roboto require explicit weight specification

Style Configuration

style?: string | string[];
  • Single style: 'normal', 'italic' - Loads specific font style
  • Multiple styles: ['normal', 'italic'] - Loads multiple styles
  • Default: Most fonts default to 'normal' if not specified

Display Configuration

display?: Display;

Controls the CSS font-display property:

  • 'auto': Browser default behavior
  • 'block': Block rendering until font loads
  • 'swap': Use fallback immediately, swap when font loads (recommended)
  • 'fallback': Brief block period, then use fallback
  • 'optional': Use fallback if font doesn't load quickly

Variable Fonts

variable?: T;

Creates a CSS custom property for the font family:

const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
});

// Usage in CSS
// font-family: var(--font-inter);

Preloading

preload?: boolean;

Controls whether font files are preloaded:

  • true: Adds <link rel="preload"> for faster font loading
  • false: No preloading (default for non-critical fonts)

Subsets

subsets?: string[];

Specifies which font subsets to load. Common subsets include:

  • 'latin': Basic Latin characters (most common)
  • 'latin-ext': Extended Latin characters
  • 'cyrillic': Cyrillic script
  • 'greek': Greek script
  • 'vietnamese': Vietnamese characters

Fallback Fonts

fallback?: string[];
adjustFontFallback?: boolean;
  • fallback: Array of fallback font names
  • adjustFontFallback: Automatically calculate fallback font metrics to prevent layout shift

Usage Examples

Basic Google Font

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

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

export default function Page() {
  return (
    <div className={inter.className}>
      <p>This text uses Inter font</p>
    </div>
  );
}

Variable Font with CSS Variable

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

const inter = Inter({
  subsets: ['latin'],
  variable: '--font-inter',
});

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

Multiple Weights and Styles

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

const roboto = Roboto({
  weight: ['300', '400', '700'],
  style: ['normal', 'italic'],
  subsets: ['latin'],
  display: 'swap',
});

Custom Fallbacks

import { Playfair_Display } from "@next/font/google";

const playfair = Playfair_Display({
  weight: ['400', '700'],
  subsets: ['latin'],
  fallback: ['Georgia', 'serif'],
  adjustFontFallback: true,
});

Preloading Critical Fonts

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

const inter = Inter({
  subsets: ['latin'],
  preload: true, // Preload for above-the-fold content
});

Font Name Transformations

Google Font names are transformed for JavaScript compatibility:

  • Spaces to underscores: "Open Sans" → Open_Sans
  • Hyphens to underscores: "Source Sans Pro" → Source_Sans_Pro
  • Special characters removed: "Josefin Sans" → Josefin_Sans
  • Numbers preserved: "Roboto Mono" → Roboto_Mono

Available Fonts

The package includes 1625+ Google Fonts. Some popular examples:

Sans-serif Fonts

  • Inter - Modern variable font, excellent for UI
  • Roboto - Google's signature font
  • Open_Sans - Friendly, readable font
  • Lato - Humanist sans-serif
  • Montserrat - Geometric sans-serif

Serif Fonts

  • Playfair_Display - High-contrast serif
  • Merriweather - Designed for screens
  • Lora - Brush-style serif
  • Source_Serif_Pro - Adobe's serif font

Monospace Fonts

  • Fira_Code - With programming ligatures
  • Source_Code_Pro - Adobe's monospace font
  • JetBrains_Mono - Designed for developers
  • Roboto_Mono - Google's monospace font

Display Fonts

  • Oswald - Gothic-style display font
  • Bebas_Neue - Condensed display font
  • Righteous - Casual display font

Performance Considerations

  • Subset selection: Only include necessary language subsets
  • Weight optimization: Load only required font weights
  • Variable fonts: Use variable fonts when available for better performance
  • Preloading: Preload fonts used above the fold
  • Fallback adjustment: Enable automatic fallback metrics for better user experience

docs

google-fonts.md

index.md

local-fonts.md

tile.json