Config API reference

Source information

• Package: @pikacss/config
• Generated from the exported surface and JSDoc in packages/config/src/index.ts.
• Public entries: @pikacss/config, @pikacss/config/host
• Source files: packages/config/src/host-load.ts, packages/config/src/host-scan.ts, packages/config/src/host-types.ts, packages/config/src/host.ts, packages/config/src/index.ts, packages/config/src/types.ts

Package summary

Canonical project configuration and defineConfig authoring surface Re-exports the public surface of @pikacss/core.

Use Engine configuration when you need conceptual usage guidance instead of exact symbol lookup.

Functions

defineConfig

Defines one canonical PikaCSS project configuration.

Overload 1: defineConfig(config)

Parameter	Type	Description
config	SingleProjectConfig	Single-entry project settings, including the Engine configuration and project-owned runtime, scan, report, and generated-state options.

Returns: DefinedPikaConfig

Remarks:

The returned value is an opaque transport intended only as a config file default export. Do not inspect, spread, or mutate its runtime shape.

Overload 2: defineConfig(entries, options?)

Defines an explicit non-empty multi-entry PikaCSS project configuration.

Parameter	Type	Description
entries	readonly [ MultiProjectEntryConfig, ...MultiProjectEntryConfig[] ]	Ordered project entries. Every explicit entry owns its callable root and logical CSS module.
options?	MultiProjectConfigOptions	Project-wide generated-state options shared by all entries.

Returns: DefinedPikaConfig

Remarks:

Explicit multi-entry authoring remains distinct even when the array currently contains one entry; hosts must not infer single-entry CSS auto-import behavior from its length.

Types

DefinedPikaConfig

Opaque transport produced only by defineConfig.

MultiProjectConfigOptions

Project-wide options for the explicit multi-entry authoring form.

Property	Type	Description	Default
stateDir?	string	Directory shared by all entries for generated authoring state.	Host-provided default, otherwise .pikacss.

MultiProjectEntryConfig

One entry in the explicit multi-entry authoring form.

Property	Type	Description	Default
engine?	EngineConfig	Engine-specific configuration for this project entry.	{}
fnName	string	Required compile-time callable root used by this entry's source files.	—
cssModule	string	Required logical CSS module exposed by this entry's runtime stylesheet.	—
transformedFormat?	'string' | 'array'	Replacement shape emitted for the configured base callable.	'string'
scan?	ScanConfig	Source scan patterns owned by this entry.	Standard include and exclude patterns from DEFAULT_SCAN_INCLUDE and DEFAULT_SCAN_EXCLUDE.
report?	ReportConfig	Final production report behavior for this entry.	false

ReportConfig

Optional final production-build report configuration.

Type: boolean | Readonly<{ output: string; }>

ResolvedProjectConfig

Canonical project semantic state consumed by host/runtime layers.

Property	Type	Description	Default
authoringForm	'single' | 'multi'	Authoring form used to create this project configuration.	—
stateDir	string	Resolved project-wide directory for generated authoring state.	—
entries	readonly ResolvedProjectEntry[]	Normalized entries in their authored order.	—

ResolvedProjectEntry

One normalized semantic project entry.

Property	Type	Description	Default
engine	EngineConfig	Engine-specific configuration retained for this entry.	—
fnName	string	Validated compile-time callable root for this entry.	—
cssModule	string	Validated logical CSS module for this entry's runtime stylesheet.	—
transformedFormat	'string' | 'array'	Normalized replacement shape emitted for the base callable.	—
scan	ResolvedScanConfig	Resolved source scan patterns for this entry.	—
report	ResolvedReportConfig	Normalized final production report behavior for this entry.	—

ResolvedReportConfig

Normalized report behavior; false disables reporting.

Type: false | Readonly<{ output?: string; }>

ResolvedScanConfig

Fully normalized ordered scan pattern lists.

Property	Type	Description	Default
include	readonly string[]	Resolved include patterns used to select source files for scanning.	—
exclude	readonly string[]	Resolved exclude patterns applied after include matching.	—

ScanConfig

Ordered scan patterns owned by one project entry.

Property	Type	Description	Default
include?	string | readonly string[]	Source-file glob or globs to include in this entry's scan.	DEFAULT_SCAN_INCLUDE (all supported JavaScript, TypeScript, and Vue source files)
exclude?	string | readonly string[]	Source-file glob or globs to exclude after include matching.	node_modules/**, dist/**, .git/**, .nuxt/**, .output/**, and coverage/**

SingleProjectConfig

Single-entry authoring form accepted by defineConfig.

Property	Type	Description	Default
engine?	EngineConfig	Engine-specific configuration for this project entry.	{}
fnName?	string	Compile-time callable root used by this entry's source files.	'pika'
cssModule?	string	Logical CSS module exposed by this entry's runtime stylesheet.	'pika.css'
transformedFormat?	'string' | 'array'	Replacement shape emitted for the configured base callable.	'string'
scan?	ScanConfig	Source scan patterns owned by this entry.	Standard include and exclude patterns from DEFAULT_SCAN_INCLUDE and DEFAULT_SCAN_EXCLUDE.
report?	ReportConfig	Final production report behavior for this entry.	false
stateDir?	string	Project-wide directory for generated authoring state.	Host-provided default, otherwise .pikacss.

Public subpath: @pikacss/config/host

Import this entry as @pikacss/config/host.

ConfigHostDependencyTrace

Deterministic dependency trace for one config-load candidate.

Property	Type	Description	Default
selection	readonly ConfigHostFileDependency[]	Config-selection paths: all auto candidates or the exact explicit path.	—
modules	readonly ConfigHostFileDependency[]	Actually evaluated project-local config modules.	—
all	readonly ConfigHostFileDependency[]	De-duplicated selection + module dependencies.	—

ConfigHostFileDependency

File dependency emitted by the low-level Config host.

Property	Type	Description	Default
type	'file'	Dependency discriminator for filesystem-backed config inputs.	—
path	string	Absolute dependency path watched by the consuming host.	—

createPikaScanMatcher(options)

Creates the canonical source-membership matcher for one normalized entry.

Parameter	Type	Description
options	CreatePikaScanMatcherOptions	Normalized scan configuration and resolved state directory.
options.scan	ResolvedScanConfig	Normalized absolute include/exclude scan patterns.
options.stateDir	string	Resolved project state directory that is always excluded.

Returns: PikaScanMatcher

Remarks:

Inputs are the absolute scan patterns emitted by the Config host. The resolved state directory is excluded structurally before glob matching, even when an include pattern would otherwise match it.

CreatePikaScanMatcherOptions

Inputs for createPikaScanMatcher.

Property	Type	Description	Default
scan	ResolvedScanConfig	Normalized absolute include/exclude patterns for one scan entry.	—
stateDir	string	Resolved project state directory, always excluded regardless of globs.	—

LoadedPikaConfig

Canonically loaded and normalized PikaCSS project configuration.

Property	Type	Description	Default
projectRoot	string	Canonical absolute project root used for config selection and normalization.	—
selectedConfigPath	string | null	Selected config spelling, or null for the synthetic no-config default.	—
configDir	string	Filesystem base for authored relative config values.	—
config	ResolvedProjectConfig	Fully normalized project configuration returned to the host.	—
dependencies	ConfigHostDependencyTrace	Deterministic config-selection and evaluated-module dependency trace.	—

loadPikaConfig(options)

Selects, freshly evaluates, and canonically normalizes one PikaCSS project config.

Parameter	Type	Description
options	LoadPikaConfigOptions	Absolute project root plus optional explicit config selection and host state-directory default.

Returns: Promise<LoadedPikaConfig>

Remarks:

This is a low-level Node host API. It never creates Engines or owns generation/watch lifecycle. Selection and actually evaluated project-local module dependencies are returned for the caller to aggregate/watch.

LoadPikaConfigOptions

Low-level config selection input.

Property	Type	Description	Default
projectRoot	string	Immutable absolute project root chosen by the host.	—
config?	string	Closed explicit config-file selection. Omit for canonical auto-discovery.	—
defaultStateDir?	string	Resolved absolute host state-directory default used only when config omits stateDir.	—

PIKA_CONFIG_AUTO_CANDIDATES

Canonical config filenames checked, in order, during automatic project-config discovery.

PikaConfigHostError

Error from Config-host selection, evaluation, or normalization.

Constructors:

constructor(options)

Creates an error carrying the failed config-host operation and its dependency trace.

Parameter	Type	Description	Default
options	{ message: string; projectRoot: string; selectedConfigPath?: string | null; dependencies: ConfigHostDependencyTrace; cause?: unknown; }	Failed operation details and the dependencies observed before it failed.	—
options.message	string	Human-readable description of the config-host failure.	—
options.projectRoot	string	Absolute project root used for config selection.	—
options.selectedConfigPath?	string | null	Selected config path, or null when no config was selected.	null
options.dependencies	ConfigHostDependencyTrace	Config-selection and evaluated-module dependencies observed before the failure.	—
options.cause?	unknown	Underlying error, when one caused the failure.	—

Property	Type	Description	Default
projectRoot	string	Project root associated with the failed host operation.	—
selectedConfigPath	string | null	Selected config path when known, otherwise null.	—
dependencies	ConfigHostDependencyTrace	Dependency trace accumulated before the host operation failed.	—

PikaScanMatcher

Efficient matcher for one normalized entry scan.

Property	Type	Description	Default
matches	(filePath: string) => boolean	Returns whether one absolute physical source path belongs to the entry.	—

Next

• Engine configuration
• Integration API reference
• API reference overview