Configuration

Setting up the plugin

Vite

import { defineConfig } from 'vite';
import ecss from '@ecss/vite-plugin';

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

The plugin does not take options directly — everything is configured through the ecss.config.ts file.

ecss.config.ts

Create the file at the root of your project. The config must be exported via defineConfig:

Vite

import { defineConfig } from '@ecss/config';

export default defineConfig({
  enableDebug: true,
});

Supported formats: .ts, .js, .mts, .mjs, .cts, .cjs.

Options

generateDeclarations

generateDeclarations: boolean; // default: true

Generates .d.ts files in .ecss/types/ for each .ecss file. Add to tsconfig.json:

{
  "compilerOptions": {
    "rootDirs": ["./", "./.ecss/types"]
  }
}

enableDebug

enableDebug: boolean; // default: false

When true, @debug directives are compiled into console.log. When false, they are completely stripped from the bundle.

minifyNames

minifyNames: boolean; // default: false

When true, shortens the names of generated classes and attributes to short hashes. Recommended for production builds.

runtimeValidation

runtimeValidation: boolean; // default: false

When true, prints warnings to the console if invalid or missing parameters are passed. Useful during development.

aliases

aliases: Record<string, string>;

Path aliases for imports inside .ecss files:

aliases: {
  '#/*': './src/*',
}

globalImports

globalImports: string[]

Files automatically prepended to the start of every .ecss file. Convenient for global tokens:

globalImports: ['./src/tokens.ecss'],

adapters

adapters: EcssAdapter[]

The adapters used to generate framework components. You can register several — see Multiple adapters in one project.

defaultAdapter

defaultAdapter: string | null; // default: null

The adapter used by default when importing a .ecss file without a suffix. For example, 'react' activates React components without an explicit reference. For a non-default adapter, use the ?<id> suffix on import — see Multiple adapters.

Functional form

defineConfig accepts a function — the bundler passes it an object from which you can read information about the environment:

Vite

import { defineConfig } from '@ecss/config';

export default defineConfig(({ command, mode }) => ({
  enableDebug: command === 'serve',
  minifyNames: command === 'build',
  runtimeValidation: command === 'serve',
}));

See also

• @debug — the enableDebug option