compile() and compileAst()

Core compilation functions for processing Tailwind CSS

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

css · string · required

The input CSS string containing Tailwind directives like @tailwind utilities, @theme, @variant, etc.

opts · CompileOptions

Optional compilation options

Show CompileOptions properties

base · string

Base directory for resolving file paths. Defaults to empty string.

from · string

Source file path for source map generation.

polyfills · Polyfills

Control which CSS polyfills to emit. Can be:

• Polyfills.None - No polyfills (default)
• Polyfills.AtProperty - Emit @property fallbacks
• Polyfills.ColorMix - Emit color-mix() fallbacks
• Polyfills.All - All polyfills enabled

loadModule · function

Function to load external modules (plugins and configs).

(id: string, base: string, resourceHint: 'plugin' | 'config') => Promise<{
  path: string
  base: string
  module: Plugin | Config
}>

loadStylesheet · function

Function to load external stylesheets for @import statements.

(id: string, base: string) => Promise<{
  path: string
  base: string
  content: string
}>

Return Value

sources · array

Array of source patterns discovered from @source directives.

{ base: string; pattern: string; negated: boolean }[]

root · Root

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

features · Features

Bitmask of features detected in the CSS:

• Features.AtApply - @apply was used
• Features.AtImport - @import was used
• Features.JsPluginCompat - @plugin or @config was used
• Features.ThemeFunction - theme() function was used
• Features.Utilities - @tailwind utilities was used
• Features.Variants - @variant was used
• Features.AtTheme - @theme was used

build · function

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.

buildSourceMap · function

Function to generate a source map for the compiled CSS.

(): DecodedSourceMap

Example Usage

Basic Usage

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

input · AstNode[] · required

Array of AST nodes from the CSS parser.

opts · CompileOptions

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.

build · 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

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)[]
}