Configuration

Tailwind v4 is configured primarily through CSS at-rules. The legacy tailwind.config.js configuration still works through the v3 compat layer.

CSS at-rules

| Directive | Purpose | Implementation | | ---------------------------------------- | --------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | --- | ------------------------------------------ | ----------------------------------------------- | | @import "tailwindcss" | Import the framework's index, which pulls in preflight, theme, and utilities. | packages/tailwindcss/index.css; resolved by at-import.ts. | | @import "tailwindcss" prefix(tw) | Apply a class prefix. | Parsed in parseCss, stored on the design system. | | @import "tailwindcss" theme(reference) | Reference the theme without emitting its tokens. | Parsed in parseCss; flips the reference flag. | | @reference "…" | Import a stylesheet for theme/variant access only — no CSS is emitted from the imported file. | Handled in parseCss. | | @theme { … } | Declare theme tokens. | Parsed in parseCss; tokens added to Theme. | | @theme reference { … } | Declare reference-only tokens (no :root emission). | Same, with ThemeOptions.REFERENCE. | | @theme inline { … } | Inline values into utilities instead of var(--…). | Same, with ThemeOptions.INLINE. | | @theme static { … } | Always emit on :root, even if no utility consumed the value. | Same, with ThemeOptions.STATIC. | | @theme default { … } | Mark these tokens as defaults that user @theme blocks can override without warning. | Same, with ThemeOptions.DEFAULT. | | @utility name { … } | Define a static utility. | createCssUtility(node) in utilities.ts. | | @utility name-* { … } | Define a functional utility (the trailing -* is required). | Same. | | @variant name (selector) | Define a variant from a selector list. | parseCss walk, dispatched to Variants.static. | | @variant name { … } | Define a variant from a body containing @slot. | Variants.fromAst(...). | | @variant name { … } (inside a rule) | Apply a variant to the wrapping rule's body. | substituteAtVariant in variants.ts. | | @custom-variant | Same as the body-form @variant outside a rule. | parseCss walk. | | @apply class1 class2 | Inline another utility's rules. | substituteAtApply in apply.ts. | | @plugin "./plugin.js" | Load a JavaScript plugin. | Adapter's loadModule; compat layer in compat/. | | @config "./tailwind.config.js" | Load a v3-style JS config. | Same loader path; bridged through apply-config-to-theme.ts. | | @source "./glob" | Add a source-detection glob. | parseCss walk; passed to the scanner. | | @source not "./glob" | Negate a source-detection glob. | Same, with negated: true. | | @source inline("class names") | Inline a list of always-emit class names. | Same. | | @layer base | components | utilities | … | Force CSS into a particular cascade layer. | Standard CSS; handled during AST normalization. | | @tailwind utilities | Mark the position where utilities should be inserted (legacy form, still supported). | parseCss walk; replaced in build(). |

The full list of recognized at-rules lives in parseCss inside packages/tailwindcss/src/index.ts.

CSS functions

Function	Purpose
theme(--color-red-500)	Look up a theme value by namespace + key.
theme(spacing.4)	Legacy v3-style theme path (translated through compat).
--spacing(4)	Resolve a value through the --spacing namespace.
--alpha(value, modifier)	Apply an opacity modifier to a value.
--value(...) (inside @utility)	Bind a positional value parameter for a functional utility.
--modifier(...) (inside @utility)	Bind the modifier slash parameter.

Implemented in packages/tailwindcss/src/css-functions.ts.

CLI flags (tailwindcss build)

Defined in packages/@tailwindcss-cli/src/commands/build/index.ts:

Flag	Type	Default	Description
--input, -i	string	(stdin)	Input CSS file path.
--output, -o	string	-	Output file or stdout.
--watch, -w	boolean / always	false	Re-build on change. always keeps watching after stdin closes.
--minify, -m	boolean	false	Optimize and minify via Lightning CSS.
--optimize	boolean	false	Optimize without minifying.
--cwd	string	.	Project base directory.
--map	boolean / string	false	Generate a source map.
--help, -h	boolean	—	Show usage.

Plugin/adapter options

@tailwindcss/postcss

type PluginOptions = {
  base?: string; // default: process.cwd()
  optimize?: boolean | { minify?: boolean }; // default: NODE_ENV === 'production'
  transformAssetUrls?: boolean; // default: true
};

@tailwindcss/vite

type PluginOptions = {
  optimize?: boolean | { minify?: boolean }; // default: NODE_ENV === 'production'
};

@tailwindcss/webpack

type LoaderOptions = {
  base?: string; // default: process.cwd()
  optimize?: boolean | { minify?: boolean }; // default: NODE_ENV === 'production'
};

@tailwindcss/upgrade

CLI flags only:

Flag	Description
--config, -c	Path to a v3 config file (otherwise auto-detected).
--force, -f	Skip the clean-git-worktree check.
--version, -v	Print version.
--help, -h	Print usage.

Environment variables

Variable	Effect
DEBUG	When set to anything truthy, every adapter logs Instrumentation spans to stderr. See packages/@tailwindcss-node/src/env.ts.
NODE_ENV	Controls default optimize: true/false in the adapters and the PostCSS plugin.
RUST_LOG	Enables tracing output in the Rust scanner. Set to e.g. tailwindcss_oxide=debug.
NODE_PATH	Honored by the standalone CLI (v4.2.3 change, PR #19617).
FEATURES_ENV	Inputs to the build cache key in turbo.json — used by maintainers when cutting feature-flagged builds.
RUSTUP_HOME	Passed through to Rust subtasks (globalPassThroughEnv in turbo.json).

File-system controls

• .gitignore, .tailwindcssignore, .ignore are all honored by the scanner via the vendored crates/ignore/ crate.
• The Rust scanner's auto_source_detection.rs defines a binary-extension exclusion list that always applies, even without an .ignore file.