Setup

Install one public integration package, add its adapter to your build tool, and reference the generated PikaCSS authoring state from TypeScript.

Install

pnpm

pnpm add -D @pikacss/unplugin-pikacss

npm

npm install -D @pikacss/unplugin-pikacss

yarn

yarn add -D @pikacss/unplugin-pikacss

You do not need to install @pikacss/core, @pikacss/config, or @pikacss/integration separately for normal bundler usage. The outer package re-exports the authoring types/helpers it is designed to expose.

PikaCSS requires Node.js >=22.19.0. The Vite adapter supports Vite 7 and 8.

Apply the Vite plugin

setup.vite.example.ts

import PikaCSS from '@pikacss/unplugin-pikacss/vite'
import { defineConfig } from 'vite'

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

The public adapter options are deliberately narrow: config?: string selects an explicit config file and cwd?: string overrides the project root when the host does not supply one. PikaCSS semantics belong in pika.config.*, not in bundler options.

For the complete supported-host matrix, see Bundler integrations.

pika is a compile-time global — never import it

The build integration replaces configured Pika calls at build time. Generated TypeScript under .pikacss/ declares the callable global and its project-derived authoring surface.

Import the logical CSS module

setup.main.example.ts

import 'pika.css'

pika.css is the default logical CSS module. The adapter resolves it to the active generation's private runtime CSS file. If you configure another cssModule, import that logical module instead.

Create project config

No config file is required: absence of a config is equivalent to the default single-entry project. To create a canonical config explicitly, run:

pikacss init

init is conservative: it creates a suitable pika.config.* only when needed and prints the generated-state/type-project wiring you should add. It does not silently rewrite unrelated project files.

A basic project config is:

import { defineConfig } from '@pikacss/unplugin-pikacss'

export default defineConfig({
  engine: {
    // EngineConfig lives here.
  },
})

Automatic discovery checks exactly these project-root candidates:

• pika.config.ts
• pika.config.mts
• pika.config.js
• pika.config.mjs

Zero candidates is valid. More than one is an error. An explicit adapter/CLI config path uses closed explicit selection instead of auto-discovery.

Filesystem-relative values authored in a selected config, such as scan, stateDir, and report output paths, resolve from that config file's directory.

Generated state

PikaCSS owns one generated-state root. By default it is:

.pikacss/
├── pika.gen.ts
├── previews/
└── runs/

pika.gen.ts is always part of generated state. There is no per-Typegen enable/disable or output-path option. If the project needs another location, configure the whole stateDir in defineConfig().

For generic TypeScript projects, include the generated declaration in the TypeScript program. For example:

{
  "include": ["src", ".pikacss/pika.gen.ts"]
}

or add a user-owned declaration file under an already-included source directory:

/// <reference path="../.pikacss/pika.gen.ts" />

Before standalone editor/typecheck/ESLint workflows need generated authoring state, run:

pikacss prepare

For an explicit config path:

pikacss prepare --config ./config/pika.config.ts

prepare derives the same canonical project configuration as the bundler and publishes Typegen/preview state without scanning application usages or generating production reports.

Framework integrations may own this wiring themselves. In particular, the Nuxt module composes PikaCSS generation with Nuxt's type-preparation lifecycle.

Commit or ignore generated state?

Generated state is reproducible and normally ignored:

# .gitignore
.pikacss/

CI jobs that run type-aware tooling before a build should run pikacss prepare first. Keep pika.config.* itself in version control.

Next

• Usage — write styles with pika().
• Engine Config — understand project versus Engine configuration.
• ESLint Config — validate the same static Pika grammar before build.