Set up Master CSS in Next.js

Guide to setting up Master CSS in your Next.js project.

Master CSS Progressive Rendering scans the rendered HTML ahead of time, server-side or at build time, generates the corresponding CSS rules for each page, and lazy loads the runtime engine to keep track of the dynamic class names.

Faster page loading

Non-rendering-blocking internal CSS and lazy loading

Fully automatic

Capture any program-generated class names

CSS encapsulation

Only ship the page-used CSS instead of the whole site

Quick start

Clone the example

Copy-paste the following commands to quickly start using the

You can skip all installation steps.

npx degit master-co/css/examples/next.js-with-progressive-rendering my-project
cd my-project
npm install @master/css.react@beta
npm install
npm run dev


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 --experimental-app --ts
cd project

Install Master CSS

Install Master CSS React into your project via package managers.

npm install @master/css.react@beta @master/css-renderer @master/css-server

Initialize configuration file

Run npx mcss init to create a configuration file master.css.ts.

npx mcss init

Set up CSS runtime engine

Register Master CSS with official CSSProvider and provide instance context.

  1. Use next/dynamic to load CSSProvider
  2. Dynamic import('../master.css')
  3. Add display: 'none' in <html> to avoid FOUC during development

@master/css.react and master.css.js will not be included in the page's initial JavaScript bundle.

import './globals.css'
import { CSSProvider } from '@master/css.react'
import config from '../master.css'
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" style={process.env.NODE_ENV === 'development' ? { display: 'none' } : undefined}>
<CSSProvider config={config}>

Set up Master CSS renderer

Statically generate CSS for each .html page after next build using the Master CSS Render CLI.

Next.js 13 has deprecated getInitialProps, and there is no alternative, so now only static output is supported.

"scripts": {
"dev": "next dev",
"build": "next build",
"build": "next build && mcss render \".next/**/*.html\"",
"start": "next start",
"lint": "next lint"

Launch server

Run npm run dev to start your Next.js development server

npm run dev

Start using Master CSS

Now style your first element using Master CSS syntax!

export default function Home() {
return (
<h1 className="font:40 font:heavy italic m:50 text:center">Hello World</h1>

Open your browser to watch the changes.


Hello World

MIT License © Aoyue Design LLC.