@functionalcss/next

Official Next.js integration for FCSS — wraps your Next.js config with withFcss() to enable production CSS purging without hydration mismatches.

Installation

pnpm add @functionalcss/core @functionalcss/next

App Router

next.config.ts (Next.js 14, 15 and 16):

import { withFcss } from '@functionalcss/next';
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {};
export default withFcss(nextConfig);

app/layout.tsx:

import '@functionalcss/core/full.css';

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

Pages Router

pages/_app.tsx:

import '@functionalcss/core/full.css';
import type { AppProps } from 'next/app';

export default function App({ Component, pageProps }: AppProps) {
  return <Component {...pageProps} />;
}

Next.js 16: build with webpack

Next.js 16 builds with Turbopack by default. FCSS purges through webpack's asset pipeline, so build with the --webpack flag:

{
  "scripts": {
    "dev": "next dev",
    "build": "next build --webpack"
  }
}

next dev works as usual (Turbopack or webpack). A Turbopack production build stops with a clear error instead of shipping the full, unpurged stylesheet. Next.js 14 and 15 build with webpack already and need no flag.

Configuration

Create fcss.config.ts in your project root to customise scanning paths:

import type { FcssNextConfig } from '@functionalcss/next';

const config: FcssNextConfig = {
  content: ['app/**/*.{ts,tsx}', 'components/**/*.{ts,tsx}', '!node_modules/**'],
};

export default config;

Default content paths (used when no config file is found):

• app/**/*.{js,jsx,ts,tsx}
• pages/**/*.{js,jsx,ts,tsx}
• components/**/*.{js,jsx,ts,tsx}
• src/**/*.{js,jsx,ts,tsx}

Monorepo scanning

To scan components from a shared package in your monorepo, add the package path to content:

const config: FcssNextConfig = {
  content: ['app/**/*.{ts,tsx}', '../../packages/ui/src/**/*.{ts,tsx}', '!node_modules/**'],
};

CSS Modules

FCSS global utilities and CSS Modules coexist without conflict. Import @functionalcss/core/full.css once globally and use CSS Modules normally for component-scoped styles.

Notes

• withFcss() does not add 'use client' directives — FCSS classes are plain strings and work in Server Components without special handling.
• Production purging is CSS-only; no runtime JavaScript is added to the browser bundle.
• SSR and static generation are unaffected.