Getting started

This guide adds Stillwind to a Vite application that uses React. At the end, a button uses Stillwind styles, and the CLI checks them. For another framework or build tool, follow the same steps and use the build setup from Framework integrations. To let a coding agent do the setup, see Coding agents.

Install the packages

vp i stillwind
vp i -D @stillwind/integration @stillwind/cli

npm install stillwind
npm install -D @stillwind/integration @stillwind/cli

pnpm add stillwind
pnpm add -D @stillwind/integration @stillwind/cli

yarn add stillwind
yarn add -D @stillwind/integration @stillwind/cli

bun add stillwind
bun add --dev @stillwind/integration @stillwind/cli

stillwind provides the style API. @stillwind/integration compiles your styles during development and builds. @stillwind/cli checks your styles from the command line.

Create a stylesheet

Create src/stillwind.css:

@import "stillwind";

@theme {
  --color-accent: oklch(0.6 0.2 250);
}

@import "stillwind" loads the default Tailwind CSS v4 theme and utilities. Each token in @theme adds utilities. For example, --color-accent adds bg-accent and text-accent.

Configure the project

Create stillwind.config.ts in the application root:

import { defineConfig } from "stillwind/config";

export default defineConfig({
  projects: [
    {
      css: "./src/stillwind.css",
      files: ["src/**/*.{ts,tsx,vue,svelte,astro}"],
    },
  ],
});

css selects the stylesheet. files selects the files that the CLI and the editor check.

Add Stillwind to vite.config.ts:

import { stillwind } from "@stillwind/integration/vite";
import react from "@vitejs/plugin-react";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [stillwind(), react()],
});

Place stillwind() before react(). Stillwind must compile styles before React compiles JSX. The plugin finds stillwind.config.ts in the application root.

Style a component

import { style } from "stillwind/react";

export function SaveButton({ loading }: { loading: boolean }) {
  return (
    <button
      disabled={loading}
      {...style(
        "rounded-md bg-accent px-4 py-2 text-white hover:opacity-90",
        loading && "opacity-60",
      )}
    >
      Save changes
    </button>
  );
}

style() returns props, such as className, so you spread the result onto the element. Each argument adds utilities. loading && "opacity-60" adds opacity-60 only while loading is true.

Start the development server. The button uses the accent color from your stylesheet. The build writes the CSS for these utilities to a static CSS file.

Check your styles

Change bg-accent to bg-acent, and run the CLI from the application root:

vp exec stillwind lint

npx stillwind lint

pnpm exec stillwind lint

yarn stillwind lint

bunx stillwind lint

The CLI reports bg-acent as an unknown utility. The build does not report this mistake: the misspelled utility produces no CSS, and the page still renders. Run the CLI in CI to catch such mistakes before you merge them.

Next steps

• Why Stillwind: what Stillwind checks and why
• The basics of style(): variants, conditions, and reusable styles
• Design systems: how to restrict colors, spacing, and breakpoints to your theme
• Checks in the editor and CI: how to run the checks in CI and the editor
• Editors: how to install the extension
• Formatters: how to sort utilities with your formatter

Set up with an AI agent

Coding agents gives a prompt that sets up Stillwind or migrates an existing project. The stillwind package includes this documentation and skills for the agent.