Integration API reference
Source information
- Package:
@pikacss/integration - Generated from the exported surface and JSDoc in
packages/integration/src/index.ts. - Source files:
packages/integration/src/ctx.ts,packages/integration/src/index.ts,packages/integration/src/types.ts
Package summary
Build-tool integration context Re-exports the public surface of @pikacss/core.
Use Unplugin integration when you need conceptual usage guidance instead of exact symbol lookup.
Functions
createCtx(options)
Creates an IntegrationContext that wires together config loading, engine initialization, source file transformation, and codegen output.
| Parameter | Type | Description |
|---|---|---|
options | IntegrationContextOptions | The integration configuration including paths, function name, scan globs, and codegen settings. |
Returns: IntegrationContext - A fully constructed IntegrationContext. Call setup() on the returned context before using transforms.
Remarks:
The context uses reactive signals internally so that computed paths (CSS and TS codegen file paths) automatically update when cwd changes. The setup() method must be called before any transform or codegen operations - transform calls automatically await the pending setup promise.
Types
FnUtils
Classifier and regex utilities for recognizing all pika() function call variants in source code.
| Property | Type | Description | Default |
|---|---|---|---|
isNormal | (fnName: string) => boolean | Returns true if the given function name is a normal call (output format determined by transformedFormat). | — |
isForceString | (fnName: string) => boolean | Returns true if the given function name forces string output (e.g., pika.str). | — |
isForceArray | (fnName: string) => boolean | Returns true if the given function name forces array output (e.g., pika.arr). | — |
isPreview | (fnName: string) => boolean | Returns true if the given function name is a preview variant (e.g., pikap, pikap.str). | — |
RE | RegExp | A compiled global regex that matches all recognized function call variants, including bracket-notation accessors. | — |
Remarks:
The function name is configurable via IntegrationContextOptions.fnName, so all variants (.str, .arr, preview p suffix, bracket notation) are derived dynamically from that base name.
IntegrationContext
The main build-tool integration context that bridges the PikaCSS engine with bundler plugins.
| Property | Type | Description | Default |
|---|---|---|---|
cwd | string | The current working directory. Can be updated at runtime (e.g., when the project root changes). | — |
currentPackageName | string | The npm package name of the integration consumer, used in generated file headers and module declarations. | — |
fnName | string | The base function name recognized in source transforms (e.g., 'pika'). | — |
transformedFormat | 'string' | 'array' | The default output format for normal pika() calls: 'string' or 'array'. | — |
cssCodegenFilepath | string | Absolute path to the generated CSS output file, computed from cwd and the configured relative path. | — |
tsCodegenFilepath | string | Nullish | Absolute path to the generated TypeScript declaration file, or null if TypeScript codegen is disabled. | — |
hasVue | boolean | Whether the vue package is installed in the project, used to include Vue-specific type declarations in codegen. | — |
resolvedConfig | EngineConfig | Nullish | The loaded engine configuration object, or null if loading failed or no config was found. | — |
resolvedConfigPath | string | Nullish | Absolute path to the resolved config file on disk, or null for inline configs or when no config was loaded. | — |
resolvedConfigContent | string | Nullish | Raw string content of the config file, or null for inline configs or when no config was loaded. | — |
loadConfig | () => Promise<LoadedConfigResult> | Loads (or reloads) the engine configuration from disk or inline source, updating resolvedConfig, resolvedConfigPath, and resolvedConfigContent. | — |
usages | Map<string, UsageRecord[]> | Map from source file ID to the list of UsageRecord entries extracted during transforms. Keyed by the file path relative to cwd. | — |
hooks | { styleUpdated: ReturnType<typeof createEventHook<void>> tsCodegenUpdated: ReturnType<typeof createEventHook<void>> } | Event hooks for notifying plugins when generated outputs need refreshing. styleUpdated fires on CSS changes; tsCodegenUpdated fires on TypeScript declaration changes. | — |
engine | Engine | The initialized PikaCSS engine instance. Throws if accessed before setup() completes. | — |
transformFilter | { include: string[] exclude: string[] } | Glob patterns for the bundler's transform pipeline, derived from the scan config with codegen files excluded. | — |
transform | (code: string, id: string) => Promise<{ code: string, map: SourceMap } | Nullish> | Processes a source file by extracting pika() calls, resolving them through the engine, and replacing them with computed output. Returns the transformed code and source map, or null if no calls were found. | — |
getCssCodegenContent | () => Promise<string | Nullish> | Generates the full CSS output string, including layer declarations, preflights, and all atomic styles collected from transforms. | — |
getTsCodegenContent | () => Promise<string | Nullish> | Generates the full TypeScript declaration content for pika.gen.ts, or null if TypeScript codegen is disabled. | — |
writeCssCodegenFile | () => Promise<void> | Generates and writes the CSS codegen file to disk at cssCodegenFilepath. | — |
writeTsCodegenFile | () => Promise<void> | Generates and writes the TypeScript codegen file to disk at tsCodegenFilepath. No-op if TypeScript codegen is disabled. | — |
fullyCssCodegen | () => Promise<void> | Scans all matching source files, collects usages via transform, then writes the CSS codegen file. Used for full rebuilds. | — |
setupPromise | Promise<void> | null | The pending setup promise while initialization is in progress, or null when idle. Transform calls await this before proceeding. | — |
setup | () => Promise<void> | Initializes (or reinitializes) the context by clearing state, loading config, creating the engine, and wiring up dev hooks. Returns a promise that resolves when setup is complete. | — |
Remarks:
Created via createCtx(). The context manages the full build lifecycle: config loading, engine initialization, source file transformation, usage tracking, and output file generation. All transform and codegen calls automatically await setup() completion before proceeding.
IntegrationContextOptions
Configuration options for creating an integration context.
| Property | Type | Description | Default |
|---|---|---|---|
cwd | string | The working directory used to resolve relative paths for config files, codegen outputs, and source scanning. | — |
currentPackageName | string | The npm package name of the integration consumer (e.g., '@pikacss/unplugin'), embedded in generated file headers and import paths. | — |
scan | { include: string[] exclude: string[] } | Glob patterns controlling which source files are scanned for pika() calls. include specifies files to process; exclude specifies files to skip. | — |
configOrPath | EngineConfig | string | Nullish | The engine configuration object, a path to a config file, or null/undefined to trigger auto-discovery of pika.config.* files. | — |
fnName | string | The base function name to recognize in source code (e.g., 'pika'). All variants (.str, .arr, preview) are derived from this name. | — |
transformedFormat | 'string' | 'array' | Controls the default output format of normal pika() calls: 'string' produces a space-joined class string, 'array' produces a string array. | — |
tsCodegen | false | string | Path to the generated TypeScript declaration file (pika.gen.ts), or false to disable TypeScript codegen entirely. | — |
cssCodegen | string | Path to the generated CSS output file (e.g., 'pika.gen.css'). | — |
autoCreateConfig | boolean | When true, automatically scaffolds a default pika.config.js file if no config file is found. | — |
Remarks:
These options are set by bundler plugin adapters (Vite, webpack, Nuxt) and are not typically configured by end users directly.
LoadedConfigResult
Discriminated union representing the outcome of loading an engine configuration file.
Remarks:
Three shapes are possible: an inline config (no file), a successfully loaded file-based config, or a failed/missing load (all fields null). The file and content fields are populated only when the config was loaded from disk, enabling hot-reload detection.
UsageRecord
Records a single pika() call result, pairing the resolved atomic style IDs with the original call arguments.
| Property | Type | Description | Default |
|---|---|---|---|
atomicStyleIds | string[] | The list of atomic CSS class names generated by the engine for this call. | — |
params | Parameters<Engine['use']> | The original arguments passed to engine.use(), preserved for TypeScript codegen overload generation. | — |
Remarks:
Each source file may produce multiple UsageRecord entries — one per pika() call site. These records drive both CSS output (via atomicStyleIds) and IDE preview overloads (via params).