nishiki

Bundler setup

The compiler is an unplugin shipped in the same package as the runtime, so there is nothing else to install. It compiles the literal parts of css(...), styled(_, {...}) and css={{...}} with oxc at build time, using the same code as the runtime, so class names are identical either way.

Each bundler has its own entry, nishiki/unplugin/<bundler>. Two rules apply to all of them:

  • Run the compiler before the JSX transform, which must use nishiki as its import source.
  • Place it after plugins that move code between modules, such as TanStack Router's code splitting, so each module it compiles imports only the rules its own code uses.

Every bundler below has a runnable project in examples/.

// vite.config.ts
import react from "@vitejs/plugin-react";
import nishiki from "nishiki/unplugin/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [nishiki(), react({ jsxImportSource: "nishiki" })],
});
// rollup.config.js
import nishiki from "nishiki/unplugin/rollup";
import esbuild from "rollup-plugin-esbuild";

export default {
  input: "src/main.tsx",
  output: { dir: "dist", format: "es" },
  plugins: [nishiki(), esbuild({ jsx: "automatic", jsxImportSource: "nishiki" })],
};
// build.ts; JSX settings, including the import source, come from tsconfig.json
import nishiki from "nishiki/unplugin/rolldown";
import { build } from "rolldown";

await build({
  input: "src/main.tsx",
  output: { dir: "dist" },
  plugins: [nishiki()],
});
// webpack.config.js
import nishiki from "nishiki/unplugin/webpack";

export default {
  entry: "./src/main.tsx",
  resolve: { extensions: [".tsx", ".ts", ".js"] },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        exclude: /node_modules/,
        use: {
          loader: "swc-loader",
          options: {
            jsc: {
              parser: { syntax: "typescript", tsx: true },
              transform: { react: { runtime: "automatic", importSource: "nishiki" } },
            },
          },
        },
      },
    ],
  },
  plugins: [nishiki()],
};
// rspack.config.js
import nishiki from "nishiki/unplugin/rspack";

export default {
  entry: "./src/main.tsx",
  resolve: { extensions: [".tsx", ".ts", ".js"] },
  module: {
    rules: [
      {
        test: /\.tsx?$/,
        exclude: /node_modules/,
        loader: "builtin:swc-loader",
        options: {
          jsc: {
            parser: { syntax: "typescript", tsx: true },
            transform: { react: { runtime: "automatic", importSource: "nishiki" } },
          },
        },
      },
    ],
  },
  plugins: [nishiki()],
};
// rsbuild.config.ts
import { defineConfig } from "@rsbuild/core";
import { pluginReact } from "@rsbuild/plugin-react";
import nishiki from "nishiki/unplugin/rsbuild";

export default defineConfig({
  plugins: [pluginReact({ swcReactOptions: { importSource: "nishiki" } }), nishiki()],
});
// build.ts
import { build } from "esbuild";
import nishiki from "nishiki/unplugin/esbuild";

await build({
  entryPoints: ["src/main.tsx"],
  outdir: "dist",
  bundle: true,
  format: "esm",
  jsx: "automatic",
  jsxImportSource: "nishiki",
  plugins: [nishiki()],
});
// build.ts; Bun reads jsxImportSource from tsconfig.json
import nishiki from "nishiki/unplugin/bun";

await Bun.build({
  entrypoints: ["src/main.tsx"],
  outdir: "dist",
  plugins: [nishiki()],
});
// farm.config.ts
import { defineConfig } from "@farmfe/core";
import nishiki from "nishiki/unplugin/farm";

export default defineConfig({
  compilation: { input: { index: "./index.html" } },
  // Farm only strips types from TSX; the JSX transform comes from its React plugin.
  plugins: [["@farmfe/plugin-react", { runtime: "automatic", importSource: "nishiki" }], nishiki()],
});
// render.ts; unloader runs hooks in array order and ignores `enforce`, so the compiler must come before oxc's JSX transform.
import { createElement } from "react";
import { renderToString } from "react-dom/server";
import nishiki from "nishiki/unplugin/unloader";
import { register } from "unloader";
import oxc from "unplugin-oxc/unloader";

register({
  plugins: [nishiki(), oxc({ transform: { jsx: { runtime: "automatic", importSource: "nishiki" } } })],
});

// Modules imported after register() go through the plugins.
const { App } = await import("./src/App.tsx");
console.log(renderToString(createElement(App)));
// next.config.ts; works with webpack and Turbopack
import withKiln from "nishiki/unplugin/next";

export default withKiln({});

TanStack Router and TanStack Start use the Vite entry; place it after their plugin:

// vite.config.ts
import { tanstackRouter } from "@tanstack/router-plugin/vite";
import react from "@vitejs/plugin-react";
import nishiki from "nishiki/unplugin/vite";
import { defineConfig } from "vite";

export default defineConfig({
  plugins: [tanstackRouter({ target: "react", autoCodeSplitting: true }), nishiki(), react({ jsxImportSource: "nishiki" })],
});

Options

Option Default Meaning
importSource "nishiki" Module css and styled are imported from
cssProp true Compile css={{...}} on JSX elements
extract false Emit compiled rules as CSS instead of inserting them at runtime; see Extraction

extract takes true, or { split: "chunks" | "single" }. What it produces depends on the bundler; Extraction and CSS splitting covers each one.

Bundler notes

  • webpack, Rspack and Rsbuild: with extract, the project root must be a real path, not one under a symlink such as macOS's /var or /tmp. unplugin stores the CSS module under the root as given and the bundler resolves it to the real path, where it is missing. webpack and Rspack also need a CSS pipeline for the extracted modules, such as css-loader with mini-css-extract-plugin, or Rspack's CssExtractRspackPlugin; Rsbuild handles CSS itself.
  • Bun: Bun.build reads jsxImportSource from tsconfig.json.
  • Farm emits root-absolute asset URLs, so serve its output from /.
  • unloader transforms modules for Node and produces no browser bundle; the example renders the app on the server and writes a static page.
  • Next.js: Turbopack runs the compiler as a loader, which cannot add CSS modules, so extract only applies to webpack builds.