Set up Master CSS in Next.js
Guide to setting up Master CSS in your Next.js project.
Create a Next.js project
If you don't have a Next.js project, create one first. It's recommended to refer to Create Next App.
npx create-next-app@latest my-app --ts --app --no-tailwindcd my-appInstall Master CSS
Install Master CSS React and the Next.js adapter into your project via package managers.
npm i @master/css.react@rc @master/css.next@rcAuthor app CSS and manifest directives
Keep the normal app/globals.css import in the root layout. The same stylesheet imports Master CSS defaults, holds regular CSS, defines @settings and theme directives, and serves as the project CSS entry.
@import '@master/css';.native-card { border: 1px solid rgb(0 0 0 / 12%);}@components { hero-title { @compose m:0 font:5xl font:heavy text:neutral; }}Register the CSS runtime
Wrap the root layout with CSSRuntimeRegistry. The registry is a client component that loads the project-level manifest through the Next.js adapter. Progressive rendering hides development HTML until the runtime engine is ready.
import './globals.css'import { CSSRuntimeRegistry } from '@master/css.react'export const metadata = { title: 'Create Next App', description: 'Generated by create next app',}export default function RootLayout({ children }: { children: React.ReactNode }) { return ( <html lang="en" hidden={process.env.NODE_ENV === 'development'}> <body> <CSSRuntimeRegistry> {children} </CSSRuntimeRegistry> </body> </html> )}Set up Next.js adapter
Register the Master CSS Next.js adapter to pre-render CSS for build-time HTML outputs during next build.
This adapter uses the Next.js 16 Adapter API and runs in onBuildComplete. It pre-renders static and pre-rendered HTML outputs, while dynamic SSR responses continue to rely on the runtime engine.
Component CSS is generated when component classes are found in the built HTML or later observed by the runtime engine.
Static and pre-rendered outputs attach data-master-css-hydration-manifest to style#master-css. The JSON asset is written under /_next/static/master-css/hydration/…, while dynamic SSR responses continue to rely on runtime rendering.
import { withMasterCSS } from '@master/css.next'/** @type {import('next').NextConfig} */const nextConfig = withMasterCSS({ /* your Next.js config */})export default nextConfigLaunch server
Run npm run dev to start your Next.js development server. Development uses the runtime engine directly for fast refresh.
Pre-rendered <style id="master-css" data-master-css-hydration-manifest="…"> is generated by next build, so verify progressive output with npm run build && npm run start.
npm run devStart using Master CSS
Now style your first element using Master CSS syntax!
export default function Home() { return ( <h1 className="hero-title native-card m:2xl">Hello World</h1> )}Open your browser to watch the changes.