Options

Pass a second argument to withTailwindcssAtomic, or the same object to Vite / Webpack / Rollup / esbuild / Astro plugins.


type Options = {
  /** Functions whose string arguments are rewritten. */
  targetFunctions?: Set<string>;
  /** Already-compiled Tailwind CSS, to preload the map (uncommon). */
  tailwindCss?: string;
  /** Packages under node_modules whose JS is rewritten (design systems). */
  transpilePackages?: string[];
  /** Extra CSS that is not atomicized (on top of node_modules). */
  ignoreCss?: Array<string | RegExp>;
  /** Class names that look like utilities but must stay literal. */
  preserveClasses?: Array<string | RegExp>;
  /** Functions whose strings are left intact (default `twIgnore`). */
  preserveFunctions?: Iterable<string>;
  /** JSON inventory of the map. `false` disables it. */
  classMapFile?: string | boolean;
  /** Extra CSS/SCSS entries for warmup (monorepos: `scss/styles.scss`). */
  cssEntries?: string[];
  /**
   * Print a before/after report when the build finishes.
   * `true` pretty-prints; `"json"` emits one JSON line.
   */
  report?: boolean | "json";
};

Defaults

targetFunctions: cn, clsx, classnames, cva
preserveFunctions: twIgnore
classMapFile: node_modules/.cache/tailwindcss-atomic/class-map.json


withTailwindcssAtomic(nextConfig, {
  targetFunctions: new Set(["cn", "clsx", "tw"]),
});

`report`

Shows what the compiler changed in this build: CSS bytes (raw + gzip), unique utilities vs shared atomic hashes, and class-string size (hashed names are often slightly longer).


withTailwindcssAtomic(nextConfig, {report: true});

Or without changing config:


TAILWINDCSS_ATOMIC_REPORT=1 pnpm build
TAILWINDCSS_ATOMIC_REPORT=json pnpm build

Dev servers skip the print so HMR is not noisy. In this repo, pnpm report:apps builds every example app with the text report on.

`transpilePackages`

Use this when class strings live in a workspace UI package or in node_modules. Without it, Turbopack/Webpack may leave flex in the published JS while the app CSS is already hashed.

`cssEntries`

Force warmup of SCSS/CSS files that are not the first stylesheet Next discovers. Typical in monorepos:


export default withTailwindcssAtomic(nextConfig, {
  cssEntries: ["scss/styles.scss"],
});

`classMapFile`

Set a custom path, or false to skip writing the inventory.


tailwindcssAtomic({
  classMapFile: ".cache/atomic-class-map.json",
});

`ignoreCss`

Skip atomicizing extra CSS besides node_modules (third-party sheets you import into the app bundle).

`preserveClasses`

Leave class names that look like Tailwind utilities (text-logo, flex-container) as literals. Strings match exactly; regexes test the unescaped name.


withTailwindcssAtomic(nextConfig, {
  preserveClasses: ["text-logo", /^flex-container$/],
});

The map is written so JS/HTML rewrite does not race PostCSS.