Unplugin

PikaCSS uses unplugin as an adapter layer, but support is intentionally limited to the Rollup and Webpack families.

The Vite entry supports Vite 7 and 8 only.

Supported Tools

Family	Bundler	Import Path
Rollup	Vite	@pikacss/unplugin-pikacss/vite
Rollup	Rollup	@pikacss/unplugin-pikacss/rollup
Rollup	Rolldown	@pikacss/unplugin-pikacss/rolldown
Webpack	Webpack	@pikacss/unplugin-pikacss/webpack
Webpack	Rspack	@pikacss/unplugin-pikacss/rspack

Other Unplugin hosts, including esbuild, are outside the supported surface and have no public PikaCSS adapter entry point. Import an explicit supported bundler subpath rather than the package root when configuring a bundler plugin.

Example with Vite:

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

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

Vite plugin order

The Vite entry registers with enforce: 'pre'. PikaCSS still runs before framework compiler plugins even if your Vite plugins array is ordered as [vue(), pikacss()], so you do not need to reorder the array just to avoid template compile errors.

Config

The bundler adapter has only two bootstrap selectors. Source scanning, function roots, CSS-module names, transform format, generated-state placement, Engine behavior, and production reports belong to the canonical PikaCSS project config.

Property	Type	Description
cwd	string?	Optional project-root override. Normally the supported bundler supplies its resolved root/context.
config	string?	Optional explicit PikaCSS config file. Relative paths are resolved from the selected project root; when omitted, canonical project-root discovery is used.

See API Reference — Unplugin for exact type signatures.

Diagnostics and Reporting

Engine plugins can report diagnostics during transforms (for example, @pikacss/plugin-design-tokens strict mode). The engine never throws them — it hands each Diagnostic ({ level, code, message, plugin?, … }) to a handler. The unplugin installs that handler for you; there is no onDiagnostic plugin option to set.

How diagnostics surface

The built-in handler logs every diagnostic live, so a 'warning' appears immediately during dev and build. It also collects the 'error'-level diagnostics and, once every module has been transformed, throws a single aggregated Error at buildEnd listing them all — so an error-severity diagnostic fails a production build.

Why the build fails at buildEnd, not inline

Core delivers diagnostics through a handler whose throws are swallowed, so a handler cannot abort a single module's transform. Errors are therefore aggregated and thrown once at buildEnd. The trade-off: an error surfaces after the full build rather than inline on the producing module (with Vite's dev overlay). Warnings still log live on the module that produced them.

Production reports

Production reporting is configured per entry in the canonical PikaCSS project config, not as a bundler-plugin option. report: true enables the final summary for that entry; { output } additionally publishes its JSON report to the config-relative path.

// pika.config.ts
import { defineConfig } from '@pikacss/unplugin-pikacss'

export default defineConfig({
  report: { output: './design-tokens.report.json' },
})

The adapter only owns host lifecycle presentation. Reports finalize after a successful one-shot production build on supported Rollup-family and Webpack-family hosts; dev/watch lifecycles do not publish final reports. Report producer, serialization, directory, write, or atomic-replacement failures reject the production build.

CLI

A direct install of @pikacss/unplugin-pikacss provides the pikacss binary. The CLI is intentionally narrow:

pikacss init [--cwd <dir>]
pikacss prepare [--cwd <dir>] [--config <file>]

init creates only a canonical PikaCSS config when none exists and prints setup guidance; it does not modify package metadata, TypeScript config, or ignore files. prepare performs deterministic generated-state publication only. It does not source-scan, build runtime CSS, start watchers, or emit final production reports.

--cwd selects the host project root. --config is available to prepare as the same explicit closed config-file selector used by the bundler adapter.

TypeScript and logical CSS modules

In Vite projects, the ambient *.css module declaration from vite/client covers logical CSS-module specifiers such as the single-entry default pika.css. PikaCSS itself ships no ambient declaration for those specifiers, so TypeScript projects on other bundlers (Webpack, Rspack, Rollup, Rolldown) may report TS2307 for the configured cssModule. Add a shim for each logical module your application imports:

// pika-css.d.ts
declare module 'pika.css' // or your configured logical cssModule

Next

• Nuxt — zero-config Nuxt integration.
• Setup — basic project setup.