Font Configuration

Customize your application's typography by configuring fonts in a single TypeScript file - the kit uses Next.js font optimization for automatic loading and performance.

The repo defines fonts in apps/web/lib/fonts.ts using Next.js's built-in font optimization. By default, it uses a small set of optimized fonts and CSS variables that you can swap or extend.

Font configuration in the kit uses Next.js's next/font module, which automatically optimizes font loading, eliminates layout shift, and self-hosts font files for privacy and performance.

Use Google Fonts when: you want easy setup with automatic optimization and a wide font selection.

Use self-hosted fonts when: you need custom fonts, Adobe Fonts, or have strict privacy requirements.

If unsure: start with Google Fonts - they're optimized out of the box and cover most use cases.

Font Configuration Location

Default Configuration

The kit ships with this font setup:

import { Inter as SansFont } from 'next/font/google';
const sans = SansFont({
  subsets: ['latin'],
  variable: '--font-sans-fallback',
  fallback: ['system-ui', 'Helvetica Neue', 'Helvetica', 'Arial'],
  preload: true,
  weight: ['300', '400', '500', '600', '700'],
});
const heading = sans;
export { sans, heading };

Key points:

• variable: Creates a CSS variable for Tailwind to use
• fallback: System fonts used while loading
• preload: Loads font immediately for above-fold content
• weight: Only loads specified weights (reduces bundle size)

Changing to a Different Google Font

Step 1: Update the Import

Edit apps/web/lib/fonts.ts:

import { Poppins as SansFont } from 'next/font/google';
const sans = SansFont({
  subsets: ['latin'],
  variable: '--font-sans-fallback',
  fallback: ['system-ui', 'Helvetica Neue', 'Helvetica', 'Arial'],
  preload: true,
  weight: ['400', '500', '600', '700'],
});

Browse available fonts at Google Fonts.

Step 2: Using Different Fonts for Headings

To use a display font for headings:

import { Inter as SansFont, Playfair_Display as HeadingFont } from 'next/font/google';
const sans = SansFont({
  subsets: ['latin'],
  variable: '--font-sans-fallback',
  fallback: ['system-ui', 'Helvetica'],
  preload: true,
  weight: ['400', '500', '600'],
});
const heading = HeadingFont({
  subsets: ['latin'],
  variable: '--font-heading',
  fallback: ['Georgia', 'serif'],
  preload: true,
  weight: ['400', '700'],
});
export { sans, heading };

Using Self-Hosted Fonts

For custom fonts or Adobe Fonts, use next/font/local:

import localFont from 'next/font/local';
const sans = localFont({
  src: [
    {
      path: '../public/fonts/CustomFont-Regular.woff2',
      weight: '400',
      style: 'normal',
    },
    {
      path: '../public/fonts/CustomFont-Medium.woff2',
      weight: '500',
      style: 'normal',
    },
    {
      path: '../public/fonts/CustomFont-Bold.woff2',
      weight: '700',
      style: 'normal',
    },
  ],
  variable: '--font-sans-fallback',
  fallback: ['system-ui', 'Helvetica'],
});

Place font files in public/fonts/ and use WOFF2 format for best compression.

Removing Apple System Font Priority

By default, the kit prioritizes Apple's system font on Apple devices. This is intentional: system fonts render sharper on Retina displays and eliminate the 100-200ms flash while Google Fonts load. If your audience is >50% non-Apple users, consider disabling this.

To use your custom font everywhere:

Edit apps/web/styles/shadcn-ui.css and find the --font-sans variable:

:root {
  /* Before: Apple fonts first */
  --font-sans: -apple-system, BlinkMacSystemFont, var(--font-sans-fallback), sans-serif;
  /* After: Your font first */
  --font-sans: var(--font-sans-fallback), system-ui, sans-serif;
}

Common Pitfalls

• Loading too many weights: Each weight adds to bundle size. Only include weights you actually use (typically 400, 500, 600, 700).
• Forgetting subsets: Always specify subsets: ['latin'] at minimum. Add others only if needed (e.g., latin-ext, cyrillic).
• Wrong font variable name: The CSS variable in fonts.ts must match what Tailwind expects (--font-sans-fallback).
• Not preloading: Set preload: true for fonts used above the fold to prevent flash of unstyled text.
• Large local font files: Use WOFF2 format and subset fonts to only include needed characters.

Related

• Branding Overview - Full branding customization guide
• Tailwind CSS Configuration - Theme and color customization
• Logo Configuration - Application logo and favicons

Back to: Branding Overview