使わない CSS を消す（CSS Purge）

CSS Purge（パージ。「取りのぞく」という意味）は、ビルドしたあとのファイルを調べて、実際に使っている Lism のクラスだけを CSS に残すしくみです。本番で配る CSS が小さくなります。Vite・Astro 用のプラグインが、@lism-css/plugin パッケージに入っています。

どんなときに使う？#

• 本番の CSS ファイルを小さくして、ページを軽くしたいとき
• 全部入りの full.css を使いたいとき（CSS Purge と一緒に使う前提です）
• xs・xl のブレイクポイントを使えるようにして、CSS が大きくなったとき

入れ方（おすすめ）#

まずパッケージを入れます。

pnpm add -D @lism-css/plugin

統合プラグイン lismCss() を使っているなら、purge: true を渡すだけです。

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

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

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

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

true の代わりにオブジェクトを渡すと、オプション（下の「オプション」）も決められます。

lismCss({
  purge: {
    report: true, // 消す前と後の大きさをビルドのログに出す
    safelist: ['-p:30'], // 見つけられないクラスを残す
  },
});

しくみ#

1. ビルドで出てきた HTML・JS から、Lism の名前のルールに合うクラス名を集めます
2. CSS ファイルを読んで、集めたクラスに関係するセレクタ（CSS の当てる先）だけを残します

集める名前は、c--・a--・l--・is--・has--・set--・u-- で始まるクラスと、-prop:value の形の Property Class です。

• 名前のルールに合うセレクタを持たない CSS は、そのまま出ます
• 自分で作ったクラスや、ほかのライブラリの CSS には手を出しません
• :not()・:has() の中に書かれたクラスは、「使っている」には数えません
• [class*="-p:"] のような属性セレクタは、使っているクラスか safelist に合えば残ります

見つけられるもの・見つけられないもの#

React・Astro のコンポーネントは、動くときに Props をクラス名に変えます。たとえば <Box p="20"> は -p:20 を出しますが、ブラウザ用の JS には p: "20" しか残らないことがあります。Props の値が決まっていても、クラス名がまるごとビルドの結果に無ければ、その CSS は消されます。

たとえば <Box p={isOpen ? 20 : 40}> で、ビルドのときに 20 のほうだけが HTML に出たとします。ほかのどこにも -p:40 が書かれていなければ、-p:40 は消えます。こういうクラスは、下の safelist に全部書いて残します。書き出すのが難しいときは、CSS Purge を使わない（purge を書かないか false にする、単体のプラグインを外す）ことにします。

ビルドのときの警告#

次のときは、ビルドで警告が出ます。

• Astro 版：出た HTML に client:only の部分があるとき
• Vite 版：ブラウザ用の JS に Lism の動く部分が入っているのに、HTML から Lism のクラスが1つも見つからないとき

警告は、safelist を書いていても出ます。書いてあるだけでは、必要なクラスが全部守られているか分からないからです。

単体のプラグインを使う#

統合プラグインを使わず、CSS Purge だけのプラグインを入れることもできます。

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()],
});

SSR やハイブリッドの構成（output: 'server' か、prerender = false のページがある）では、dist/client/ に加えて dist/server/ も調べます。

full.css と一緒に使う#

lism-css/full.css は、main.css に無いブレイクポイントのクラスや色のトークンのクラスまで入った、全部入りの CSS です。そのままでは大きいので、CSS Purge と一緒に使う前提で配られています。

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

CSS Purge を入れて full.css に切り替えると、たくさんのクラスが使えるうえに、最後の CSS はサイトで使ったクラスだけになります。中身は CSS ファイルの種類 にあります。

オプション#

統合プラグインの purge にも、単体のプラグインにも、同じオプション（LismPurgeOptions）を渡せます。

safelist#

JS で組み立てるクラス名のように、ビルドの結果に文字として出ないクラスは見つけられません。消されないように、safelist に書きます。書き方は3種類あります。

lismPurge({
  safelist: [
    // 文字で、ぴったり同じもの
    '-p:30',
    // 正規表現に合うもの
    /^-bgc:/,
    // 関数で決める
    (className) => className.startsWith('-fz:'),
  ],
});

文字で書いたものは、属性セレクタ（[class*="..."] など）を残すかの判断にも使われます。正規表現や関数が1つでもあると、属性セレクタは比べられないので、使っているクラスや文字の項目に合わなかった属性セレクタも全部残ります。

report#

true にすると、ビルドのログにこんな行が出ます。

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

known#

Lism のクラスかどうかを決めるための一覧です。関数を渡すと、ビルドのときに呼ばれ、返した値が一覧になります。

main.css にあるセレクタは全部 full.css にもあります。だから main.css を読み込んでいても、見落とすクラスは出ません。

気をつけること#

• クラスを切りかえるときは、size === 'l' ? '-p:40' : '-p:30' のように、クラス名をまるごと書きます。`-p:${size}` や '-p:' + size のようにつなげて作ると見つけられません。難しいときは safelist に書きます
• 判断の単位はサイト全体です。あるページで使っていないクラスでも、別のページに1回でも出てくれば残ります。ページどうしで同じ CSS ファイルを使い回しても、見た目が崩れないようにするためです
• 書きかえるのは Lism が出した CSS だけです。自分の CSS やほかのライブラリの CSS はそのままです
• Tailwind CSS など、ほかのフレームワークの「使わないクラスを消す」機能とは別に動きます
• sourcemap（元のファイルとの対応表）は使えなくなります。ルールを消すと行の位置が合わなくなるので、CSS Purge は sourceMappingURL のコメントと古い .css.map を自分で消します。sourcemap が必要な作業では、CSS Purge を切ってください
• Vite 版の落とし穴：CSS Purge で CSS の名前（ハッシュ）は新しくなりますが、それを読む JS の名前は前のままです（JS の名前のほうが先に決まるため）。名前が同じならずっと使い回す CDN だと、古い JS が残り、もう無い CSS を探して 404 になることがあります。公開するたびに CDN のキャッシュを消せば防げます
• ファイル名の最後の区切りが、ちょうど 8 文字の英数字（<name>.xxxxxxxx.css、Vite 版は <name>-xxxxxxxx.css も）だと、ハッシュ付きの名前とみなされ、名前が付けかえられます。app-critical.css もこの形に当たります。CSS を決まった名前で外から読むなら、この形の名前を避けてください

関連するページ#

• カスタマイズの選び方
• lism.config.js で設定する
• CSS ファイルの種類