CodeVetter · Repo Unpack · Extension points
tailwindlabs/tailwindcss
The system has three distinct extension tiers. Tier one is CSS-native: `@utility`, `@custom-variant`, and `@theme` register directly into the design system with no JS. Tier two is the JS plugin API, preserved wholesale from v3 in `compat/plugin-api.ts` and loaded via `@plugin`. Tier three is internal: the `Utilities` and `Variants` classes are plain registries with `static`/`functional` methods that core code and plugins call identically, and the upgrade tool has its own ordered `DEFAULT_MIGRATIONS` array. Adding a new template language to the scanner is a matter of one new pre-processor module plus one match arm.
- `Utilities` is the utility registry — `static(name, compileFn)` and `functional(name, compileFn, options)` push into a `DefaultMap<string, Utility[]>`, with a parallel `completions` map driving IntelliSense suggestions.
- `Variants` is the variant registry, offering `static`, `functional`, and `fromAst(name, ast, designSystem)` (which powers `@custom-variant` with a body), and tracking `compounds`/`compoundsWith` bit flags that decide which variants may be composed with which.
- `@utility` is the CSS-native extension point: `createCssUtility(node)` turns the at-rule into a `(designSystem) => void` registration function, with explicit validation that functional utilities end in `-*` and that `@utility` is never nested.
- `@custom-variant` registrations are topologically sorted before application via `topologicalSort(customVariantDependencies, { onCircularDependency })`, so variants may reference each other and circular references produce a rendered CSS error rather than a stack overflow.
- `buildPluginApi` is the JS plugin extension surface, exposing `addBase`, `addVariant`, `matchVariant`, `addUtilities`, `matchUtilities`, `addComponents`, `matchComponents`, and a `theme()` accessor, with name validation that rejects non-single-class selectors and non-lowercase-leading utility names.
- `@plugin` supports typed options passed as a declaration body — `CssPluginOptions` values are parsed from the declaration text into JSON primitives (`null`, `true`, numbers, comma-separated lists) before being handed to the plugin factory.
- `applyCompatibilityHooks` is the single seam where all v3 behavior is grafted on — it registers `darkModePlugin`, `registerContainerCompat`, `registerLegacyUtilities`, `registerScreensConfig`, and `registerThemeVariantOverrides`, keeping legacy concerns out of core.
- `DesignSystem.storage` is an explicit general-purpose extension slot — a `Record<symbol, unknown>` documented as requiring unique symbol keys to avoid collisions; the canonicalization code uses it via `prepareDesignSystemStorage` and `UTILITY_SIGNATURE_KEY`.
- Adding a new template language to the scanner requires two edits: a new module in `crates/oxide/src/extractor/pre_processors/` re-exported from `mod.rs`, and a new extension arm in the `pre_process_input` match statement.
- The extractor is itself a pluggable set of state machines all implementing the `Machine` trait — `ArbitraryPropertyMachine`, `ArbitraryValueMachine`, `NamedUtilityMachine`, `NamedVariantMachine`, `ModifierMachine`, `StringMachine`, and others — which `main.rs` can benchmark individually via `_run_machine::<T>`.
- The upgrade tool's template codemods are an ordered array `DEFAULT_MIGRATIONS: Migration[]` where each entry is `(designSystem, userConfig, rawCandidate) => string`; order is load-bearing, flagged by the inline comment that `migrateVariantOrder` must run before variant-modifying migrations.
- CSS-level codemods are a parallel, separately-composed pipeline in `codemods/css/` (`migrate-at-apply`, `migrate-at-layer-utilities`, `migrate-import`, `migrate-media-screen`, `migrate-preflight`, `migrate-tailwind-directives`, `migrate-theme-to-var`, `migrate-variants-directive`), each with a co-located test file.
- The CLI command table is a literal dispatch in `run()` — `command === 'build'` and `command === 'canonicalize'` — with options merged from `build.options()` and `sharedOptions`, so a new subcommand means a module exporting `options()`/`handle()` plus one branch.
- `internal-example-plugin` is a workspace package existing purely as a plugin-resolution fixture, consumed as a devDependency by `@tailwindcss/postcss` tests.