安裝與設定

一般 bundler 專案只需要安裝一個公開整合套件，設定對應 adapter，並讓 TypeScript 載入 PikaCSS 產生的 authoring state。

安裝

pnpmnpmyarn

pnpm add -D @pikacss/unplugin-pikacss

npm install -D @pikacss/unplugin-pikacss

yarn add -D @pikacss/unplugin-pikacss

一般 bundler 使用情境不需要另外安裝 @pikacss/core、@pikacss/config 或 @pikacss/integration。外層套件會重新匯出它承諾提供的 authoring helpers 與型別。

PikaCSS 需要 Node.js >=22。Vite adapter 支援 Vite 7 與 8。

套用 Vite plugin

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

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

公開 adapter options 刻意維持很小：config?: string 用來指定明確設定檔，cwd?: string 只在 host 沒有提供 root 時覆寫 project root。fnName、scan、output format 等語義都屬於 pika.config.*，不屬於 bundler options。

完整支援矩陣見 Bundler 整合。

pika 是編譯時期 global，不要 import

建置整合會在編譯時取代設定好的 Pika call。.pikacss/ 內產生的 TypeScript 宣告會提供 global callable 與 project-derived authoring surface。

匯入 logical CSS module

import 'pika.css'

pika.css 是預設的 logical CSS module。Adapter 會把它解析到目前 active generation 的 private runtime CSS。若設定了其他 cssModule，請匯入那個 logical module。

建立 project config

沒有設定檔也是合法狀態，等同預設 single-entry project。要明確建立 canonical config，可執行：

pikacss init

init 採保守策略：只有需要時才建立合適的 pika.config.*，並輸出 generated-state / type-project 接線建議，不會偷偷修改其他專案檔案。

基本設定如下：

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

export default defineConfig({
  engine: {
    // EngineConfig 放在這裡
  },
})

自動探索只檢查 project root 的四個候選：

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

找不到任何候選是合法的；同時存在多個則是錯誤。Adapter/CLI 的明確 config path 會改走 closed explicit selection，不再做 auto-discovery。

設定檔內相對的 filesystem path，例如 scan、stateDir 與 report output，都以選中的 config file 所在目錄為基準。

Generated state

PikaCSS 擁有一個完整 generated-state root，預設為：

text

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

pika.gen.ts 永遠屬於 generated state，沒有單獨停用或改位置的選項。若需要搬移，請在 defineConfig() 改整個 stateDir。

一般 TypeScript 專案需要讓 generated declaration進入 TypeScript program，例如：

json

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

或在已被 include 的 source 目錄放一個自己管理的 declaration：

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

在 editor、typecheck、ESLint 等獨立流程需要 generated authoring state 前，先執行：

pikacss prepare

自訂設定檔則可用：

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

prepare 會使用與 bundler 相同的 canonical config derivation，產生 Typegen 與 preview state，但不掃描 application usages，也不產生 production report。

Nuxt 等 framework integration可自行接管這段 type preparation wiring。

Generated state 要不要 commit？

Generated state 可重建，通常直接 ignore：

txt

# .gitignore
.pikacss/

若 CI 在 build 前就會跑 type-aware tooling，先執行 pikacss prepare。pika.config.* 本身是你的專案設定，應納入版本控制。

安裝與設定 ​

安裝 ​

套用 Vite plugin ​

匯入 logical CSS module ​

建立 project config ​

Generated state ​

Generated state 要不要 commit？ ​

下一步 ​