クライアントサイドレンダリング

EffCSSは、特別な設定なしでクライアントサイドで既に動作しています。しかし、サーバーサイドレンダリングで一般的に使用されるスタイルハイドレーション機構は、vite-plugin-effcssを使用することでクライアントサイドレンダリング（CSR）でも利用できます。

このプラグインは、Vite SSRパイプラインを介してEffCSSで生成されたCSSを取得し、HTMLにインライン化します。これにより、スタイルハイドレーションによってFOUC（First Object Unlimited Content：最初のレンダリングエラー）を解消し、初回レンダリングを高速化できます。開発モードとビルドモードの両方で動作し、追加の依存関係は一切不要です（esbuild、tsx、その他のローダーは不要）。

設定不要 — オプションは一切必要ありません。プラグイン配列に追加するだけです。

CSR重視 — SSR/SSGの場合は、serialize()とserializeMeta()を手動で使用してください。詳細はサーバーサイドレンダリングを参照してください。.

プラグインの使用方法

まず、プロジェクトにプラグインをインストールする必要があります。

bash

npm install vite-plugin-effcss --save-dev

EffCSSはピア依存関係として宣言されています。プロジェクトにインストールされていることを確認してください。
bash
npm install effcss

次に、それをViteの設定ファイルに追加します。

// vite.config.ts
import { defineConfig } from 'vite';
import react from '@vitejs/plugin-react';
import effcss from 'vite-plugin-effcss';

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

HTMLにプレースホルダーを追加します（オプション - </head>にフォールバックします）：

html

<head>
  <!-- EFFCSS_INJECT -->
</head>

以上です。このプラグインは、EffCSSで生成されたすべてのCSSをキャプチャし、HTMLにインライン化します。

ただし、このプラグインはprefix、minify、その他のEffCSS設定を管理しません。これらの設定は、configure()を使用してソースコード内で個別に設定する必要があります。

// src/effcss-config.ts
import { configure } from 'effcss';

configure({
  prefix: 'my',
  minify: true,
});

オプション

このプラグインは以下のオプションをサポートしています。

Option	Type	Default	Description
`verbose`	`boolean`	`false`	詳細ログ
`entry`	`string`	—	明示的なエントリポイント（例：`/src/main.tsx`）。省略した場合、`index.html`内の`<script type="module" src="...">`から自動検出されます。
`placeholder`	`string`	`'<!-- EFFCSS_INJECT -->'`	`<style>`に置き換えるHTMLプレースホルダー
`injectTo`	`'head' \| 'head-prepend' \| 'body'`	`'head'`	プレースホルダーが見つからない場合のフォールバック挿入位置
`injectMeta`	`boolean`	`true`	JSONメタデータを含む`<script>`として`serializeMeta()`を挿入します。

仕組み

                    buildStart()
                          │
                 ┌─────────┴─────────┐
                 │                   │
                 ▼                   ▼
           Server exists?      Server null?
           (dev mode)          (build mode)
                 │                   │
                 ▼                   ▼
      write tmp .ts file     createServer() + virtual module
      → ssrLoadModule        → ssrLoadModule('effcss:capture')
                 │                   │
                 └───────┬───────────┘
                         ▼
               mod.css + mod.meta
                         │
                         ▼
               transformIndexHtml
               → inject <style> + <script>

このプラグインは、以下の処理を行うキャプチャモジュールを作成します。

EffCSSをインポート（serialize() / serializeMeta()にアクセスするため）
エントリポイントをインポート（スタイルの実行と登録のため）
serialize()を呼び出す（最終的なCSSとメタデータを文字列としてキャプチャ）
結果をtransformIndexHtmlを介してHTMLにインラインする

開発モード：既存のViteDevServerを一時的な.tsファイルとともに使用し、その後クリーンアップします。

ビルドモード：createServer()を介して一時的なVite開発サーバーを作成し、resolveId/loadフックを使用して仮想モジュール'effcss:capture'を登録し、ssrLoadModule()を介してロードし、サーバーを閉じます。ユーザープラグイン（React、Vueなど）が組み込まれているため、JSX、SVG、CSSのインポートは適切に変換されます。このプラグインは、無限再帰を防ぐために、ネストされたサーバーから自身を除外します。

技術ノート

Vite: ^5.0.0 || ^6.0.0
EffCSS: ^5.4.0
ランタイム: EffCSSはブラウザバンドル内に残ります

クライアントサイドレンダリング ​

プラグインの使用方法 ​

オプション ​

仕組み ​

技術ノート ​

クライアントサイドレンダリング

プラグインの使用方法

オプション

仕組み

技術ノート