Zero Config

PikaCSS is designed to work out of the box with sensible defaults — no configuration file is needed to get started. "Zero config" means you can install PikaCSS, add the build plugin, and immediately start writing styles with the pika() function. The engine, code generation, file scanning, and config file creation are all handled automatically.

What happens when the plugin starts

When the PikaCSS build plugin initializes, it automatically performs the following steps:

1. Config discovery — searches your project for an existing config file.
2. Auto-create config — if no config file is found, creates a pika.config.js with an empty config scaffold.
3. Engine initialization — creates the core engine with built-in plugins and default settings.
4. File scanning — scans your source files for pika() function calls.
5. Code generation — generates pika.gen.css (compiled atomic CSS) and pika.gen.ts (TypeScript autocomplete support).

All of these steps happen without any manual setup.

Config file discovery

PikaCSS searches your project for files matching the glob pattern:

**/{pika,pikacss}.config.{js,cjs,mjs,ts,cts,mts}

This means any of these file names are recognized: pika.config.js, pika.config.ts, pikacss.config.mjs, etc.

If no config file is found and autoCreateConfig is enabled (which it is by default), PikaCSS automatically creates a pika.config.js in your project root:

/// <reference path="./pika.gen.ts" />
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	// Add your PikaCSS engine config here
})

The /// <reference path="..." /> directive links to the generated TypeScript file so your editor can provide autocomplete inside the config.

Built-in plugins

Even with zero configuration, PikaCSS loads five built-in core plugins that power its fundamental features:

Plugin	Description
core:important	Handles !important modifier for styles
core:variables	CSS custom properties (variables) with unused pruning
core:keyframes	@keyframes animation definitions with unused pruning
core:selectors	Custom selector resolution (e.g., pseudo-classes, media queries)
core:shortcuts	Reusable style shortcut resolution

These plugins are always active — you do not need to add them to your config.

Default engine configuration

When no config file exists (or the config object is empty), the engine uses these defaults:

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

// These are the default values used by the engine when no config is provided.
// You do NOT need to specify any of these unless you want to override them.
export default defineEngineConfig({
	// Prefix prepended to all generated atomic class names.
	// e.g., prefix: 'pk-' would generate class names like 'pk-a', 'pk-b', ...
	prefix: '',

	// The CSS selector template for each atomic style.
	// '%' is replaced with the generated atomic style ID.
	defaultSelector: '.%',

	// Additional engine plugins (beyond built-in ones).
	plugins: [],

	// CSS preflights (global base styles injected before atomic styles).
	preflights: [],

	// Built-in plugin: controls whether all styles are !important by default.
	important: {
		default: false,
	},

	// Built-in plugin: CSS custom properties (variables) configuration.
	variables: {
		pruneUnused: true,
	},

	// Built-in plugin: @keyframes animation configuration.
	keyframes: {
		pruneUnused: true,
	},
})

Key points:

• prefix — Empty by default. Generated class names are short identifiers like a, b, c. Set a prefix (e.g., 'pk-') to namespace them.
• defaultSelector — .% turns each atomic style into a class selector where % is replaced by the style ID (e.g., .a { color: red }).
• plugins — Empty array. Built-in plugins are always loaded separately.
• preflights — No global base styles. Plugins like plugin-reset can add them.
• important.default — false. Styles are not !important unless explicitly specified.
• variables.pruneUnused / keyframes.pruneUnused — true. Unused variables and keyframes are removed from the final CSS output.

Default plugin options

The build plugin (e.g., for Vite) also has its own defaults:

import PikaCSS from '@pikacss/unplugin-pikacss/vite'

// These are the default plugin options.
// You do NOT need to specify any of these unless you want to override them.
PikaCSS({
	// Automatically creates a pika.config.js file if none is found.
	autoCreateConfig: true,

	// The function name used in source code to define styles.
	fnName: 'pika',

	// Format of transformed output: 'string' | 'array' | 'inline'
	transformedFormat: 'string',

	// TypeScript codegen file (provides autocomplete support).
	// true = 'pika.gen.ts', false = disabled, or a custom path string.
	tsCodegen: true, // generates 'pika.gen.ts'

	// CSS codegen file (contains the compiled atomic CSS).
	// true = 'pika.gen.css', or a custom path string.
	cssCodegen: true, // generates 'pika.gen.css'

	// File scanning patterns.
	scan: {
		include: ['**/*.{js,ts,jsx,tsx,vue}'],
		exclude: ['node_modules/**', 'dist/**'],
	},
})

Key points:

• autoCreateConfig — true. A config file is auto-created if none exists.
• fnName — 'pika'. This is the function name the plugin looks for in your source code.
• transformedFormat — 'string'. The pika() call is replaced with a space-separated string of class names at build time.
• tsCodegen — true. Generates pika.gen.ts for TypeScript autocomplete.
• cssCodegen — true. Generates pika.gen.css containing all compiled atomic styles.
• scan.include — Scans all js, ts, jsx, tsx, and vue files by default.
• scan.exclude — Excludes node_modules and dist directories.

Generated outputs

By default, PikaCSS generates two files in your project root:

• pika.gen.css — The compiled atomic CSS containing all styles found in your source files. Import this in your app entry via the virtual module pika.css.
• pika.gen.ts — A TypeScript declaration file that provides autocomplete support for the pika() function based on your configured selectors, shortcuts, and variables. This file uses declare global to register pika as a global function — you do not import pika from this file.

When to customize

You only need to create or edit a config file when you want to:

• Add a prefix to generated class names
• Define custom selectors (e.g., hover, responsive breakpoints)
• Create reusable shortcuts (e.g., flex-center)
• Declare CSS variables with theme support
• Add plugins (icons, reset, typography)
• Configure preflights (global base styles)
• Change codegen file paths

Here is an example of a customized config:

/// <reference path="./pika.gen.ts" />
import { defineEngineConfig } from '@pikacss/unplugin-pikacss'

export default defineEngineConfig({
	// Add a prefix to all generated class names
	prefix: 'pk-',

	// Custom selectors for responsive design
	selectors: {
		selectors: [
			['hover', '$:hover'],
			[/^screen-(\d+)$/, m => `@media (min-width: ${m[1]}px)`, ['screen-768', 'screen-1024']],
		],
	},

	// Reusable style shortcuts
	shortcuts: {
		shortcuts: [
			['flex-center', {
				display: 'flex',
				alignItems: 'center',
				justifyContent: 'center',
			}],
		],
	},

	// CSS custom properties
	variables: {
		variables: {
			'--color-primary': '#3b82f6',
			'--color-bg': '#ffffff',
		},
	},
})

Next

• Continue to First Pika