FAQ

PikaCSS 的常見問題與解決方法。

為什麼我的樣式沒有出現？

請確認你的應用程式進入點有匯入產生出來的 CSS 模組：

// main.ts
import 'pika.css'

import 'pika.css' 是預設 single-entry 的 logical CSS module。Adapter 會把它解析到 active run 位於 <stateDir>/runs/... 的 private runtime CSS；stateDir 可以在 project config 中設定，但 runtime CSS 沒有獨立的 output-path 選項。每個 dev server 或 build invocation 都擁有自己的 private artifact。

使用 Nuxt single-entry authoring 時，module 會自動注入唯一的 logical CSS-module import。Explicit multi-entry authoring 不會猜測全域 stylesheet。若使用一般 unplugin integration，請在需要各 entry 樣式的地方明確匯入對應 logical cssModule，並確認 build config 已註冊 plugin。

ReferenceError: pika is not defined

這個執行階段錯誤代表有個 pika() 呼叫沒有經過轉換就到了瀏覽器：pika 只存在於編譯時期，並沒有任何執行階段的匯出。最常見的原因是 scan glob 沒有比對到這個檔案，所以外掛從未處理它。預設的 scan.include 是 **/*.{js,mjs,cjs,jsx,ts,mts,cts,tsx,vue}，而預設的 scan.exclude 會略過 node_modules、dist、.git、.nuxt、.output，以及 coverage。

修正方式：

1. 如果你設定了自訂的 scan.include，請確認它仍然能比對到該檔案：自訂值會原封不動地取代預設值，而不是加以擴充。預設的 glob 已經涵蓋轉換所支援的每一種副檔名（JS 家族加上 Vue SFC），其他副檔名即使加進去也無法轉換。
2. 檢查該檔案是否位於被排除的路徑底下（node_modules、dist、.git、.nuxt、.output、coverage）。如果你設定了自訂的 scan.exclude，請確認它不會不小心比對到該檔案。
3. 確認 PikaCSS 外掛確實已在你的建置設定中註冊。

Cannot find name 'pika'

這個 TypeScript 錯誤代表 <stateDir>/pika.gen.ts 尚未產生，或沒有被納入 TypeScript program。獨立執行 editor/typecheck/ESLint 前先跑 pikacss prepare，再把 .pikacss/pika.gen.ts（或你設定的 stateDir）納入 TypeScript project。

Typegen永遠屬於整個 PikaCSS generated state，不能單獨搬移或停用。見 Generated state。

為什麼 static-usage 會回報 ESLint 錯誤？

pikacss/static-usage 會讀取 canonical project config，檢查 configured roots 的 bounded-static argument grammar、static-extension語法、scan ownership，以及跨 entry root dependency。若同名 root在 lexical scope中被本地宣告遮蔽，就會當成一般 application code。

Runtime value請拆成不同的合法 pika() call，再由一般 JavaScript決定使用哪一個結果：

// ❌ 無效：runtime conditional直接出現在 Pika argument
pika(isDark ? { color: 'white' } : { color: 'black' })

// ✅ 有效：分開產生靜態 class
const className = isDark
  ? pika({ color: 'white' })
  : pika({ color: 'black' })

我要怎麼改變 layer 順序？

在你的引擎設定裡定義一個自訂的 layers map。數字越小，越早渲染：

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

export default defineConfig({
  engine: {
  layers: {
    reset: -1,
    preflights: 1,
    components: 5,
    utilities: 10,
  },
  },
})

完整範例請見 Layers。

我可以不用建置外掛就使用 PikaCSS 嗎？

可以。@pikacss/core 不需要打包工具的外掛也能運作。建立一個引擎，用 await engine.use(...) 註冊樣式，接著從 layer 宣告、preflight，以及原子樣式組合出 CSS 輸出：

import { createEngine, defineEngineConfig } from '@pikacss/core'

const engine = await createEngine(defineEngineConfig({}))
const atomicStyleIds = await engine.use({ color: 'red' })

const css = [
	engine.renderLayerOrderDeclaration(),
	await engine.renderPreflights(true),
	await engine.renderAtomicStyles(true, { atomicStyleIds }),
]
	.filter(Boolean)
	.join('\n\n')

unplugin integration 會加上 HMR 與靜態擷取，但不是 Core 使用的必要條件。Nuxt single-entry authoring 會自動匯入唯一 configured logical cssModule；explicit multi-entry 不會。一般 unplugin integration 則由應用程式明確匯入各 owning entry 的 logical cssModule（single-entry 預設為 pika.css）。

我要如何加入自訂的偽類（pseudo-class）或斷點？

使用 selectors 設定屬性來註冊自訂選擇器，包含偽類與媒體查詢的 RWD 斷點：

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

export default defineConfig({
  engine: {
  selectors: {
    definitions: [
      { name: '@dark', value: 'html.dark $' },
      { name: '@sm', value: '@media (min-width: 640px)' },
    ],
  },
  },
})

請見 選擇器。

TypeScript 找不到外掛的模組擴增

請確認外掛套件已安裝，而且你的 tsconfig.json 使用了現代的模組解析模式，例如 moduleResolution: 'bundler' 或 'node16'，這樣 TypeScript 才能沿著外掛套件的 export map 找到它的宣告檔，以及 @pikacss/core 的模組擴增：

{
  "compilerOptions": {
    "moduleResolution": "bundler"
  }
}

開發時樣式沒有更新（HMR）

PikaCSS 的 Vite 外掛會自動處理 HMR。如果樣式沒有更新：

1. 確認外掛已用 PikaCSS() 在 vite.config.ts 中註冊。
2. 檢查需要樣式的地方有匯入 owning entry 設定的 logical cssModule（single-entry 預設為 import 'pika.css'）。
3. 變更 pika.config.ts 應該會自動觸發設定重新載入。如果沒有，請確認你編輯的是解析後的設定檔路徑，而且存檔的內容確實有變更。

我要如何有條件地組合 PikaCSS class？

預設情況下，轉換後的 pika() 呼叫會產生一個單純的 class 名稱字串，所以標準的 JavaScript 組合方式都能運作：

const base = pika({ display: 'flex', padding: '1rem' })
const active = pika({ color: 'blue' })
const inactive = pika({ color: 'gray' })

const className = `${base} ${isActive ? active : inactive}`

若 owning project entry設定 transformedFormat: 'array'，configured base pika() 就會回傳陣列。沒有 per-call .arr() override；請直接用 framework慣用的 array class handling組合結果。

PikaCSS 能搭配 SSR／SSG 運作嗎？

可以。樣式會在 build time 擷取成靜態 runtime CSS artifacts，而且每次 pika() 呼叫都會替換成單純的 class-name 資料，完全沒有 runtime style injection。每個 project entry 擁有自己的 logical cssModule，所以 explicit multi-entry project 可以產生多份獨立匯入的 stylesheet。SSR、SSG 與 streaming 不需要 PikaCSS 特有處理，只要正常提供這些 CSS imports。Nuxt module 會註冊 Vite adapter，並且只在 single-entry authoring 時透過 generated Nuxt plugin 匯入唯一 logical CSS module。

我應該提交產生的檔案嗎？

整個 .pikacss/ generated-state directory都可以重建，通常直接 ignore。若 CI 在 build前就跑 type-aware tooling，先執行 pikacss prepare 產生 .pikacss/pika.gen.ts。見 Generated state。

下一步

• 快速開始：從頭開始。
• API 參考：完整的 API 細節。