astro add tailwind installs incompatible @tailwindcss/vite (build fails on Astro 6 default rolldown-vite)

[FunksterOne]

What version of astro are you using?

6.2.1 (with bundled vite 7.3.2)

What package manager are you using?

npm

What operating system are you using?

Windows 11 (also seen on macOS — see related vitejs/vite#22322)

Describe the Bug

Running astro add tailwind (the documented way to install Tailwind per the AI tools guide and integration docs) on a fresh Astro 6 project installs @tailwindcss/vite@^4.2.4 and registers it as a Vite plugin. The resulting setup fails to build:

[ERROR] [vite] ✗ Build failed in 1.10s
[@tailwindcss/vite:generate:build] Missing field `tsconfigPaths` on BindingViteResolvePluginConfig.resolveOptions
file: src/styles/global.css
  Stack trace:
    at makeBuiltinPluginCallable (file:///.../node_modules/rolldown/dist/shared/normalize-string-or-regex-...)
    at oxcResolvePlugin (file:///.../node_modules/vite/dist/node/chunks/node.js)
    at @tailwindcss/vite/dist/index.mjs

This is the same root cause as vitejs/vite#22322, where the original reporter concluded it is an Astro-side issue rather than Vite. As of the date this is filed, no corresponding issue exists in this repo.

What's the expected result?

astro add tailwind should produce a working setup — either by installing the PostCSS variant (@tailwindcss/postcss) when rolldown-vite is in use, or by warning the user.

What's the actual result?

astro add tailwind succeeds and modifies config, but npm run build then fails immediately on any Tailwind-using stylesheet.

Reproduction

npm create astro@latest demo -- --template minimal --typescript strict --yes
cd demo
npm install
npx astro add tailwind --yes
mkdir -p src/styles
echo '@import "tailwindcss";' > src/styles/global.css
cat > src/pages/index.astro <<'EOA'
---
import "../styles/global.css";
---
<div class="text-blue-500">hi</div>
EOA
npm run build

Workarounds

Option 1 — switch to PostCSS:

npm uninstall @tailwindcss/vite
npm install @tailwindcss/postcss

postcss.config.mjs:

export default { plugins: { "@tailwindcss/postcss": {} } };

astro.config.mjs: remove the @tailwindcss/vite plugin.

This builds fine.

Option 2 — pin Vite to v6 (per miksin/dev-log#34).

Suggested fix

Either:

1. Update astro add tailwind to install @tailwindcss/postcss and write postcss.config.mjs instead of @tailwindcss/vite, until the latter supports the rolldown-bundled Vite that Astro 6 ships with.
2. Detect the incompatibility during astro add tailwind and print a warning + recommendation.

Versions tested

• astro@6.2.1
• @tailwindcss/vite@4.2.4
• tailwindcss@4.2.4
• vite@7.3.2 (transitive via Astro)

Related

• Vite 8.0.10 public resolver APIs produce incomplete rolldown plugin configs vitejs/vite#22322 (closed — concluded Astro-side)
• fix: pin vite to v6 to resolve tailwindcss build error miksin/dev-log#34 (closed — workaround was pinning Vite to v6)

[astrobot-houston]

• Reproduced: Yes — following the exact reproduction steps with npm causes npm install to hoist Vite 8.0.10 (instead of Astro's required Vite 7), which then fails at build time with the reported Missing field 'tsconfigPaths' on BindingViteResolvePluginConfig.resolveOptions error.
• Exploration: Yes — View branch
• Priority: P3: minor bug. This only affects users who use npm (not pnpm or yarn) and run astro add tailwind. The workaround is straightforward: add "overrides": { "vite": "^7" } to package.json, or use the PostCSS variant as described in the issue. Users of pnpm are unaffected because pnpm's strict dependency resolution prevents Vite 8 from being hoisted.

The root cause is not that Astro 6 ships rolldown-vite (it does not — Astro 6.2.1 uses standard Vite 7.3.2 with Rollup). The problem is that @tailwindcss/vite@4.2.4 declares "vite": "^5.2.0 || ^6 || ^7 || ^8" as a peer dependency. When using npm's flat node_modules layout, npm resolves the latest matching version (Vite 8.0.10) and hoists it to the project root, overriding Astro's vite: ^7.3.2 requirement. Vite 8 uses rolldown instead of rollup internally, and @tailwindcss/vite is not yet compatible with it, producing the build error. Astro's existing tailwind test suite passes because it uses pnpm, which correctly resolves Vite 7.

I found a potential fix for this issue. The fix adds a "vite": "^7" override to package.json during astro add tailwind, using the same updatePackageJsonOverrides mechanism already used by the Cloudflare adapter in the same file (packages/astro/src/cli/add/index.ts:238-243). The change is a 5-line addition at line 268 in packages/astro/src/cli/add/index.ts.

Full Triage Report

Reproduction

Followed the exact reproduction steps from the issue using npm:

# Created minimal Astro project with:
# - astro@^6.2.1
# - @tailwindcss/vite@^4.2.4
# - tailwindcss@^4.2.4
npm install  # npm hoisted vite@8.0.10 to node_modules/vite/
npx astro build  # FAILS with the reported error

Confirmed: npm install resolved vite@8.0.10 (not 7.3.2) because @tailwindcss/vite has peerDependencies: { "vite": "^5.2.0 || ^6 || ^7 || ^8" }, and npm picks the latest matching version.

Vite 8.0.10 depends on rolldown@1.0.0-rc.17 (instead of rollup), which is the source of the BindingViteResolvePluginConfig.resolveOptions error.

Key finding: Astro 6 does NOT use rolldown-vite

Contrary to the issue title, Astro 6.2.1 uses standard Vite 7.3.2 with Rollup as the production bundler. The rolldown references in the error stack trace come from Vite 8 being incorrectly hoisted by npm.

• packages/astro/package.json declares "vite": "^7.3.2"
• Vite 7.3.2's runtime dependencies include "rollup": "^4.43.0" (no rolldown)
• No references to rolldown-vite exist anywhere in the Astro monorepo

Diagnosis

The astro add tailwind command is special-cased in packages/astro/src/cli/add/index.ts:

• Line 1042-1048: Overrides dependencies to install @tailwindcss/vite ^4.0.0 and tailwindcss ^4.0.0
• Line 409-410: Adds @tailwindcss/vite as a Vite plugin (not an Astro integration)

The Cloudflare adapter already handles this exact npm hoisting problem by calling updatePackageJsonOverrides({ overrides: { vite: '^7' } }) at line 238-243, which adds "overrides": { "vite": "^7" } to the user's package.json. The tailwind code path lacks this protection.

Fix

Added the same updatePackageJsonOverrides call to the tailwind branch in packages/astro/src/cli/add/index.ts, right after the CSS scaffolding block (after line 267). This ensures that when a user runs astro add tailwind, their package.json gets a "vite": "^7" override that prevents npm from hoisting Vite 8.

Existing tests: The tailwind build test (packages/astro/test/tailwindcss.test.ts) continues to pass after the change.

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

[matthewp]

Please follow the issue template.

[github-actions]

Hello @FunksterOne. Please provide a minimal reproduction using a GitHub repository or StackBlitz. Issues marked with needs repro will be closed if they have no activity within 3 days.