@bestcss/webpack-loader 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yuta Ura
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/css.d.ts

@@ -0,0 +1,11 @@
+interface LoaderContext {
+    resourcePath: string;
+}
+/**
+ * 元ファイル（css`` を含む tsx 等）を受け取り、抽出した CSS テキストを
+ * 返す loader。メイン loader が発行する matchResource import
+ * （`<file>.bestcss.css!=!@bestcss/webpack-loader/css!<file>`）から使われる
+ */
+export default function bestCssCssLoader(this: LoaderContext, source: string): string;
+export {};
+//# sourceMappingURL=css.d.ts.map

package/dist/css.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"css.d.ts","sourceRoot":"","sources":["../src/css.ts"],"names":[],"mappings":"AAEA,UAAU,aAAa;IACrB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,CACtC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,MAAM,GACb,MAAM,CAMR"}

package/dist/css.js

@@ -0,0 +1,14 @@
+import { transform } from "@bestcss/core";
+/**
+ * 元ファイル（css`` を含む tsx 等）を受け取り、抽出した CSS テキストを
+ * 返す loader。メイン loader が発行する matchResource import
+ * （`<file>.bestcss.css!=!@bestcss/webpack-loader/css!<file>`）から使われる
+ */
+export default function bestCssCssLoader(source) {
+    const result = transform(source, { filename: this.resourcePath });
+    // css`` を含まない入力はそのまま返す（冪等）。Turbopack は as: "*.css" の
+    // 適用後にルールを再評価することがあり、2 周目の入力は抽出済みの
+    // CSS テキストになるため、素通しできないと空になってしまう
+    return result?.css ?? source;
+}
+//# sourceMappingURL=css.js.map

package/dist/css.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"css.js","sourceRoot":"","sources":["../src/css.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAM1C;;;;GAIG;AACH,MAAM,CAAC,OAAO,UAAU,gBAAgB,CAEtC,MAAc;IAEd,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IAClE,qDAAqD;IACrD,mCAAmC;IACnC,iCAAiC;IACjC,OAAO,MAAM,EAAE,GAAG,IAAI,MAAM,CAAC;AAC/B,CAAC"}

package/dist/index.d.ts

@@ -0,0 +1,29 @@
+export interface BestCssLoaderOptions {
+    /**
+     * 抽出 CSS の取り込み方。
+     *
+     * - "match-resource"（デフォルト）: webpack の matchResource（`!=!`）構文で
+     *   「元ファイル自身を @bestcss/webpack-loader/css で CSS として再読み込み」する
+     * - "query": 自分自身をクエリ付き（`./file.tsx?bestcss`）で import する。
+     *   matchResource を解釈しない Turbopack 向け。利用側で
+     *   「query が bestcss のとき @bestcss/webpack-loader/css を as: '*.css' で
+     *   実行する」rule を設定する
+     */
+    importStyle?: "match-resource" | "query";
+}
+interface LoaderContext {
+    resourcePath: string;
+    getOptions?: () => BestCssLoaderOptions;
+    callback: (error: Error | null, content?: string, sourceMap?: unknown) => void;
+}
+/**
+ * css`` をクラス名リテラルへ変換する webpack loader。
+ *
+ * 抽出した CSS は仮想モジュールではなく「元ファイル自身を CSS として
+ * 再読み込み」する形で取り込む。ファイルが実在するため、仮想モジュール
+ * 機構を持たないバンドラー（Turbopack 等の loader 互換環境）にも
+ * 同じ発想を展開できる（ADR-0008）
+ */
+export default function bestCssLoader(this: LoaderContext, source: string): void;
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,oBAAoB;IACnC;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,gBAAgB,GAAG,OAAO,CAAC;CAC1C;AAED,UAAU,aAAa;IACrB,YAAY,EAAE,MAAM,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,oBAAoB,CAAC;IACxC,QAAQ,EAAE,CACR,KAAK,EAAE,KAAK,GAAG,IAAI,EACnB,OAAO,CAAC,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,OAAO,KAChB,IAAI,CAAC;CACX;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,UAAU,aAAa,CACnC,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,MAAM,GACb,IAAI,CA4BN"}

package/dist/index.js

@@ -0,0 +1,31 @@
+import path from "node:path";
+import { transform } from "@bestcss/core";
+/**
+ * css`` をクラス名リテラルへ変換する webpack loader。
+ *
+ * 抽出した CSS は仮想モジュールではなく「元ファイル自身を CSS として
+ * 再読み込み」する形で取り込む。ファイルが実在するため、仮想モジュール
+ * 機構を持たないバンドラー（Turbopack 等の loader 互換環境）にも
+ * 同じ発想を展開できる（ADR-0008）
+ */
+export default function bestCssLoader(source) {
+    const result = transform(source, { filename: this.resourcePath });
+    if (result === null) {
+        this.callback(null, source);
+        return;
+    }
+    // webpack のリクエスト文字列では ! が loader 区切り、? がクエリ開始として
+    // 解釈され、エスケープ手段がない。パスに含まれると任意 loader の注入に
+    // なり得るため明示的に拒否する
+    if (/[!?]/.test(this.resourcePath)) {
+        throw new Error(`bestcss: パスに "!" または "?" を含むファイルは扱えません: ${this.resourcePath}`);
+    }
+    const importStyle = this.getOptions?.().importStyle ?? "match-resource";
+    const cssRequest = importStyle === "query"
+        ? `./${path.basename(this.resourcePath)}?bestcss`
+        : // matchResource を .css にすることで、利用側の既存 CSS ルール
+            // （css-loader / mini-css-extract 等）がそのまま適用される
+            `${this.resourcePath}.bestcss.css!=!@bestcss/webpack-loader/css!${this.resourcePath}`;
+    this.callback(null, `${result.code}\nimport ${JSON.stringify(cssRequest)};\n`, result.map);
+}
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AA0B1C;;;;;;;GAOG;AACH,MAAM,CAAC,OAAO,UAAU,aAAa,CAEnC,MAAc;IAEd,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,EAAE,QAAQ,EAAE,IAAI,CAAC,YAAY,EAAE,CAAC,CAAC;IAClE,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,IAAI,CAAC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAC5B,OAAO;IACT,CAAC;IAED,iDAAiD;IACjD,yCAAyC;IACzC,iBAAiB;IACjB,IAAI,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,YAAY,CAAC,EAAE,CAAC;QACnC,MAAM,IAAI,KAAK,CACb,2CAA2C,IAAI,CAAC,YAAY,EAAE,CAC/D,CAAC;IACJ,CAAC;IAED,MAAM,WAAW,GAAG,IAAI,CAAC,UAAU,EAAE,EAAE,CAAC,WAAW,IAAI,gBAAgB,CAAC;IACxE,MAAM,UAAU,GACd,WAAW,KAAK,OAAO;QACrB,CAAC,CAAC,KAAK,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,YAAY,CAAC,UAAU;QACjD,CAAC,CAAC,6CAA6C;YAC7C,8CAA8C;YAC9C,GAAG,IAAI,CAAC,YAAY,8CAA8C,IAAI,CAAC,YAAY,EAAE,CAAC;IAC5F,IAAI,CAAC,QAAQ,CACX,IAAI,EACJ,GAAG,MAAM,CAAC,IAAI,YAAY,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,KAAK,EACzD,MAAM,CAAC,GAAG,CACX,CAAC;AACJ,CAAC"}

package/dist/plugin.d.ts

@@ -0,0 +1,58 @@
+export interface BestCssWebpackPluginOptions {
+    /**
+     * ビルド時にクラス名を使用頻度順の短い名前（a, b, ...）へ振り直す。
+     *
+     * @default true
+     */
+    minifyClassNames?: boolean;
+}
+interface AssetSource {
+    source: {
+        source: () => string | Buffer;
+    };
+}
+interface CompilationLike {
+    hooks: {
+        processAssets: {
+            tap: (options: {
+                name: string;
+                stage: number;
+            }, handler: (assets: Record<string, unknown>) => void) => void;
+        };
+    };
+    getAsset: (name: string) => AssetSource | undefined;
+    updateAsset: (name: string, source: unknown) => void;
+}
+interface CompilerLike {
+    webpack: {
+        Compilation: {
+            PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE: number;
+        };
+        sources: {
+            RawSource: new (source: string) => unknown;
+        };
+    };
+    hooks: {
+        thisCompilation: {
+            tap: (name: string, handler: (compilation: CompilationLike) => void) => void;
+        };
+    };
+}
+/**
+ * Vite 版の generateBundle 相当のサイズ最適化を webpack で行うプラグイン。
+ * CSS アセットの重複ルール排除と、クラス名の頻度順短縮（ADR-0004）。
+ *
+ * 生成クラス名の一覧は loader と状態を共有せず、CSS アセットのセレクタ
+ * （.bc...）から集める。loader が別プロセス・別インスタンスで動いても
+ * 自己完結するため。
+ *
+ * Turbopack にはアセット後処理のフックが存在しないため、このプラグインは
+ * webpack ビルド専用（Turbopack では内容ハッシュ名のまま配信される）
+ */
+export declare class BestCssWebpackPlugin {
+    private readonly minifyClassNames;
+    constructor(options?: BestCssWebpackPluginOptions);
+    apply(compiler: CompilerLike): void;
+}
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,2BAA2B;IAC1C;;;;OAIG;IACH,gBAAgB,CAAC,EAAE,OAAO,CAAC;CAC5B;AAID,UAAU,WAAW;IACnB,MAAM,EAAE;QAAE,MAAM,EAAE,MAAM,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CAC3C;AAED,UAAU,eAAe;IACvB,KAAK,EAAE;QACL,aAAa,EAAE;YACb,GAAG,EAAE,CACH,OAAO,EAAE;gBAAE,IAAI,EAAE,MAAM,CAAC;gBAAC,KAAK,EAAE,MAAM,CAAA;aAAE,EACxC,OAAO,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,KAC/C,IAAI,CAAC;SACX,CAAC;KACH,CAAC;IACF,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,WAAW,GAAG,SAAS,CAAC;IACpD,WAAW,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;CACtD;AAED,UAAU,YAAY;IACpB,OAAO,EAAE;QACP,WAAW,EAAE;YAAE,kCAAkC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC5D,OAAO,EAAE;YAAE,SAAS,EAAE,KAAK,MAAM,EAAE,MAAM,KAAK,OAAO,CAAA;SAAE,CAAC;KACzD,CAAC;IACF,KAAK,EAAE;QACL,eAAe,EAAE;YACf,GAAG,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,CAAC,WAAW,EAAE,eAAe,KAAK,IAAI,KAAK,IAAI,CAAC;SAC9E,CAAC;KACH,CAAC;CACH;AAID;;;;;;;;;;GAUG;AACH,qBAAa,oBAAoB;IAC/B,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAAU;gBAE/B,OAAO,GAAE,2BAAgC;IAIrD,KAAK,CAAC,QAAQ,EAAE,YAAY,GAAG,IAAI;CAgEpC"}

package/dist/plugin.js

@@ -0,0 +1,61 @@
+import { applyRename, createRenameMap, dedupeCss } from "@bestcss/core";
+const PLUGIN_NAME = "BestCssWebpackPlugin";
+/**
+ * Vite 版の generateBundle 相当のサイズ最適化を webpack で行うプラグイン。
+ * CSS アセットの重複ルール排除と、クラス名の頻度順短縮（ADR-0004）。
+ *
+ * 生成クラス名の一覧は loader と状態を共有せず、CSS アセットのセレクタ
+ * （.bc...）から集める。loader が別プロセス・別インスタンスで動いても
+ * 自己完結するため。
+ *
+ * Turbopack にはアセット後処理のフックが存在しないため、このプラグインは
+ * webpack ビルド専用（Turbopack では内容ハッシュ名のまま配信される）
+ */
+export class BestCssWebpackPlugin {
+    minifyClassNames;
+    constructor(options = {}) {
+        this.minifyClassNames = options.minifyClassNames ?? true;
+    }
+    apply(compiler) {
+        const { Compilation, sources } = compiler.webpack;
+        compiler.hooks.thisCompilation.tap(PLUGIN_NAME, (compilation) => {
+            compilation.hooks.processAssets.tap({
+                name: PLUGIN_NAME,
+                stage: Compilation.PROCESS_ASSETS_STAGE_OPTIMIZE_SIZE,
+            }, (assets) => {
+                const readAsset = (name) => compilation.getAsset(name)?.source.source().toString() ?? "";
+                const cssNames = Object.keys(assets).filter((n) => n.endsWith(".css"));
+                for (const name of cssNames) {
+                    compilation.updateAsset(name, new sources.RawSource(dedupeCss(readAsset(name))));
+                }
+                if (!this.minifyClassNames) {
+                    return;
+                }
+                const generated = new Set();
+                for (const name of cssNames) {
+                    for (const matched of readAsset(name).matchAll(/\.(bc[a-z0-9]+)/g)) {
+                        generated.add(matched[1]);
+                    }
+                }
+                if (generated.size === 0) {
+                    return;
+                }
+                const jsNames = Object.keys(assets).filter((n) => n.endsWith(".js"));
+                const frequencies = new Map([...generated].map((name) => [name, 0]));
+                for (const name of jsNames) {
+                    for (const matched of readAsset(name).matchAll(/\bbc[a-z0-9]+\b/g)) {
+                        const count = frequencies.get(matched[0]);
+                        if (count !== undefined) {
+                            frequencies.set(matched[0], count + 1);
+                        }
+                    }
+                }
+                const renameMap = createRenameMap(frequencies);
+                for (const name of [...jsNames, ...cssNames]) {
+                    compilation.updateAsset(name, new sources.RawSource(applyRename(readAsset(name), renameMap)));
+                }
+            });
+        });
+    }
+}
+//# sourceMappingURL=plugin.js.map

package/dist/plugin.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.js","sourceRoot":"","sources":["../src/plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AA0CxE,MAAM,WAAW,GAAG,sBAAsB,CAAC;AAE3C;;;;;;;;;;GAUG;AACH,MAAM,OAAO,oBAAoB;IACd,gBAAgB,CAAU;IAE3C,YAAY,UAAuC,EAAE;QACnD,IAAI,CAAC,gBAAgB,GAAG,OAAO,CAAC,gBAAgB,IAAI,IAAI,CAAC;IAC3D,CAAC;IAED,KAAK,CAAC,QAAsB;QAC1B,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,GAAG,QAAQ,CAAC,OAAO,CAAC;QAClD,QAAQ,CAAC,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,WAAW,EAAE,CAAC,WAAW,EAAE,EAAE;YAC9D,WAAW,CAAC,KAAK,CAAC,aAAa,CAAC,GAAG,CACjC;gBACE,IAAI,EAAE,WAAW;gBACjB,KAAK,EAAE,WAAW,CAAC,kCAAkC;aACtD,EACD,CAAC,MAAM,EAAE,EAAE;gBACT,MAAM,SAAS,GAAG,CAAC,IAAY,EAAU,EAAE,CACzC,WAAW,CAAC,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC;gBAC/D,MAAM,QAAQ,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAChD,CAAC,CAAC,QAAQ,CAAC,MAAM,CAAC,CACnB,CAAC;gBAEF,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;oBAC5B,WAAW,CAAC,WAAW,CACrB,IAAI,EACJ,IAAI,OAAO,CAAC,SAAS,CAAC,SAAS,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAClD,CAAC;gBACJ,CAAC;gBAED,IAAI,CAAC,IAAI,CAAC,gBAAgB,EAAE,CAAC;oBAC3B,OAAO;gBACT,CAAC;gBAED,MAAM,SAAS,GAAG,IAAI,GAAG,EAAU,CAAC;gBACpC,KAAK,MAAM,IAAI,IAAI,QAAQ,EAAE,CAAC;oBAC5B,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,CAC5C,kBAAkB,CACnB,EAAE,CAAC;wBACF,SAAS,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAW,CAAC,CAAC;oBACtC,CAAC;gBACH,CAAC;gBACD,IAAI,SAAS,CAAC,IAAI,KAAK,CAAC,EAAE,CAAC;oBACzB,OAAO;gBACT,CAAC;gBAED,MAAM,OAAO,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,CAAC;gBACrE,MAAM,WAAW,GAAG,IAAI,GAAG,CACzB,CAAC,GAAG,SAAS,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,CACxC,CAAC;gBACF,KAAK,MAAM,IAAI,IAAI,OAAO,EAAE,CAAC;oBAC3B,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,IAAI,CAAC,CAAC,QAAQ,CAC5C,kBAAkB,CACnB,EAAE,CAAC;wBACF,MAAM,KAAK,GAAG,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,CAAC;wBAC1C,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;4BACxB,WAAW,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;wBACzC,CAAC;oBACH,CAAC;gBACH,CAAC;gBAED,MAAM,SAAS,GAAG,eAAe,CAAC,WAAW,CAAC,CAAC;gBAC/C,KAAK,MAAM,IAAI,IAAI,CAAC,GAAG,OAAO,EAAE,GAAG,QAAQ,CAAC,EAAE,CAAC;oBAC7C,WAAW,CAAC,WAAW,CACrB,IAAI,EACJ,IAAI,OAAO,CAAC,SAAS,CAAC,WAAW,CAAC,SAAS,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC,CAAC,CAC/D,CAAC;gBACJ,CAAC;YACH,CAAC,CACF,CAAC;QACJ,CAAC,CAAC,CAAC;IACL,CAAC;CACF"}

package/docs/index.md

@@ -0,0 +1,80 @@
+# @bestcss/webpack-loader ドキュメント
+
+このディレクトリはパッケージに同梱されており、インストールされているバージョンと常に一致する。**css`` の文法や内部のしくみは [core のドキュメント](../../core/docs/index.md)**（`node_modules/@bestcss/core/docs/`）を参照。
+
+Vite 版と同じ変換コア（`@bestcss/core`）が動く。
+
+## webpack
+
+```js
+// webpack.config.js
+import MiniCssExtractPlugin from "mini-css-extract-plugin";
+import { BestCssWebpackPlugin } from "@bestcss/webpack-loader/plugin";
+
+export default {
+  module: {
+    rules: [
+      {
+        test: /\.[jt]sx?$/,
+        exclude: /node_modules/,
+        use: ["@bestcss/webpack-loader"],
+      },
+      {
+        test: /\.css$/,
+        // sideEffects: false 宣言下でも CSS import を保持する（css-loader の定石）
+        sideEffects: true,
+        use: [MiniCssExtractPlugin.loader, "css-loader"],
+      },
+    ],
+  },
+  plugins: [
+    new MiniCssExtractPlugin(),
+    // サイズ最適化（クラス名の頻度順短縮 + CSS の重複排除）
+    new BestCssWebpackPlugin(),
+  ],
+};
+```
+
+loader は抽出 CSS を matchResource（`!=!`）構文で「元ファイル自身の CSS としての再読み込み」として取り込むため、既存の CSS ルール（css-loader / mini-css-extract）がそのまま適用される。
+
+## Next.js（Turbopack）
+
+Turbopack は matchResource を解釈しないため、`importStyle: "query"` と `turbopack.rules` で統合する:
+
+```ts
+// next.config.ts
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  turbopack: {
+    rules: {
+      "*.tsx": {
+        condition: {
+          all: [{ not: "foreign" }, { not: { query: /bestcss/ } }],
+        },
+        loaders: [
+          {
+            loader: "@bestcss/webpack-loader",
+            options: { importStyle: "query" },
+          },
+        ],
+      },
+      "*": {
+        condition: { all: [{ not: "foreign" }, { query: /bestcss/ }] },
+        loaders: ["@bestcss/webpack-loader/css"],
+        as: "*.css",
+      },
+    },
+  },
+};
+
+export default nextConfig;
+```
+
+## 制限
+
+- **Turbopack ではサイズ最適化（クラス名短縮・CSS 重複排除）が使えない** — Turbopack にはアセット後処理のフック（webpack の processAssets 相当）が存在しないため。内容ハッシュ名（`bc...`、9 文字程度）のまま配信される。抽出・ゼロランタイムは動作する
+- SSR スイート（ルート単位分割・`routeCssHrefs`）は Vite 版のみ
+- ファイルパスに `!` または `?` を含むファイルは扱えない（webpack のリクエスト構文と衝突するため明示的にエラーになる）
+
+補足: `"sideEffects": false` を宣言したパッケージ内で css`` を使う場合は、上記 CSS ルールの `sideEffects: true` に加え、そのパッケージの宣言を `"sideEffects": ["**/*.css"]` にすること。

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@bestcss/webpack-loader",
+  "version": "0.1.0",
+  "description": "bestcss の webpack / Next.js (Turbopack) 統合。loader と最適化プラグイン",
+  "keywords": [
+    "css",
+    "css-in-js",
+    "zero-runtime",
+    "bestcss"
+  ],
+  "license": "MIT",
+  "author": "Yuta Ura",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/YutaUra/bestcss.git",
+    "directory": "packages/webpack-loader"
+  },
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./css": {
+      "types": "./dist/css.d.ts",
+      "default": "./dist/css.js"
+    },
+    "./plugin": {
+      "types": "./dist/plugin.d.ts",
+      "default": "./dist/plugin.js"
+    }
+  },
+  "files": [
+    "dist",
+    "docs"
+  ],
+  "dependencies": {
+    "@bestcss/core": "0.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.1.0",
+    "css-loader": "^7.1.4",
+    "mini-css-extract-plugin": "^2.10.2",
+    "typescript": "^6.0.3",
+    "webpack": "^5.108.3"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc --noEmit"
+  }
+}