compile() Compile a CSS string containing Tailwind directives into optimized CSS output.
function compile ( css : string , opts ?: CompileOptions ) : Promise <{ sources : { base : string ; pattern : string ; negated : boolean }[] root : Root features : Features build ( candidates : string []) : string buildSourceMap () : DecodedSourceMap }>
Parameters The input CSS string containing Tailwind directives like @tailwind utilities, @theme, @variant, etc.
Optional compilation options Show CompileOptions properties
Base directory for resolving file paths. Defaults to empty string.
Source file path for source map generation.
Control which CSS polyfills to emit. Can be:
Polyfills.None - No polyfills (default)Polyfills.AtProperty - Emit @property fallbacksPolyfills.ColorMix - Emit color-mix() fallbacksPolyfills.All - All polyfills enabled Function to load external modules (plugins and configs). ( id : string , base : string , resourceHint : 'plugin' | 'config' ) => Promise <{ path : string base : string module : Plugin | Config }>
Function to load external stylesheets for @import statements. ( id : string , base : string ) => Promise <{ path : string base : string content : string }>
Return Value Array of source patterns discovered from @source directives. { base : string ; pattern : string ; negated : boolean }[]
Root configuration extracted from source() parameters in @tailwind utilities. Can be:
null - No root specified'none' - Explicitly disabled via source(none){ base: string; pattern: string } - Explicit pattern Bitmask of features detected in the CSS:
Features.AtApply - @apply was usedFeatures.AtImport - @import was usedFeatures.JsPluginCompat - @plugin or @config was usedFeatures.ThemeFunction - theme() function was usedFeatures.Utilities - @tailwind utilities was usedFeatures.Variants - @variant was usedFeatures.AtTheme - @theme was used Function to generate CSS for a given set of candidates. ( candidates : string []) : string
Returns the compiled CSS string. Automatically caches results - if the same candidates are provided, returns the cached output without recompilation. Function to generate a source map for the compiled CSS. Example Usage Basic Usage
With Source Maps
With Custom Loaders
Incremental Builds
import { compile } from 'tailwindcss' const css = ` @theme { --color-primary: #3b82f6; --color-secondary: #8b5cf6; } @tailwind utilities; ` const compiler = await compile ( css ) // Generate CSS for specific classes const output = compiler . build ([ 'text-primary' , 'bg-secondary' , 'hover:text-white' ]) console . log ( output )
compileAst() Compile a pre-parsed AST instead of a CSS string. This is useful when you already have an AST from the CSS parser.
function compileAst ( input : AstNode [], opts ?: CompileOptions ) : Promise <{ sources : { base : string ; pattern : string ; negated : boolean }[] root : Root features : Features build ( candidates : string []) : AstNode [] }>
Parameters Array of AST nodes from the CSS parser.
Same options as compile() function. See above for details.
Return Value Returns the same structure as compile(), except the build() function returns AstNode[] instead of a string, and there is no buildSourceMap() function.
Function to generate an AST for a given set of candidates. ( candidates : string []) : AstNode []
Returns an array of AST nodes that can be further processed or converted to CSS using toCss(). Example Usage Basic AST Compilation
AST Manipulation
import { compileAst } from 'tailwindcss' import * as CSS from 'tailwindcss/css-parser' import { toCss } from 'tailwindcss/ast' const css = ` @theme { --color-brand: #ff6b6b; } @tailwind utilities; ` // Parse CSS to AST const ast = CSS . parse ( css ) // Compile the AST const compiler = await compileAst ( ast ) // Generate AST nodes for candidates const outputAst = compiler . build ([ 'text-brand' , 'flex' ]) // Convert back to CSS if needed const outputCss = toCss ( outputAst )
Types CompileOptions type CompileOptions = { base ?: string from ?: string polyfills ?: Polyfills loadModule ?: ( id : string , base : string , resourceHint : 'plugin' | 'config' , ) => Promise <{ path : string base : string module : Plugin | Config }> loadStylesheet ?: ( id : string , base : string , ) => Promise <{ path : string base : string content : string }> }
Polyfills Enum enum Polyfills { None = 0 , AtProperty = 1 << 0 , // Fallbacks for @property rules ColorMix = 1 << 1 , // color-mix() fallbacks All = AtProperty | ColorMix }
Features Enum enum Features { None = 0 , AtApply = 1 << 0 , // @apply was used AtImport = 1 << 1 , // @import was used JsPluginCompat = 1 << 2 , // @plugin or @config was used ThemeFunction = 1 << 3 , // theme() was used Utilities = 1 << 4 , // @tailwind utilities was used Variants = 1 << 5 , // @variant was used AtTheme = 1 << 6 // @theme was used }
DecodedSourceMap interface DecodedSourceMap { version : number sources : string [] names : string [] mappings : string sourcesContent ?: ( string | null )[] }