Configuration

stillwind.config.ts describes your projects. The build integration, the CLI, and the editor all read the same file.

import { defineConfig } from "stillwind/config";

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

Each entry in projects selects a stylesheet and the files that belong to it. Most applications need one project. A monorepo can list one project for each application, or keep a configuration file in each package and reference those files.

Reference other configuration files

A string in projects references other configuration files, relative to the file that declares it. Strings and project objects can appear in the same list.

import { defineConfig } from "stillwind/config";

export default defineConfig({
  projects: ["apps/*", "!apps/legacy", "packages/ui", "tools/site.stillwind.ts"],
});

A path or a directory that is missing causes an error. A glob skips directories that have no configuration file, and it does not search node_modules or .git. Stillwind reports an error only when no project remains in the list.

A relative root in a referenced file uses the directory of that file, so packages keep working on their own. Referenced files must list project objects because references do not nest. Project names must be unique across all files.

Build tools watch the referenced files, but they do not notice a new file that a glob would match. Restart the build after you add a package.

Where Stillwind finds the file

The build integration searches from the application root upward. The CLI and the editor search from the working directory or the workspace upward. The file in the nearest directory wins.

The editor also searches from each file that you open. A monorepo therefore works without a configuration file at its root: when no open project includes the file, the editor uses the nearest configuration file inside the workspace. Setting an explicit configuration file turns this search off.

Stillwind accepts stillwind.config.ts, .mts, .cts, .js, .mjs, .cjs, and .json. In one directory, it uses the first of these that exists.

defineConfig() also accepts a function or an async function that returns the settings. Stillwind calls it once and uses the result.

Project fields

Required

Scope

Paths in css, files, exclude, and tsconfig are relative to root.

Checks and sorting

Generated CSS

Generated names

Editor

The shared configuration API describes the remaining fields for custom integrations, such as sources, projection, typeFacts, and automatic.

Lint

The lint field of a project selects the rules that the CLI and the editor report. Checks in the editor and CI explains where the rules run.

Presets and severities

import { defineConfig, lintPresets } from "stillwind/config";

export default defineConfig({
  projects: [
    {
      css: "./src/stillwind.css",
      files: ["src/**/*.{ts,tsx,vue,svelte,astro}"],
      lint: {
        extends: [lintPresets.recommended, lintPresets.stylistic],
        rules: {
          "unknown-utility": "deny",
          "no-arbitrary-colors": "warn",
        },
      },
    },
  ],
});

The lint rule reference shows the severity of each rule in recommended. Each rule page shows its severity in every preset.

Each rule has one of three severities:

How the settings combine

Stillwind applies the presets in extends in order, and then rules. A later setting replaces the severity of an earlier one. Options in objects merge, and arrays replace earlier arrays. A severity alone, such as "deny", keeps the rule’s options from the presets.

An unknown rule name is a configuration error. Turning off rules does not turn off compiler errors.

Rule options

Some rules accept options. Write the rule as an object with severity and the options:

const rules = {
  "no-restricted-utilities": {
    severity: "deny",
    utilities: [{ pattern: "absolute", message: "Use the positioned component." }],
  },
  "no-restricted-declarations": {
    severity: "deny",
    rules: [{ properties: ["position"], values: ["absolute"] }],
  },
  "no-restricted-length-units": {
    severity: "warn",
    rules: [{ properties: ["width", "height"], disallow: ["px"] }],
  },
  "no-restricted-theme-tokens": {
    severity: "deny",
    tokens: ["--color-blue-*"],
  },
};

Patterns accept * for any text and ? for one character. Utility and theme token patterns are case-sensitive. Property and value patterns are not.

Definitions of packages and plugins

incompatible-property-value checks the declarations that utility definitions write. By default, it checks only your own definitions: your stylesheet, the stylesheets that it imports by a relative or absolute path, and the plugin files that it loads by path. Two project-level fields of lint add the definitions of packages and plugins. Presets cannot set them.

lint: {
  extends: [lintPresets.recommended],
  checkLibraries: ["@acme/*"],
  checkPlugins: ["brand"],
}

Each field accepts true for every package or plugin, false for none, or a list of case-sensitive patterns. Both fields default to false. Use them to check a package of your own, such as a design system in the same repository, or to find problems to report upstream.

Suppression comments

To allow one exception, add a comment that names the rule. Give the reason after --:

import { style } from "stillwind/react";

// swlint-disable-next-line no-arbitrary-colors -- External brand color.
export const badge = style("bg-[#123456]");

In stylesheets, write the same text in /* ... */ comments.

A comment hides the finding only. A misspelled utility still produces no CSS. invalid-lint-suppression reports a malformed comment, and unused-lint-suppression reports a comment that suppresses nothing.

Sorting

The sort field controls where stillwind fmt, the editor, and the Prettier plugin sort utilities:

sort: false disables sorting, including stillwind fmt and the prefer-sorted-utilities rule. Turning off only that rule keeps stillwind fmt working.

The CLI checks the files that files selects. File patterns on the command line narrow that set; they cannot add files outside it.

Several projects

When the file has several projects, each integration selects one:

1. If the integration has a project option, it selects the project with that name.
2. Otherwise, it selects the project whose root is the deepest directory that contains the application root.

If no project or more than one project matches, the build fails with a configuration error. The CLI and the editor check every project.

Override settings in the integration

The integration accepts options that change how it reads the file:

import { stillwind } from "@stillwind/integration/vite";

stillwind({ configFile: "config/stillwind.config.ts", project: "web" });

configFile selects another file, relative to the application root. Other options, such as css or lint, replace the values of the selected project. Objects merge with the file’s values, and arrays replace them.