Skip to content

oxfmt: Tailwind CSS initialization takes 3+ seconds #18072

Description

@Boshen

Summary

The first call to format() with experimentalTailwindcss enabled takes 3+ seconds on macOS and even longer on Windows (causing CI timeout at 10 seconds).

CI failure: https://github.com/oxc-project/oxc/actions/runs/21063444575/job/60575013233

Root Cause Analysis

Investigated prettier-plugin-tailwindcss source code. The slow initialization happens in getTailwindConfig():

1. Prettier config resolution (config.ts:37)

let [configDir, configPath] = await resolvePrettierConfigPath(options.filepath)
// Internally calls prettier.resolveConfigFile() which walks up directory tree

2. Tailwind module resolution (config.ts:44)

let [mod, pkgDir] = await resolveTailwindPath(options, inputDir)
// Dynamically imports the entire tailwindcss package

3. Design system initialization (v4.ts:71)

let design = await mod.__unstable__loadDesignSystem(css, { ... })
// Creates jiti instance, reads CSS, initializes the design system

The Issue in oxfmt

In apps/oxfmt/src-js/libs/prettier.ts:

export async function sortTailwindClasses({ filepath, classes, options = {} }) {
  const tailwindPlugin = await loadTailwindPlugin();  // ✓ cached
  // ...
  const tailwindContext = await tailwindPlugin.getTailwindConfig(configOptions);  // Expensive on first call!
  // ...
}

While prettier-plugin-tailwindcss has internal caching (pathToApiMap with 10s TTL), the first call still runs all expensive setup:

  • Prettier config resolution: ~200-500ms (Windows)
  • Tailwind dynamic import: ~200-500ms
  • Design system init: ~500-1000ms
  • Total: ~1-2s (macOS), 10s+ (Windows CI)

Proposed Solutions

Option 1: Warmup during initialization

Pre-call getTailwindConfig with a dummy filepath during module load to warm the cache before any real formatting happens.

Option 2: Cache the Tailwind context in oxfmt

Store the result of getTailwindConfig and reuse it across calls (with same options).

Option 3: Skip unnecessary work for oxfmt's use case

Since oxfmt doesn't support custom Tailwind configs, we could:

  • Skip resolvePrettierConfigPath() entirely
  • Use the bundled tailwindcss-v4 directly without resolution

Observed Timings

  • macOS (arm64): ~3.1 seconds for first test
  • Windows (CI): >10 seconds (test timeout)

Affected Test

apps/oxfmt/test/tailwindcss/tailwindcss.test.ts - first test times out on Windows CI

Activity

  1. Boshen commented on Jan 16, 2026

    @Boshen
    MemberAuthor

    Additional Root Cause Analysis from prettier-plugin-tailwindcss

    After investigating the source code at https://github.com/tailwindlabs/prettier-plugin-tailwindcss, here are the deeper root causes:

    1. Top-Level Await Blocking Initialization (Main Culprit)

    In src/index.ts:20:

    let base = await loadPlugins()

    This eagerly loads all plugins at module initialization time. The loadPlugins() function:

    • Loads 8+ third-party plugins sequentially (astro, liquid, marko, twig, hermes, oxc, pug, svelte)
    • Loads 8 "compatible" plugins sequentially (css-order, organize-attributes, multiline-arrays, sort-imports variants, jsdoc)
    • Each uses await loadIfExistsESM() which tries to dynamically import plugins that may not exist

    Status: PR #420 addresses this by implementing lazy loading.

    2. Per-File Config Caching Instead of Per-Directory

    The cache key in config.ts is filePath, meaning:

    • 100 files in the same directory = 100 separate cache entries
    • Sibling files miss the cache entirely

    Status: PR #432 fixes this with directory-based caching (24% improvement on large codebases).

    3. Jiti Instance Created Without Caching (v4)

    In src/versions/v4.ts:51-54:

    let jiti = createJiti(import.meta.url, {
      moduleCache: false,  // No caching!
      fsCache: false,      // No caching!
    })

    4. Expiring Caches with 10-Second TTL

    All caches use expiringMap(10_000) (10 seconds), which is problematic for longer formatting sessions.


    Upstream Status

    • Issue #430 - Public API request for oxfmt (maintainer has started work on feat/public-api branch)
    • PR #420 - Remove top-level await (in progress)
    • PR #432 - Directory-based caching
  2. added
    A-formatterArea - Formatter (oxfmt). Add F-* labels for details
    on Jan 20, 2026
  3. added a commit that references this issue on Jan 21, 2026
    10f37cd
  4. added a commit that references this issue on Jan 21, 2026
    7e6c15b
  5. Dunqing commented on Jan 21, 2026

    @Dunqing
    Member

    I think this one should still open because #18339 only increased the test timeout to avoid test failures. The root causes are listed in the PR description.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    A-formatterArea - Formatter (oxfmt). Add F-* labels for details

    Type

    No type

    Fields

    Priority

    None yet

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions