@tailwind-merge/next 0.0.0-dev.50b1d1e9f69ac68604be38dabea94cccdc6b070a

package/dist/options-B1iOW6tJ.d.mts

@@ -0,0 +1,38 @@
+//#region src/options.d.ts
+interface TailwindMergeOptions {
+  /** Path to the project's Tailwind CSS entrypoint, relative to the project directory. When omitted, the entrypoint is auto-detected within the project. Set this to disambiguate themes or select an entrypoint outside the discovery scan. */
+  css?: string;
+  /** LRU cache size of the generated `twMerge`, passed through to the generated config. Defaults to tailwind-merge's default. */
+  cacheSize?: number;
+  /** How theme scales are encoded in the generated config: `'compact'` (default) picks the smallest matcher even when it accepts names beyond the theme, `'exact'` enumerates finite names to avoid that overmatching, at a size cost; arbitrary-value types remain approximate. See the configurator's docs for the tradeoff. */
+  encoding?: 'compact' | 'exact';
+  /**
+   * Prunes the generated config to the classes found in your sources — the same files Tailwind scans, found the same way — so production bundles ship only the class groups and scale values the project uses. Lists composed of scanned candidates merge exactly like with the full generated config; retained validators may also match unscanned names.
+   *
+   * `true` (the default): prune in `next build`, serve the full config in `next dev`. `false`: never prune — for projects whose class names reach `twMerge` from outside the scanned sources *and* get their styles from somewhere else than this Tailwind build (server-delivered markup, module federation). The object form configures the details.
+   */
+  prune?: boolean | PruneOptions;
+}
+interface PruneOptions {
+  /** Prune production builds. Defaults to `true`. */
+  build?: boolean;
+  /** Also prune in the dev server, for debugging differences between dev and build: every source edit that changes the used classes then regenerates the module. Defaults to `false`. */
+  dev?: boolean;
+  /** Log one line per generation saying what pruning did. Defaults to `true`. */
+  log?: boolean;
+}
+/**
+ * What the loader receives from the plugin through the bundler configuration. Plain data on purpose — Turbopack serializes loader options for its Rust side, so nothing here may be a function, a class instance, or `undefined` (absent keys are simply left out, see `serializableLoaderOptions`). The plugin resolves the user's options against the mode once so the loader never has to know the option surface.
+ */
+type LoaderOptions = {
+  /** `dev` for the dev server, `build` for `next build`: decides pruning and whether a generation failure fails the compilation (build) or falls back to the last good module (dev). */
+  mode: 'dev' | 'build';
+  prune: boolean;
+  log: boolean;
+  css?: string;
+  cacheSize?: number;
+  encoding?: 'compact' | 'exact';
+};
+//#endregion
+export { PruneOptions as n, TailwindMergeOptions as r, LoaderOptions as t };
+//# sourceMappingURL=options-B1iOW6tJ.d.mts.map

package/dist/options-B1iOW6tJ.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options-B1iOW6tJ.d.mts","names":[],"sources":["../src/options.ts"],"mappings":";UAAiB;;EAEb;;EAEA;;EAEA;;;;;;EAMA,kBAAkB;;UAGL;;EAEb;;EAEA;;EAEA;;;;;KAMQ;;EAER;EACA;EACA;EACA;EACA;EACA"}

package/dist/runtime.d.mts

@@ -0,0 +1,2 @@
+import { ClassNameValue, ClassValidator, Config, ConfigExtension, createTailwindMerge, extendTailwindMerge, getDefaultConfig as getConfig, mergeConfigs, twJoin, twMerge, validators } from "tailwind-merge";
+export { type ClassNameValue, type ClassValidator, type Config, type ConfigExtension, createTailwindMerge, extendTailwindMerge, getConfig, mergeConfigs, twJoin, twMerge, validators };

package/dist/runtime.mjs

@@ -0,0 +1,7 @@
+import { createTailwindMerge, extendTailwindMerge, getDefaultConfig as getConfig, mergeConfigs, twJoin, twMerge, validators } from "tailwind-merge";
+//#region src/runtime.ts
+/*! @tailwind-merge/next runtime fallback */
+//#endregion
+export { createTailwindMerge, extendTailwindMerge, getConfig, mergeConfigs, twJoin, twMerge, validators };
+
+//# sourceMappingURL=runtime.mjs.map

package/dist/runtime.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime.mjs","names":[],"sources":["../src/runtime.ts"],"sourcesContent":["/*! @tailwind-merge/next runtime fallback */\n\n/**\n * The stable import surface of `@tailwind-merge/next`: `import { twMerge } from '@tailwind-merge/next/runtime'`.\n *\n * When the plugin is configured, neither Turbopack nor webpack ever evaluates this file's content: a loader rule for the built `runtime.mjs` (matched by file name and by the legal comment above, which survives the package build where ordinary comments do not — kept to a few bytes because a bundle that includes this fallback keeps legal comments too) replaces it with the module generated from the project's Tailwind CSS, exporting the same names with the project-specific config in place. This file is what resolves everywhere else (Jest, plain Node scripts, tooling that does not load next.config) and serves tailwind-merge's default behavior, so code using the subpath keeps working outside the Next.js build, just without project-specific precision.\n *\n * It also defines the types users see: TypeScript always resolves the subpath to this file through ordinary package resolution, never to the generated module. The export surface must therefore stay in sync with the generated module's runtime appendix in the plugin core (see `fallbackModuleCode` there and the surface test in tests/config.test.ts).\n *\n * `extendTailwindMerge` deserves a note: in the generated module it extends the project's generated config, which is the reading users expect when customizing. Here it falls back to tailwind-merge's own export, which extends the default config — consistent, since the default config is exactly what this fallback serves. `fromTheme` is deliberately absent from the surface: generated configs materialize theme scales inline and carry an empty `theme` object, so theme getters would never match anything.\n */\nexport {\n    createTailwindMerge,\n    extendTailwindMerge,\n    getDefaultConfig as getConfig,\n    mergeConfigs,\n    twJoin,\n    twMerge,\n    validators,\n} from 'tailwind-merge'\nexport type { ClassNameValue, ClassValidator, Config, ConfigExtension } from 'tailwind-merge'\n"],"mappings":""}

package/package.json

@@ -0,0 +1,80 @@
+{
+  "name": "@tailwind-merge/next",
+  "version": "0.0.0-dev.50b1d1e9f69ac68604be38dabea94cccdc6b070a",
+  "description": "Next.js plugin that generates a project-optimized twMerge from the project's Tailwind CSS.",
+  "license": "MIT",
+  "author": "Dany Castillo",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dcastil/tailwind-merge.git",
+    "directory": "packages/next"
+  },
+  "homepage": "https://github.com/dcastil/tailwind-merge",
+  "bugs": {
+    "url": "https://github.com/dcastil/tailwind-merge/issues"
+  },
+  "type": "module",
+  "sideEffects": [
+    "./dist/runtime.mjs"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./runtime": {
+      "types": "./dist/runtime.d.mts",
+      "default": "./dist/runtime.mjs"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "peerDependencies": {
+    "@tailwindcss/postcss": "~4.3.3",
+    "next": "^16.0.0",
+    "tailwindcss": "~4.3.3"
+  },
+  "peerDependenciesMeta": {
+    "@tailwindcss/postcss": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@tailwindcss/node": "~4.3.3",
+    "@tailwindcss/oxide": "~4.3.3",
+    "enhanced-resolve": "^5.24.5",
+    "postcss": "^8.5.15",
+    "tailwind-merge": "3.7.0-dev.50b1d1e9f69ac68604be38dabea94cccdc6b070a"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "~4.3.3",
+    "@types/node": "^24.13.3",
+    "eslint": "^9.39.5",
+    "next": "^16.3.3",
+    "react": "^19.2.0",
+    "react-dom": "^19.2.0",
+    "tailwindcss": "~4.3.3",
+    "tsdown": "^0.22.14",
+    "typescript": "^6.0.3",
+    "vitest": "^4.1.10",
+    "@tailwind-merge/configurator": "0.0.0",
+    "@tailwind-merge/plugin-core": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "lint": "eslint --max-warnings 0 .",
+    "test": "vitest --no-watch",
+    "test:watch": "vitest",
+    "test:types": "tsc --noEmit",
+    "test:exports": "node scripts/test-packed-package.mjs",
+    "test:library-release": "node ../../scripts/check-library-release.mjs --sources ../configurator/src ../plugin-core/src src",
+    "release": "pnpm version --tag-version-prefix=@tailwind-merge/next@ --message=@tailwind-merge/next@%s",
+    "version": "node ../../scripts/update-pinned-links.mjs && node ../../scripts/pin-readme-links.mjs"
+  }
+}

package/src/index.ts

@@ -0,0 +1,162 @@
+import { existsSync, realpathSync } from 'node:fs'
+import path from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+import type { NextConfig } from 'next'
+
+import {
+    type TailwindMergeOptions,
+    resolveLoaderOptions,
+    serializableLoaderOptions,
+} from './options'
+
+export type { PruneOptions, TailwindMergeOptions } from './options'
+
+/** The function form of `next.config`, which Next.js calls with the current phase (see `next/constants`) and its default config. */
+export type NextConfigFunction = (
+    phase: string,
+    context: { defaultConfig: NextConfig },
+) => NextConfig | Promise<NextConfig>
+
+/**
+ * Configures tailwind-merge for the project's own Tailwind CSS in a Next.js app.
+ *
+ * Wrap the Next.js config with it and import from the runtime subpath: `import { twMerge } from '@tailwind-merge/next/runtime'`. While Next.js compiles the app, that import resolves to the module generated from the project's Tailwind theme by the inlined plugin core and configurator; outside Next.js it resolves to the real runtime.ts and serves default tailwind-merge behavior. Repository integration goals and invariants live in agents/next-plugin.md.
+ *
+ * Mechanics: neither Turbopack nor webpack offers virtual modules through the Next.js config, but both run webpack-style loaders, so the plugin registers a loader rule for this package's own `runtime.mjs` with both bundlers and lets the loader (src/loader.ts) replace the file's content with the generated module. The rules are keyed on the file name plus the legal comment inside the file, not on a path in node_modules, because Turbopack matches real paths — a symlinked install (`pnpm link`, a workspace) would otherwise fall through to the default config unnoticed. Dev and build get separate Turbopack rules through the built-in `development`/`production` conditions; the webpack hook reads the mode from its context. `transpilePackages` keeps the Pages Router's server bundle from externalizing the package: an externalized runtime would `require()` the on-disk fallback at request time while the client bundle carries the generated module, and the two would merge classes differently.
+ *
+ * The dev loop is deliberately quiet: the loader registers the files of the CSS configuration graph as dependencies (never the app's sources, unless `prune.dev` asks for it), so Next.js re-runs it only when one of those changes, and a regeneration that produces identical code leaves the bundlers' module hashes unchanged. Production builds additionally prune the config to the classes found in the project's sources (`prune` option).
+ */
+export function withTailwindMerge(
+    nextConfig: NextConfigFunction,
+    options?: TailwindMergeOptions,
+): NextConfigFunction
+export function withTailwindMerge(
+    nextConfig?: NextConfig,
+    options?: TailwindMergeOptions,
+): NextConfig
+export function withTailwindMerge(
+    nextConfig: NextConfig | NextConfigFunction = {},
+    options: TailwindMergeOptions = {},
+): NextConfig | NextConfigFunction {
+    if (typeof nextConfig === 'function') {
+        return async (phase, context) => applyToConfig(await nextConfig(phase, context), options)
+    }
+    return applyToConfig(nextConfig, options)
+}
+
+type TurbopackRules = NonNullable<NonNullable<NextConfig['turbopack']>['rules']>
+type TurbopackRuleCollection = TurbopackRules[string]
+type TurbopackRuleItem = Exclude<TurbopackRuleCollection, readonly unknown[]>
+
+function applyToConfig(config: NextConfig, options: TailwindMergeOptions): NextConfig {
+    warnWithoutCompilerConfig()
+    const rules = config.turbopack?.rules ?? {}
+    const existing = rules[RULE_GLOB]
+    const existingItems =
+        existing === undefined ? [] : Array.isArray(existing) ? existing : [existing]
+    const transpilePackages = config.transpilePackages ?? []
+
+    return {
+        ...config,
+        transpilePackages: transpilePackages.includes(PACKAGE_NAME)
+            ? transpilePackages
+            : [...transpilePackages, PACKAGE_NAME],
+        turbopack: {
+            ...config.turbopack,
+            rules: {
+                ...rules,
+                // A user rule on the same glob keeps running; rules are evaluated in order, so the plugin's come last.
+                [RULE_GLOB]: [...existingItems, ...turbopackRules(options)],
+            },
+        },
+        webpack(webpackConfig, context) {
+            webpackConfig.module.rules.push({
+                test: isRuntimeModule,
+                use: [
+                    {
+                        loader: LOADER_PATH,
+                        options: serializableLoaderOptions(
+                            resolveLoaderOptions(options, context.dev ? 'dev' : 'build'),
+                        ),
+                    },
+                ],
+            })
+            return config.webpack ? config.webpack(webpackConfig, context) : webpackConfig
+        },
+    }
+}
+
+let warnedWithoutCompilerConfig = false
+
+/**
+ * Turbopack applies loader rules to code in node_modules only when the project has a `tsconfig.json` or `jsconfig.json` — even an empty one; the content does not matter (observed with Next.js 16.3, reproduced with a bare `*.mjs` rule). Without one, the runtime subpath would silently keep tailwind-merge's default behavior under Turbopack, so say so once per process. create-next-app writes one of the two files for every project, which keeps this rare. The working directory stands in for the project directory, which the config API does not expose.
+ */
+function warnWithoutCompilerConfig() {
+    if (warnedWithoutCompilerConfig) {
+        return
+    }
+    warnedWithoutCompilerConfig = true
+    const directory = process.cwd()
+    if (
+        !['tsconfig.json', 'jsconfig.json'].some((file) => existsSync(path.join(directory, file)))
+    ) {
+        console.warn(
+            `[${PACKAGE_NAME}] No tsconfig.json or jsconfig.json found in ${directory}. Turbopack only applies the plugin's loader to installed packages when the project has one, so without it the runtime import keeps tailwind-merge's default configuration. Add an empty jsconfig.json if the project has no TypeScript configuration.`,
+        )
+    }
+}
+
+/** One rule per mode: Turbopack evaluates the plugin's config once for `next dev` and `next build` alike, so the mode has to be a rule condition rather than a value computed at config time. */
+function turbopackRules(options: TailwindMergeOptions): TurbopackRuleItem[] {
+    return (['dev', 'build'] as const).map((mode) => ({
+        condition: {
+            all: [
+                { path: RUNTIME_PATH_PATTERN },
+                { content: RUNTIME_MARKER_PATTERN },
+                mode === 'dev' ? 'development' : 'production',
+            ],
+        },
+        loaders: [
+            {
+                loader: LOADER_PATH,
+                options: serializableLoaderOptions(resolveLoaderOptions(options, mode)),
+            },
+        ],
+    }))
+}
+
+/** webpack hands rules the resolved resource path, with symlinks resolved by default: compare against both spellings of this package's runtime file. */
+function isRuntimeModule(file: string): boolean {
+    return file === RUNTIME_PATH || file === runtimeRealPath()
+}
+
+let resolvedRuntimeRealPath: string | undefined
+
+function runtimeRealPath(): string {
+    if (resolvedRuntimeRealPath === undefined) {
+        try {
+            resolvedRuntimeRealPath = realpathSync(RUNTIME_PATH)
+        } catch {
+            // The package's own runtime file is missing only in unbuilt source checkouts; the unresolved path keeps the comparison meaningful.
+            resolvedRuntimeRealPath = RUNTIME_PATH
+        }
+    }
+    return resolvedRuntimeRealPath
+}
+
+const PACKAGE_NAME = '@tailwind-merge/next'
+
+/** Turbopack rule keys are file-name globs; the conditions below narrow the rule to this package's runtime file. */
+const RULE_GLOB = '*.mjs'
+
+/** Turbopack matches project-relative real paths with forward slashes; only the file name is fixed across install layouts. */
+const RUNTIME_PATH_PATTERN = /(^|\/)runtime\.mjs$/
+
+/** The legal comment at the top of src/runtime.ts, which the build preserves — the one part of the runtime file's content the rule can rely on across install layouts. */
+const RUNTIME_MARKER_PATTERN = /@tailwind-merge\/next runtime fallback/
+
+/** Both bundlers accept a loader as an absolute file path, which sidesteps loader-name resolution and the exports map. Built and source layouts agree on the relative location. */
+const LOADER_PATH = fileURLToPath(new URL('./loader.mjs', import.meta.url))
+
+const RUNTIME_PATH = fileURLToPath(new URL('./runtime.mjs', import.meta.url))

package/src/loader.ts

@@ -0,0 +1,183 @@
+import { statSync } from 'node:fs'
+import path from 'node:path'
+
+import {
+    type GeneratedRuntimeModule,
+    type GenerationSession,
+    createGenerationSession,
+    discoverCssRoot,
+    fallbackModuleCode,
+} from '@tailwind-merge/plugin-core'
+
+import { type LoaderOptions } from './options'
+
+/** The slice of the webpack loader API this loader uses. Turbopack's loader runner provides the same members (verified against Next.js 16.3, where `addMissingDependency` is accepted but not acted on — the recovery directories the plugin core reports cover that case as context dependencies). */
+export interface LoaderContext {
+    /** The Next.js project directory. */
+    rootContext: string
+    resourcePath: string
+    getOptions(): LoaderOptions
+    addDependency(file: string): void
+    addContextDependency(directory: string): void
+    addMissingDependency(file: string): void
+}
+
+/**
+ * Replaces the content of this package's runtime module with the module generated from the project's Tailwind CSS. Registered by `withTailwindMerge` (src/index.ts) with both Turbopack and webpack; runs once per compilation environment (server components, server rendering, browser), which the per-process project state below turns into one generation.
+ *
+ * Every run registers the CSS configuration graph — entrypoint, imported stylesheets, `@config`/`@plugin` modules, and the directories a missing import would appear in — as dependencies, so the bundler re-runs the loader when any of them changes and `refresh()` decides whether that change regenerates the module. A regeneration with identical output changes nothing downstream: both bundlers hash module content. With pruning active (builds, or dev with `prune.dev`), the scanned source directories are context dependencies too, so a class-usage change re-prunes the retained classification, and Turbopack's persistent cache cannot serve a module pruned for other sources.
+ *
+ * Failure policy mirrors the Vite plugin's: a build fails on a configuration-generation failure (the loader rejects, which fails the compilation), while the dev server logs the error and keeps serving the last good module — or the default fallback before the first success. A project without a Tailwind root warns once and serves the default fallback as well. A failed source scan is not a generation failure: the module holds the full config and the warning says so.
+ */
+export default async function tailwindMergeLoader(this: LoaderContext): Promise<string> {
+    const options = this.getOptions()
+    const project = projectState(this.rootContext, options)
+    const generated = await project.next()
+    registerDependencies(this, project, generated)
+    // Without a Tailwind root (or before the first successful generation) the served module is the same default-config surface the file on disk provides, minus the file's marker comment, which would otherwise survive minification in the app bundle.
+    return generated?.code ?? fallbackModuleCode(IMPORT_SOURCE)
+}
+
+interface ProjectState {
+    root: string
+    session: GenerationSession
+    /** The resolved entrypoint once discovery has finished: null when the project has none, undefined while unknown. */
+    cssRoot: string | null | undefined
+    /** Coalesces the compilation environments' concurrent runs into one generation or refresh. */
+    inFlight: Promise<GeneratedRuntimeModule | null> | undefined
+    started: boolean
+    next(): Promise<GeneratedRuntimeModule | null>
+}
+
+/** One state per project and option set for the life of the loader process — Next.js runs webpack loaders in its own process and Turbopack loaders in a pool process it keeps alive across compilations, so the session's retained classification and dependency graph survive from one loader run to the next. */
+const projects = new Map<string, ProjectState>()
+
+function projectState(root: string, options: LoaderOptions): ProjectState {
+    const key = `${root}\0${JSON.stringify(options)}`
+    let state = projects.get(key)
+    if (state) {
+        return state
+    }
+
+    const cssRoot: Promise<string | null> =
+        options.css !== undefined
+            ? Promise.resolve(path.resolve(root, options.css))
+            : discoverCssRoot(root, { packageName: PACKAGE_NAME }).then((found) => {
+                  if (found === null) {
+                      console.warn(
+                          `[${PACKAGE_NAME}] No Tailwind CSS root found — serving default tailwind-merge behavior. Set the \`css\` option to your Tailwind entrypoint if it uses another extension or is outside the scanned directories.`,
+                      )
+                  }
+                  return found
+              })
+
+    const session = createGenerationSession({
+        cssRoot,
+        root,
+        packageName: PACKAGE_NAME,
+        importSource: IMPORT_SOURCE,
+        cacheSize: options.cacheSize,
+        encoding: options.encoding,
+        // Tailwind's PostCSS plugin, which Next.js runs, starts automatic source detection in the working directory — the project directory in any ordinary `next dev`/`next build`.
+        prune: options.prune ? { autoDetectBases: [root] } : undefined,
+        onGenerated: (generated) => reportPruning(generated, options),
+        onError(error, current) {
+            if (options.mode === 'build') {
+                throw error
+            }
+            console.error(
+                `[${PACKAGE_NAME}] Generating the tailwind-merge config failed${current ? ' — keeping the previous one' : ''}: ${error instanceof Error ? error.message : String(error)}`,
+            )
+        },
+    })
+    state = {
+        root,
+        session,
+        cssRoot: undefined,
+        inFlight: undefined,
+        started: false,
+        next() {
+            if (!this.inFlight) {
+                // The first run is the session's eager generation; every later loader run is a refresh, which reuses the module unless the CSS graph or the used classes changed. A rejection (a build's failure policy) propagates to every waiting run.
+                const attempt = this.started ? this.session.refresh() : this.session.generation
+                this.started = true
+                this.inFlight = attempt.finally(() => {
+                    this.inFlight = undefined
+                })
+            }
+            return this.inFlight
+        },
+    }
+    void cssRoot.then(
+        (found) => {
+            state!.cssRoot = found
+        },
+        () => {},
+    )
+    projects.set(key, state)
+    return state
+}
+
+/**
+ * Hands the session's dependency graph to the bundler: files as file dependencies, directories (the recovery directories reported for missing imports, and a missing explicit entrypoint's nearest existing parent) as context dependencies, and nonexistent paths as missing dependencies for webpack, which acts on them. With pruning, the scanned source bases join as context dependencies.
+ */
+function registerDependencies(
+    context: LoaderContext,
+    project: ProjectState,
+    generated: GeneratedRuntimeModule | null,
+) {
+    const dependencies = new Set(project.session.dependencies)
+    if (project.cssRoot) {
+        dependencies.add(project.cssRoot)
+    }
+    for (const dependency of dependencies) {
+        const stats = statSync(dependency, { throwIfNoEntry: false })
+        if (!stats) {
+            context.addMissingDependency(dependency)
+            if (dependency === project.cssRoot) {
+                context.addContextDependency(nearestExistingDirectory(dependency))
+            }
+        } else if (stats.isDirectory()) {
+            context.addContextDependency(dependency)
+        } else {
+            context.addDependency(dependency)
+        }
+    }
+    for (const source of generated?.pruning?.scanner.sources ?? []) {
+        if (!source.negated) {
+            context.addContextDependency(source.base)
+        }
+    }
+}
+
+function nearestExistingDirectory(file: string): string {
+    let directory = path.dirname(file)
+    while (!statSync(directory, { throwIfNoEntry: false })?.isDirectory()) {
+        const parent = path.dirname(directory)
+        if (parent === directory) {
+            break
+        }
+        directory = parent
+    }
+    return directory
+}
+
+/** One line per generation about pruning, so the behavior and its effect are visible where someone debugging a production-only merge difference would look; a failed scan is always reported, since the module then silently holds the full config. */
+function reportPruning(generated: GeneratedRuntimeModule, options: LoaderOptions) {
+    if (generated.pruningError) {
+        console.warn(
+            `[${PACKAGE_NAME}] Could not scan your sources, serving the full tailwind-merge config instead: ${generated.pruningError.message}`,
+        )
+    } else if (generated.pruning && options.log) {
+        const { classGroupsAfter, classGroupsBefore, classifiedClassCount } =
+            generated.pruning.report
+        console.log(
+            `[${PACKAGE_NAME}] Pruned the tailwind-merge config to ${classGroupsAfter} of ${classGroupsBefore} class groups from the ${classifiedClassCount} classes found in your sources`,
+        )
+    }
+}
+
+const PACKAGE_NAME = '@tailwind-merge/next'
+
+/** The generated module replaces a real file inside this package, so it can import tailwind-merge the ordinary way: resolution starts in the package's own directory, where its dependency is installed under any package manager. */
+const IMPORT_SOURCE = 'tailwind-merge'

package/src/options.ts

@@ -0,0 +1,81 @@
+export interface TailwindMergeOptions {
+    /** Path to the project's Tailwind CSS entrypoint, relative to the project directory. When omitted, the entrypoint is auto-detected within the project. Set this to disambiguate themes or select an entrypoint outside the discovery scan. */
+    css?: string
+    /** LRU cache size of the generated `twMerge`, passed through to the generated config. Defaults to tailwind-merge's default. */
+    cacheSize?: number
+    /** How theme scales are encoded in the generated config: `'compact'` (default) picks the smallest matcher even when it accepts names beyond the theme, `'exact'` enumerates finite names to avoid that overmatching, at a size cost; arbitrary-value types remain approximate. See the configurator's docs for the tradeoff. */
+    encoding?: 'compact' | 'exact'
+    /**
+     * Prunes the generated config to the classes found in your sources — the same files Tailwind scans, found the same way — so production bundles ship only the class groups and scale values the project uses. Lists composed of scanned candidates merge exactly like with the full generated config; retained validators may also match unscanned names.
+     *
+     * `true` (the default): prune in `next build`, serve the full config in `next dev`. `false`: never prune — for projects whose class names reach `twMerge` from outside the scanned sources *and* get their styles from somewhere else than this Tailwind build (server-delivered markup, module federation). The object form configures the details.
+     */
+    prune?: boolean | PruneOptions
+}
+
+export interface PruneOptions {
+    /** Prune production builds. Defaults to `true`. */
+    build?: boolean
+    /** Also prune in the dev server, for debugging differences between dev and build: every source edit that changes the used classes then regenerates the module. Defaults to `false`. */
+    dev?: boolean
+    /** Log one line per generation saying what pruning did. Defaults to `true`. */
+    log?: boolean
+}
+
+/**
+ * What the loader receives from the plugin through the bundler configuration. Plain data on purpose — Turbopack serializes loader options for its Rust side, so nothing here may be a function, a class instance, or `undefined` (absent keys are simply left out, see `serializableLoaderOptions`). The plugin resolves the user's options against the mode once so the loader never has to know the option surface.
+ */
+export type LoaderOptions = {
+    /** `dev` for the dev server, `build` for `next build`: decides pruning and whether a generation failure fails the compilation (build) or falls back to the last good module (dev). */
+    mode: 'dev' | 'build'
+    prune: boolean
+    log: boolean
+    css?: string
+    cacheSize?: number
+    encoding?: 'compact' | 'exact'
+}
+
+/** Resolves the `prune` option's shorthand forms and defaults into the full object. */
+export function resolvePruneOptions(option: TailwindMergeOptions['prune']): Required<PruneOptions> {
+    if (option === false) {
+        return { build: false, dev: false, log: false }
+    }
+    if (option === true || option === undefined) {
+        return { build: true, dev: false, log: true }
+    }
+    return { build: option.build ?? true, dev: option.dev ?? false, log: option.log ?? true }
+}
+
+/** The loader options for one mode, with only the keys the user set — the loader applies the defaults of the underlying generator for the rest. */
+export function resolveLoaderOptions(
+    options: TailwindMergeOptions,
+    mode: LoaderOptions['mode'],
+): LoaderOptions {
+    const prune = resolvePruneOptions(options.prune)
+    const resolved: LoaderOptions = {
+        mode,
+        prune: mode === 'build' ? prune.build : prune.dev,
+        log: prune.log,
+    }
+    if (options.css !== undefined) {
+        resolved.css = options.css
+    }
+    if (options.cacheSize !== undefined) {
+        resolved.cacheSize = options.cacheSize
+    }
+    if (options.encoding !== undefined) {
+        resolved.encoding = options.encoding
+    }
+    return resolved
+}
+
+/** The same options as a value the bundler configuration types accept: Next's loader option type has no room for `undefined`, which TypeScript reads into every optional key, so the object is rebuilt from its present keys. */
+export function serializableLoaderOptions(
+    options: LoaderOptions,
+): Record<string, string | number | boolean> {
+    return Object.fromEntries(
+        Object.entries(options).filter(
+            (entry): entry is [string, string | number | boolean] => entry[1] !== undefined,
+        ),
+    )
+}

package/src/runtime.ts

@@ -0,0 +1,21 @@
+/*! @tailwind-merge/next runtime fallback */
+
+/**
+ * The stable import surface of `@tailwind-merge/next`: `import { twMerge } from '@tailwind-merge/next/runtime'`.
+ *
+ * When the plugin is configured, neither Turbopack nor webpack ever evaluates this file's content: a loader rule for the built `runtime.mjs` (matched by file name and by the legal comment above, which survives the package build where ordinary comments do not — kept to a few bytes because a bundle that includes this fallback keeps legal comments too) replaces it with the module generated from the project's Tailwind CSS, exporting the same names with the project-specific config in place. This file is what resolves everywhere else (Jest, plain Node scripts, tooling that does not load next.config) and serves tailwind-merge's default behavior, so code using the subpath keeps working outside the Next.js build, just without project-specific precision.
+ *
+ * It also defines the types users see: TypeScript always resolves the subpath to this file through ordinary package resolution, never to the generated module. The export surface must therefore stay in sync with the generated module's runtime appendix in the plugin core (see `fallbackModuleCode` there and the surface test in tests/config.test.ts).
+ *
+ * `extendTailwindMerge` deserves a note: in the generated module it extends the project's generated config, which is the reading users expect when customizing. Here it falls back to tailwind-merge's own export, which extends the default config — consistent, since the default config is exactly what this fallback serves. `fromTheme` is deliberately absent from the surface: generated configs materialize theme scales inline and carry an empty `theme` object, so theme getters would never match anything.
+ */
+export {
+    createTailwindMerge,
+    extendTailwindMerge,
+    getDefaultConfig as getConfig,
+    mergeConfigs,
+    twJoin,
+    twMerge,
+    validators,
+} from 'tailwind-merge'
+export type { ClassNameValue, ClassValidator, Config, ConfigExtension } from 'tailwind-merge'