tailwind-merge

# AGENTS.md

This repository is a pnpm monorepo hosting `tailwind-merge` — a TypeScript library that merges Tailwind class strings by removing style conflicts while preserving non-conflicting and non-Tailwind classes — and its sibling packages. Packages are independent: each owns its lint, test, and type-check setup and releases on its own schedule.

## Primary Goals

- Keep merge behavior correct for the supported Tailwind versions listed in the library documentation.
- Keep runtime fast (browser-oriented hot path, lazy init, lightweight cache).
- Keep API and type contracts stable.

## Repo Map

- The library package: `packages/tailwind-merge/` — source in `src/`, tests in `tests/`, human docs in `docs/`, build/release scripts in `scripts/`, published overview `README.md` (autogenerated from `docs/README.md`).
- Unreleased workspace packages: `packages/configurator/` generates tailwind-merge configs from Tailwind v4 CSS; `packages/plugin-core/` adds what every bundler plugin needs on top (CSS root discovery, runtime-module generation, the generation session); `packages/vite/` and `packages/next/` wrap both for Vite and Next.js with automatic generation and usage pruning. The configurator and the plugins have a maintained `README.md` and user documentation in `docs/`; the plugin core is internal and inlined into both plugins.
- Repo root: workspace orchestration only — `pnpm-workspace.yaml` (workspace list + shared tool-version catalog), `eslint.config.base.mjs` (shared lint base every scope spreads), root `eslint.config.mjs` (lints root files and `.github/`), root `vitest.config.mts` (aggregates the packages' Vitest projects plus the local GitHub actions' tests), repo-wide release tooling in `scripts/` (`update-pinned-links.mjs`, `pin-readme-links.mjs`, `stamp-dev-version.mjs`, `check-library-release.mjs`), and the repo-level `README.md`.
- CI workflows: `.github/workflows/`
- Local GitHub actions: `.github/actions/`

## Agent Docs Map

- `agents/tailwind-merge-internals.md`: library architecture, file ownership, shared testing/build behavior, and CI/security guardrails.
- `agents/configurator.md`: configurator goals, strategy, generation/classification architecture, correctness gates, and development follow-ups.
- `agents/plugin-core.md`: the shared plugin core — discovery, generation, and session invariants, testing, and its inlined packaging.
- `agents/vite-plugin.md`: Vite integration goals, runtime resolution, watching/failure contracts, packaging, and test coverage.
- `agents/next-plugin.md`: Next.js integration goals, the loader-rule mechanism and its Turbopack/webpack facts, testing harness, packaging, and test coverage.
- `agents/configurator-performance.md`: dated measurements, optimization rationale, and reproduction methodology.
- `agents/tailwind-css-version-update.md`: Tailwind CSS version support workflow.
- `agents/release-workflow.md`: changelog authoring, GitHub release text, sponsor handling, and release comments on issues/PRs.

## Environment and Commands

- Package manager: `pnpm` with a workspace rooted at `pnpm-workspace.yaml`
- Local development runtime: Node `22.18.0` or newer on a supported LTS release, satisfying the requirements of pnpm 11 and the Babel 8 build toolchain
- CI runtime: Node `24.18.1`, pinned via `node-version` in the workflows under `.github/workflows/` (Renovate bumps it there; treat the workflows as the source of truth if this number looks stale)
- Consumer TypeScript support: TypeScript `3.8` and newer; `pnpm test:exports` verifies the generated declarations with the pinned minimum compiler
- Dependency supply-chain guardrail: `minimumReleaseAge: 4320` in `pnpm-workspace.yaml`, so newly published package versions must be at least three days old before pnpm installs them. Renovate has a matching cooldown in `.github/renovate.json` (see `agents/tailwind-merge-internals.md` for how the two must stay in sync).
- Dependency build scripts are denied by default unless explicitly allowed in `pnpm-workspace.yaml`; `esbuild` is currently allowed because `.github/actions/metrics-report` needs it.
- The root manifest's `devEngines.runtime` must encode the real documented Node floor (currently `>=22.18.0`), not a rounded-down one: pnpm validates dependency `engines` against the range's minimum version, and a floor looser than a dependency's own requirement makes pnpm silently skip optional dependencies during install — this is how rolldown's platform binary went missing under an earlier `>=22`, with only a debug-level log mentioning it.

Core commands (repo root):

- `pnpm install --frozen-lockfile`
- `pnpm lint` — lints root files, then every package's own lint script (`pnpm --recursive lint`)
- `pnpm test` — runs every package's Vitest project plus the local GitHub actions' tests through the root projects config, with coverage
- `pnpm test:types` — every package's own tsc project (`pnpm --recursive test:types`)
- `pnpm test:watch` — cross-package watch mode

Library-specific commands (run with `pnpm --filter tailwind-merge <script>` from anywhere, or plain `pnpm <script>` inside `packages/tailwind-merge/`):

- `build`
- `test:exports`
- `bench`

Vite-plugin-specific commands (run with `pnpm --filter @tailwind-merge/vite <script>`, or plain `pnpm <script>` inside `packages/vite/`):

- `build` — tsdown, ESM bundles plus declarations for all three subpaths into `dist/`
- `test:exports` — packs the tarball and verifies the published shape; requires both this package's and the library's `build` to have run first (see [Vite build and packaging](./agents/vite-plugin.md#build-and-packaging) for what it checks)

Next.js-plugin-specific commands (run with `pnpm --filter @tailwind-merge/next <script>`, or plain `pnpm <script>` inside `packages/next/`):

- `build` — tsdown, ESM bundles plus declarations for the plugin entry, the loader, and the runtime into `dist/`; the package's `exports` point at `dist/` even in the workspace, and its test global setup runs this build
- `test` — spawns real `next dev`/`next build` processes for both bundlers (about two minutes); needs the library built, which the global setup does when `packages/tailwind-merge/dist` is missing
- `test:exports` — packs the tarball and verifies the published shape including a real `next build` of a consumer app; requires both this package's and the library's `build` to have run first (see [Next.js build and packaging](./agents/next-plugin.md#build-and-packaging))

Monorepo conventions:

- Shared tool versions (eslint, typescript, vitest, @types/node) live in the `catalog:` section of `pnpm-workspace.yaml`; package manifests reference them as `"catalog:"`. Single-consumer dependencies stay pinned in their package manifest.
- Every package lints with its own `eslint.config.mjs` spreading `eslint.config.base.mjs` from the root, and tests with its own `vitest.config.mts`; the root configs only orchestrate.
- No task runner (turborepo or similar) and no affected-only CI on purpose: at the current package count the full suite is fast, and running everything keeps cross-package effects (a tailwind-merge or plugin-core change must exercise both plugins' tests) trivially correct. Revisit when the package count grows or build times make caching pay off.
- Releases are per package with `<package-name>@<version>` git tags (for example `tailwind-merge@3.7.0`); see `agents/release-workflow.md`.

## Working Rules for Changes

1. Treat `packages/tailwind-merge/src/lib/default-config.ts` as the behavioral source of truth for default class groups and conflicts.
2. If behavior changes, update tests in `packages/tailwind-merge/tests/` in the same change.
3. If public behavior/docs change, update docs in `packages/tailwind-merge/docs/` (not directly in a `README.md`).
4. The library's `README.md` and the generated section of the repo-level `README.md` are version-generated from the library's `docs/README.md`; do not regenerate them during normal development changes. The configurator, Vite, and Next.js READMEs are maintained landing pages, not generated files; edit them alongside their own `docs/` pages.
5. Avoid manual edits to `dist/` and `coverage/` directories; they are generated artifacts.
6. Validate packaging paths with `pnpm --filter tailwind-merge build && pnpm --filter tailwind-merge test:exports` when touching exports/build tooling.

## Documentation Sync Policy

Treat documentation updates as part of the same change, not as follow-up work.

Self-improvement is required while working in this repo: whenever you discover useful information about architecture, workflows, commands, constraints, debugging findings, or recurring pitfalls, add it to the appropriate file in `agents/` or to `AGENTS.md` in the same change. When existing agent guidance becomes stale, misleading, or irrelevant, remove or revise it immediately.

Avoid repeating the same guidance in both `AGENTS.md` and specialized `agents/*` docs unless the rule is critically important. Prefer keeping `AGENTS.md` as the high-level entry point and putting detailed workflow, architecture, release, or CI notes in the relevant specialized agent document.

Cross-package user-docs convention: every package's docs recommend setting `twMerge` up in one project-owned file (shown as `tw-merge.ts`) and importing it from there, even without configuration, so that configuring, wrapping, or replacing `twMerge` later is a one-file change. The canonical explanation lives in the library's `docs/configuration.md` ("Import `twMerge` from one place"); the plugin and configurator getting-started pages carry their own short version. Keep new setup instructions and usage examples consistent with it.

It is acceptable to periodically restructure agent documentation when files become too large, when topics are hard to find, or when the current organization no longer matches how the repo is maintained. Split files, rename sections, or move information between `AGENTS.md` and `agents/*` as needed, while preserving useful guidance and removing stale duplication.

Required when relevant:

1. Update `packages/tailwind-merge/docs/*.md` (or the owning package's docs) for any user-visible behavior, API, version support, or limitation changes.
2. Update `AGENTS.md` whenever repository-wide agent workflow, repo conventions, required commands, or high-level guardrails change.
3. Update the relevant file in `agents/` whenever specialized architecture, workflow, CI, release, or testing guidance changes.
4. Do not regenerate the READMEs during normal development. The library `README.md` and the marked section of the repo-level `README.md` are intentionally generated as part of the version/release flow so visitors are routed to docs for the latest release.
5. Never reference repo files through `blob/main`/`raw/main`/`tree/main` URLs — they break whenever a file moves. Within the repo use relative links; where a link must be absolute (published docs, JSDoc, release notes), pin it to the latest release tag whose tree contains the file (e.g. `blob/v3.6.0/docs/...`, `blob/tailwind-merge@3.7.0/packages/tailwind-merge/docs/...`). Links pinned to a package's latest tag are re-pinned automatically at that package's next release by `scripts/update-pinned-links.mjs` (run in each publishable package's `version` lifecycle); links pinned to older tags are treated as deliberately historical and never touched. Two escape hatches for historical links that sit at the latest tag: changelog directories (`docs/changelog/`) are never scanned, and a link carrying the `twm-historical` query parameter (e.g. `blob/v3.6.0/docs/foo.md?twm-historical`, before any `#fragment`) stays untouched — GitHub ignores the parameter when serving the page.

Definition of done for every PR/change:

1. Code and tests are updated.
2. Relevant docs are updated in the same change set.
3. `AGENTS.md` and `agents/*` guidance is reviewed, with useful new context added and stale guidance removed whenever the change affects how agents should work in this repo.

## Quick Validation Matrix

All test paths below are relative to `packages/tailwind-merge/`; run single files with `pnpm --filter tailwind-merge test:watch tests/<file>`.

- Parser or modifier semantics: run `tests/modifiers.test.ts`, `tests/arbitrary-variants.test.ts`, `tests/experimental-parse-class-name.test.ts`.
- Class groups/conflicts/default config: run `tests/default-config.test.ts`, `tests/class-group-conflicts.test.ts`, `tests/tailwind-css-versions.test.ts`.
- Public API/types: run `tests/public-api.test.ts`, `tests/type-generics.test.ts`, and `pnpm --filter tailwind-merge test:types`.
- Release/package surface: run `pnpm --filter tailwind-merge build` and `pnpm --filter tailwind-merge test:exports`.
- Configurator, plugin core, or a plugin: run `pnpm --filter @tailwind-merge/configurator test` / `pnpm --filter @tailwind-merge/plugin-core test` / `pnpm --filter @tailwind-merge/vite test` / `pnpm --filter @tailwind-merge/next test` and the matching `test:types` script. A core or configurator change must run both plugin suites.
- Plugin build/packaging surface: run `pnpm --filter tailwind-merge build`, then the plugin's `build` and `test:exports` (`pnpm --filter @tailwind-merge/vite …` or `pnpm --filter @tailwind-merge/next …`).
- Repo-wide before finalizing: `pnpm lint`, `pnpm test:types`, `pnpm test` from the root.

More agent context in dcastil/tailwind-merge

One other file this repository gives its agents.