CSS Purge

Lism CSS のパージ機能は、ビルド成果物をスキャンして実際に使われている Lism CSS クラスだけを残す仕組みです。ビルド連携は @lism-css/plugin パッケージで提供しています。

pnpm add -D @lism-css/plugin

推奨セットアップ（統合プラグイン経由）

@lism-css/plugin の統合プラグインを使っている場合は、purge: true オプションを渡すだけで有効化できます。

import { defineConfig } from 'astro/config';
import { lismCss } from '@lism-css/plugin/astro';

export default defineConfig({
  integrations: [lismCss({ purge: true })],
});

import { defineConfig } from 'vite';
import { lismCss } from '@lism-css/plugin/vite';

export default defineConfig({
  plugins: [lismCss({ purge: true })],
});

オブジェクトで渡すと、purge プラグインの各オプションも指定できます。

lismCss({
  purge: {
    report: true, // ビルドログにパージ前後のサイズを出力
    safelist: ['-p:30'], // 静的解析で検出されないクラスを保持
  },
});

known（purge が対象とする既知の Lism クラス集合）を指定しない場合、ビルド開始時にconfig 反映済みの full.css から自動構築されます。これにより、lism.config.js で追加した prop / トークン由来クラスの未使用分まで正しく purge されます。known を明示した場合はそれを尊重します。

仕組み

ビルド時に出力された HTML / JS から、Lism CSS の命名規則（c-- / a-- / l-- / is-- / has-- / set-- / u-- プレフィックス、および -prop:value 形式のプロパティクラス）にマッチするクラス名を収集します。その後、CSS ファイルをパースして、使用されているクラスに紐づくセレクタのみを残します。

• 対象は Lism CSS が出力した CSS のみ（先頭シグネチャで判定）
• ユーザー定義のクラスや他ライブラリの CSS には触れない
• :not() / :has() 内のクラスは除外条件・子孫条件なので保持判定の対象外
• [class*="-p:"] のような属性セレクタも、使用クラスや safelist との照合で過不足なく保持

単体プラグインを直接使う場合

統合プラグインを使わずに単体プラグインを直接登録することもできます。

import { defineConfig } from 'vite';
import { lismPurge } from '@lism-css/plugin/purge/vite';

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

import { defineConfig } from 'astro/config';
import { lismPurgeAstro } from '@lism-css/plugin/purge/astro';

export default defineConfig({
  integrations: [lismPurgeAstro()],
});

Vite プラグインは apply: 'build' / enforce: 'post' で動作するため、開発サーバー (vite dev) では何も実行されません。vite build 実行時のみ、生成された CSS から未使用セレクタが削除されます。Astro 用は astro:build:done フックで、ビルド出力配下の HTML / JS をスキャンし、CSS ファイルを書き換えます。

SSR / hybrid 構成（output: 'server'、または prerender = false のルートがある場合）では、client 出力（dist/client/）に加えて server 出力（dist/server/）もスキャンと参照書き換えの対象になります。これにより、オンデマンドレンダリングされるページだけで使われているクラスも正しく保持されます。

full.css と組み合わせる

lism-css/full.css は、変数出力専用（isVar 系）を除く全 Property Class のブレイクポイント対応クラス（sm / md / lg）と、スペーシング系プロパティの SPACE トークンユーティリティまで含めた全部入りビルドです。素のまま読み込むとサイズが大きいため、purge との併用を前提にした配布物です。

// main.css の代わりに full.css を読み込む
import 'lism-css/full.css';

purge のデフォルトの既知の Lism クラス集合（known）は full.css 由来になっています。full.css は main.css のセレクタのスーパーセットなので、main.css / full.css のどちらを読み込んでいても、未使用クラスを取りこぼさず正しく削除できます。

purge を有効にしたうえで full.css に切り替えると、main.css には含まれないトークンクラスや拡張ブレイクポイントが使えるようになり、かつ最終的な CSS はサイト全体で実際に使われているクラスだけに絞り込まれます。

オプション

両プラグインとも、共通の LismPurgeOptions を受け取ります。

| オプション | 説明 | |---|---| | safelist | 静的解析で検出されないクラスを保持リストに追加 | | report | ビルドログにパージ前後のファイルサイズを出力 | | known | 既知の Lism クラス集合をカスタマイズ。関数を渡すとビルド時に遅延評価される。未指定時は full.css 由来の集合を使う（通常は指定不要） |

safelist

JS で動的に組み立てるクラス名など、ビルド成果物に文字列として現れないクラスは静的解析で検出できません。誤って削除されるのを防ぐには safelist に追加します。

lismPurge({
  safelist: [
    // 文字列で完全一致
    '-p:30',
    // 正規表現でマッチ
    /^-bgc:/,
    // 関数で判定
    (className) => className.startsWith('-fz:'),
  ],
});

string エントリは属性セレクタ（[class*="..."] など）の照合にも使われます。RegExp / 関数は具体的なクラス名を列挙できないため、属性セレクタは保守的に残されます。

report

true にすると、パージ前後の合計バイト数と削減率がビルドログに出力されます。

CSS: 28100 → 13200 bytes (-14900 / -53.0%)

注意事項

• 動的にクラスを組み立てる場合は、必ず完全なクラス名（`-p:${size}` など部分文字列にしない）を残すか、safelist に追加してください。
• パージはビルド出力全体で使われているクラスの和集合を残します（ページ単位ではありません）。あるページで使っていなくても、サイト内のどこかのページで使われていれば保持されます。これは複数ページで共有される CSS を壊さないための挙動です。
• パージ対象は Lism CSS が出力した CSS に限定されます。自前で書いた CSS や他ライブラリの CSS は変更されません。
• Tailwind CSS など、別のフレームワークの purge 機能とは独立して動作します。
• CSSのsourcemapには対応していません。パージはルールを削除するため、既存のsourcemapとは行がずれます。誤ったsourcemapを参照しないよう、purge後のCSSからsourceMappingURLコメントを削除し、古い.css.mapも削除します。CSSのsourcemapが必要な場合はパージを無効にしてください。
• Vite 版では、パージによって CSS ファイル名（内容ハッシュ）が変わっても、その CSS を参照する JS チャンク自体のファイル名は再計算されません（チャンク名はパージ処理より前に確定しているためです）。チャンクの中身は新しい CSS 名に書き換えられますが、ファイル名は変わらないため、ファイル名ベースの immutable キャッシュを行う CDN 等では、過去のデプロイでキャッシュされた古いチャンクが配信され続けると、存在しない旧 CSS 名を参照して 404 になる可能性があります。該当する環境では、デプロイ時に CDN のキャッシュを無効化してください。
• パージ対象の CSS は、ファイル名の末尾セグメントがちょうど 8 文字の英数字の場合（<name>.xxxxxxxx.css、Vite 版では <name>-xxxxxxxx.css も対象）にハッシュ付きファイル名とみなされ、パージ後の内容に基づくハッシュへリネームされます。app-critical.css のようにハッシュではない名前もこのパターンに一致するため、ビルド出力の CSS を外部から固定ファイル名で直接参照する場合は、末尾セグメントがちょうど 8 文字の英数字になる名前を避けてください。