Fix Tailwind v4 and Root.js/Vite v7 compatibility

[jeremydw]

Tailwind v4's Vite plugin doesn't natively work with Root.js on the Vite dev server, specifically with the asset graph. After performing some research, there are two changes we can make to Root to fix the Vite dev server compatibility.

I worked with an AI to monkey patch the changes and tested out the fix. Below is the summary of the work involved.

1. Add a css (or some other name, e.g. injectDevServerCss) option to the RootConfig to signal to Root that additional CSS entrypoints need to be bundled.

---

Root.js PR: Vite 7 compatibility fixes

This document describes two changes needed in Root.js to support Vite 7+ and to
enable explicit CSS injection in dev mode (e.g. for Tailwind CSS v4).

Change 1: Add css config option for dev-mode CSS injection

Problem

In Vite's dev server, plain CSS imports like import './tailwind.css' are
side-effect-only imports. Vite strips these from the SSR module graph, so
Root.js's DevServerAsset.collectCss() never discovers them. This means CSS
files that are only imported (not referenced by a component's module graph) are
missing from the rendered HTML — no <link> tag is generated.

This is particularly problematic for Tailwind CSS v4, which uses a CSS entry
point (@import "tailwindcss") compiled by a Vite plugin (@tailwindcss/vite)
rather than injecting styles via JS. In production builds Vite's build pipeline
captures these through the manifest, so the issue is dev-only.

Prior attempts to fix this with Vite plugins (transformIndexHtml) failed
because tags injected by transformIndexHtml are added after SSR rendering
and bypass Root.js's CSP nonce injection (the Preact vnode hook that adds nonces
only runs during renderToString).

Solution

Add a new css property to RootUserConfig that accepts an array of CSS file
paths relative to the project root. During dev-mode rendering, these paths are
injected as <link rel="stylesheet"> tags with ?direct appended (which tells
Vite to serve raw CSS instead of a JS module wrapper). The tags are generated
alongside other CSS dependencies, so they automatically receive CSP nonces via
the existing rendering pipeline.

This option is a no-op during production builds, where Vite's manifest-based
build correctly handles CSS.

Files to change

1. src/core/types.ts — Add css to RootUserConfig

Add the css field to the RootUserConfig interface, after plugins:

/**
 * CSS files to inject as `<link>` tags during dev server rendering.
 *
 * In dev mode, Vite strips plain CSS imports (e.g. `import './foo.css'`)
 * from the SSR module graph because they are side-effect-only imports.
 * This means Root.js's `collectCss()` never discovers them. Use this
 * option to explicitly list CSS entry points that should be injected.
 *
 * Paths should be relative to the project root (e.g. `styles/tailwind.css`).
 * In dev mode, `?direct` is automatically appended so Vite serves the
 * compiled CSS instead of a JS module wrapper.
 *
 * This option has no effect during production builds, where Vite's build
 * pipeline correctly captures CSS imports through the manifest.
 */
css?: string[];

2. src/render/render.tsx — Inject CSS deps in renderComponent()

In Renderer.renderComponent(), after the await this.collectElementDeps()
call (which populates jsDeps and cssDeps), add:

// Inject CSS files from rootConfig.css for dev mode.
// In dev, plain CSS imports are stripped from Vite's SSR module graph,
// so they need to be explicitly injected. The ?direct param tells Vite
// to serve raw CSS instead of a JS module wrapper.
if (this.rootConfig.css && this.assetMap.moduleGraph) {
  for (const cssPath of this.rootConfig.css) {
    const normalizedPath = cssPath.startsWith('/') ? cssPath : '/' + cssPath;
    cssDeps.add(normalizedPath + '?direct');
  }
}

Why this.assetMap.moduleGraph? Only DevServerAssetMap has a
moduleGraph property. BuildAssetMap does not. This serves as a dev-mode
guard without requiring an explicit isDev flag.

Why ?direct? Without it, Vite serves CSS files as JavaScript modules
(wrapped in __vite__createHotContext + __vite__updateStyle for HMR). The
?direct query parameter tells Vite to respond with Content-Type: text/css
and the raw compiled CSS, which is what <link rel="stylesheet"> expects.

Why not use transformIndexHtml? Tags injected via Vite's
transformIndexHtml hook are added after Root.js's SSR rendering. The Preact
vnode hook that injects CSP nonces runs during renderToString(), so
post-render tags don't receive nonces. By adding CSS deps to the cssDeps set
before tag generation, the <link> tags are created via jsx("link", ...) and
automatically receive nonces through the existing code path.

Usage

// root.config.ts
export default defineConfig({
  css: ['styles/tailwind.css'],
  // ...
});

How to verify

1. Configure css in root.config.ts:

   export default defineConfig({
     css: ['styles/tailwind.css'],
   });

2. Start the dev server and inspect the HTML:

   • <link rel="stylesheet" href="/styles/tailwind.css?direct" nonce="..."> should appear in <head>
   • /@vite/client script should have a nonce

3. Verify in the browser:

   • Tailwind utility classes apply (check with DevTools)
   • HMR works for component changes

Test matrix

Scenario	Before fix	After fix
CSS in <link> (dev)	Missing for plain CSS imports	✅ Present via css config
CSS nonce (dev)	N/A (tag missing)	✅ Nonce injected
Production build CSS	✅ Works (manifest)	✅ No change (css is no-op)
Production build elements	✅ Works	✅ No change
Vite 5/6 compat	✅ Works	✅ No regression (asset-type modules don't exist)

[jeremydw]

When asking why we can't just use the normal approach for using Tailwind:

The standard guide works because normal Vite apps are client-side SPAs. The key step is:

"Ensure your main entry file (e.g., src/main.tsx) imports the CSS file"

That import './index.css' in a client entry point is what makes it work — Vite's client-side HMR system intercepts the import, compiles Tailwind, and injects the styles into the page via JavaScript at runtime. No tag is ever needed.

Root.js can't do this because it's an SSR framework. There is no client-side entry point like main.tsx. Here's what happens:

1. Root.js renders HTML on the server via renderToString()
2. It needs to emit actual <link rel="stylesheet"> tags in the HTML response
3. To know which CSS to include, it walks Vite's SSR module graph looking for CSS dependencies
4. But Vite strips import tailwind.css from the SSR module graph — it's a side-effect-only import with no JS export, so Vite considers it irrelevant to SSR
5. Result: Root.js never discovers the CSS file, no <link> tag is emitted, no styles

The @tailwindcss/vite plugin handles compilation (turning @import "tailwindcss" into actual CSS), but it doesn't control how the CSS gets into the HTML. In an SPA, Vite's HMR client handles that. In Root.js SSR, that's Root.js's job — and it can't find the CSS in the SSR module graph.

The css config option simply tells Root.js: "these CSS files exist, please emit tags for them." The compilation is still handled by @tailwindcss/vite as normal.

And, we can't import Tailwind into styles/global.scss (for example) because it needs to be processed by the Tailwind plugin.

[stevenle]

is ?direct a hallucination? i don't see any mentions of it on the vite website. is there a vite plugin that tailwind users can use instead of having to do special server-side things on the root side?

is styles/tailwind.css a dynamically generated file? if it's a static file, can it be uploaded to public/tailwind.css?

pardon the questions, i haven't used tailwind.

[jeremydw]

• The Vite plugin for Tailwind is @tailwindcss/vite. I tried to figure out how to get it to work with Root, but it insisted that the reason it wouldn't work without changes to Root are outlined in Fix Tailwind v4 and Root.js/Vite v7 compatibility #925 (comment)

• For ?direct I think it's an internal Vite thing, it's referred to here: Undocumented ?direct query string to make SASS work with npm run dev vitejs/vite#12967

Not sure if there's a better way, i.e. a way to avoid using ?direct. IIUC ?direct should be used so Vite serves CSS directly rather than a JS module wrapper with the compiled Tailwind inside of it.

I think what we can do is set up an examples/tailwind and get everything tested + working there.

[stevenle]

yeah let's start with a tailwind example so i can help troubleshoot. i would prefer not using undocumented vite features, there are some vite options for removing the js wrapper, but i'm not entirely sure if that'll solve the problem.

[stevenle]

per chat i think we should consider a root-tailwind plugin that automatically applies the vite plugin and configures any necessary extra steps to get it working with root. only difference with other frameworks is that we may need the user to declare the tailwind .css file entrypoint to inject on pages (whereas other frameworks can handle it automatically).

[jeremydw]

Here's the workaround in the meantime:

// in routes/index.tsx

// import your tailwind entrypoint
import '@/styles/tailwind.css';

// directly load the tailwind entrypoint in dev mode
{import.meta.env.DEV && (
  <link rel="stylesheet" href="/styles/tailwind.css" />
)}

// in root.config.ts

// load the tailwind plugin
  vite: {
    plugins: [tailwindcss()],

[jeremydw]

Tailwind example:
https://github.com/blinkk/rootjs/compare/examples/tailwind

[stevenle]

sharing some codex recommended suggestions:

[jeremydw]

Finding 1 is what was suggested in my AI research too; it suggested calling the option css on the Root config (but I think it should be named something like devServerCss or similar) and then it should auto-inject correctly.

Finding 2 sounds good/better to me if we can get away without introducing a new Root config option though.

[stevenle]

i actually think it should be injected in both dev and prod to preserve rendering behavior in both environments, e.g. injecting a main.scss or global.scss. we currently recommend this as something like import '@/styles/main.scss' in baselayout.tsx but if baselayout imports a child component that has css deps then the import order gets a little wonky. having a css injection configuration helps with the import order problem since the configured injection would be rendered before any other css deps are calculated via the vite module graph.

[stevenle]

i've started the first 2 codex tasks, will review their suggestions.