Installation

Install the package, then either let the installer wire everything up for you, or do it by hand if you want full control (or your setup is something the installer doesn't recognize).

1. Install from npm

npm install strata-css

2. Scaffold it automatically (recommended)

Strata ships an interactive installer that does almost everything below for you. Run it from your project root:

npx strata-css init

It detects your setup, then walks you through a few questions:

Framework — read straight from package.json: Next.js, Astro, Nuxt, SvelteKit, Laravel (via laravel-vite-plugin), React+Vite, Vue+Vite. Anything else falls back to a generic setup.
Module system (ESM vs CommonJS) and a sensible output path for your generated CSS — both inferred, not asked.
What to install — Strata core only, core plus some or all of the companion packages (modal, offcanvas, skeleton-loader, chart), or packages on their own.
Whether to auto-update your package.json scripts, and where your main layout file lives — it'll inject the <link> (and <script>, if you picked packages) tags for you.

From there it writes strata.config.js, postcss.config.js and strata.css, updates your scripts, patches your layout file, and runs the first build — all in one pass.

It never runs npm install for you

Since v1.4.10 the CLI contains zero child_process calls, as a deliberate supply-chain hardening measure — any package installs it decides you need are printed to the terminal for you to run yourself, never executed automatically.

That's the whole setup for most projects — you can skip straight to configuration from here. Everything below is what init does under the hood, broken down by framework, for setups it doesn't recognize or if you'd rather wire it up by hand.

3. Or wire it up by hand

Create a strata.css file (anywhere in your project — strata.config.js points at it) with the three Strata directives. Strata replaces these with generated CSS at build time — never hand-edit the output that replaces them:

@strata base;
@strata components;
@strata utilities;

Strata ships both a standalone CLI (strata-css --build / --watch) and a PostCSS plugin (require('strata-css')) you can drop into an existing pipeline. Which one applies depends entirely on your tooling — bundlers with their own PostCSS pipeline (Vite, Webpack) use the plugin directly; everything else runs the CLI as a build step.

4. Wire up your stack

Next.js's built-in PostCSS pipeline is meant for Tailwind-style plugins that hook into its own config format, not arbitrary third-party plugins — a custom postcssPlugin like Strata's doesn't reliably run through it, with or without Turbopack. The reliable path is running the CLI as an npm lifecycle hook, then importing the generated file like any other stylesheet. This is exactly how this documentation site itself is built.

1. Add the build hooks

Run the CLI before both next dev and next build, so the generated CSS is always fresh before Next.js starts:

{
  "scripts": {
    "predev": "strata-css --build",
    "prebuild": "strata-css --build",
    "dev": "next dev",
    "build": "next build"
  }
}

2. Point strata.config.js at an output path inside your project

module.exports = {
  content: ['./app/**/*.{js,jsx,ts,tsx}', './components/**/*.{js,jsx,ts,tsx}'],
  input:   './strata.css',
  output:  './styles/strata.output.css',
}

3. Import the generated file from your root layout

// app/layout.tsx
import "../styles/strata.output.css";

That's a static file import, not a directive — Next.js bundles it like any other CSS import. The @strata directives only exist inside strata.css, the input file the CLI reads, never in the file you import here.

4. Verify it's working

Run the build with --verbose to confirm the scan actually found your classes:

npx strata-css --build --verbose
# [Strata]   scanned 42/42 matched file(s), 0 skipped, 900 class name(s) found

Always use the npm script, never next build directly

Calling next build or next start without going through npm run build skips the prebuild hook — new classes you added will silently be missing from the compiled CSS, because the last-generated strata.output.css on disk is stale. If a class isn't showing up after you just added it, this is the first thing to check.

App Router or Pages Router — same wiring either way

Nothing here is Router-specific. On the Pages Router, import the generated file from pages/_app.tsx instead of app/layout.tsx — everything else is identical.

Vue, Nuxt, SvelteKit and Astro all sit on Vite under the hood, so the same PostCSS-plugin wiring works for every one of them — Strata runs as a live transform inside Vite's own dev server and build, with no separate CLI step and no watch process to keep running alongside it.

1. Create the entry CSS file and import it once

/* src/style.css */
@strata base;
@strata components;
@strata utilities;

// src/main.js (or main.ts)
import './style.css'

2. Register the plugin — plain Vite / Vue

// vite.config.js
import { defineConfig } from 'vite'

export default defineConfig({
  css: {
    postcss: {
      plugins: [require('strata-css')]
    }
  }
})

Nuxt

Nuxt exposes the same Vite config under a vite key in nuxt.config.ts:

// nuxt.config.ts
export default defineNuxtConfig({
  vite: {
    css: {
      postcss: {
        plugins: [require('strata-css')]
      }
    }
  }
})

Astro

Astro forwards a vite key from astro.config.mjs the same way:

// astro.config.mjs
import { defineConfig } from 'astro/config'

export default defineConfig({
  vite: {
    css: {
      postcss: {
        plugins: [require('strata-css')]
      }
    }
  }
})

SvelteKit

SvelteKit uses a standard vite.config.js at the project root — wire it exactly like the plain Vite example above.

Verify it's working

There's no CLI flag here — Strata reports through PostCSS's own warning system, which Vite prints straight to the terminal running dev or build. Watch for a [strata]-prefixed line if a class or content glob looks wrong.

Run Strata through postcss-loader in your CSS rule, with the plugin declared in a standalone postcss.config.js — Webpack applies loaders right-to-left, so postcss-loader must come after css-loader in the use array, exactly as below.

1. Create the entry CSS file and import it

/* src/style.css */
@strata base;
@strata components;
@strata utilities;

// src/index.js
import './style.css'

2. Wire the loader chain

// webpack.config.js
module.exports = {
  module: {
    rules: [{
      test: /\.css$/,
      use: ['style-loader', 'css-loader', 'postcss-loader']
    }]
  }
}

3. Register the plugin

// postcss.config.js
module.exports = {
  plugins: [require('strata-css')]
}

Verify it's working

Same as Vite — Strata surfaces problems as PostCSS warnings, which show up in Webpack's own compile output whenever you run webpack or webpack serve.

No bundler PostCSS pipeline to hook into — plain HTML, PHP/Laravel, Django/Rails, or any other backend-rendered stack. Run the CLI directly and link the generated file like any static stylesheet.

1. Build once, or watch while you work

npx strata-css --build

npx strata-css --watch

2. Link the output file

<link rel="stylesheet" href="/dist/strata.output.css">

3. Point content globs at your actual templates

The glob is the only filter — any extension it matches gets scanned, so Blade, Twig, ERB and Django templates all work without special-casing:

module.exports = {
  content: [
    './resources/views/**/*.blade.php', // Laravel
    './templates/**/*.{html,twig}',      // Django / Symfony
    './app/views/**/*.erb',              // Rails
  ],
  input:  './strata.css',
  output: './public/dist/strata.output.css',
}

Verify it's working

npx strata-css --build --verbose
# [Strata]   scanned 35/35 matched file(s), 0 skipped, 788 class name(s) found

For a deploy pipeline, run strata-css --build as its own step before your asset copy/publish step — treat it the same as any other CSS build command.

Next, set up your configuration so Strata knows exactly where to scan for class names.