Tailwind CSS v4 and Svelte 5

[philipp-spiess]

We're working on getting Tailwind CSS v4 ready for a release and need some guidance on how to best integrate Svelte <style> tag support into our Vite extension.

Tailwind CSS users use features like the @apply directive that allows you to create custom CSS classes and fill them up with Tailwind CSS utilities directly from within their scoped Svelte components:

<style>
  .link {
    @apply text-underline font-bold;
  }
</style>

<a class="link">Click me</button>

In order to make this work in Tailwind CSS v4, we need the ability to transform the stylesheets inside the Svelte <style> tag.

There are two ways we can intercept these stylesheets:

1. We can use a svelte-preprocess to process the Stylesheets before the Svelte compiler sees them...
2. ...or we can use a Vite transform hook to intercept the styles afterwards.

Pre-processing

This was the approach necessary with our earlier alpha experiments as Svelte 4 was very strict about what CSS is allowed inside <style> tags and would make it impossible to make our syntax pass through (we, for example, rely heavily on CSS nesting).

Being able to process the styles before Svelte sees it also works great with features like our newly introduced @import "…" reference option which will remove all non-Tailwind-CSS-config settings from the imported stylesheets so the Svelte compiler won't see (and warn) about any unexpected global styles when importing your Tailwind CSS theme.

In order to register the pre-processor, we can either have the Vite plugin automatically inject it or expose the pre-processor as a separate plugin (@tailwindcss/svelte). The latter option is a bit more initial setup work but allows static analysis tools to also detect the extension.

Post-processing

This is our preferred approach and the approach that works for our existing Vue and Astro integration as well. In this case, we rely on Vite's transform hooks.

The good news is that it seems like Svelte 5 doesn't suffer from the same strictness as Svelte 4 anymore. There are still some limitations though, the most pressing one is that it's not possible to import your configuration using the @import "…" reference API without getting warnings.

This is because the @import is seemingly resolved before the Svelte compiler sees it which will create a CSS like this that might now contain style rules that Tailwind CSS will later throw out. Svelte doesn't know about the post-process step and will only warn about unused selectors:

@import "./tailwind.css" reference;

becomes

@media reference {
  /* These rules will be removed by the Tailwind CSS compiler */
  html {
    box-sizing: border-box;
  }
}

In order for us to use this approach, we'd need a way to silence these warnings. One option to consider is maybe enforce a <style lang="tailwindcss"> attribute on all styles that Tailwind CSS should process so that Svelte knows about the post-processing step.

FAQ

What about static analysis tools?

One issue that both approaches have right now is that when running against the static analysis tool (npx sv check), the analyzer doesn't know about Tailwind CSS. This results in warnings like the following when e.g. using a @theme directive for config:

Warn: Unknown at rule @theme (css)
<style>
  @theme {
    --color-red-500: #f00;

How does this work with scoping?

For the features we want to support inside <style> blocks, we will operate on the classes passed to the Tailwind CSS compiler. In case of using a post-processor, this means the input class names will already be scoped correctly. Some utilities might be creating new rules. These, however, will be nested under the existing class name using CSS nesting.

Resource reloading?

We require @import to work according to the spec. If no other pre-processor is running, Tailwind CSS will resolve imports and return the dependencies correctly in both scenarios.

What about utility class generation?

It is recommended to set up a global .css file that will be used to initialize the CSS variables from your Tailwind CSS theme and that contains all utility classes. For this, we use a regular transform in our Vite plugin to scan utilities being used (by reading all modules) and to transform .css files. This already works and is unrelated to Svelte.

@tailwind utilities, the placeholder to generated utility classes, is not supported within Svelte <style> tags.

Open Question

We'd like your input to align on an approach to choose for processing Tailwind CSS styles inside <style> tags going forward, more specifically:

• Would you want us to go with a pre or post-processing approach? If it's the latter, what can we do to silence runtime warnings by the Svelte compiler like the one outlined above?
• How can we make the static analysis tool aware of Tailwind CSS and avoid issues like the one in css_nesting_selector_invalid_placement false positive using tailwind 4 import reference #14563?

[dominikg]

I would prefer the post approach, splitting it in two and requireing a svelte preprocessor makes the pipeline more complex and slower too.

As far as i understand this would limit tailwind v4 support to svelte5, as the svelte4 compiler is more strict regarding css syntax and can't handle @apply for example.

v5 passes through @import and @apply so you should be able to pick them up from svelte compiled output, the component css is actually a virtual module but thats very similar to how vue handles it.

If you have a working testsuite with svelte, vite and tailwind v4, it would be great to hook that up to https://github.com/sveltejs/svelte-ecosystem-ci and https://github.com/vitejs/vite-ecosystem-ci once you enter rc phase so we can continue to monitor compatibility.

[dominikg]

hmm, why is that in the output of @import .. reference ? i thought that was "just" to pull in referenced configuration values of that style block? (kind of like scss mixins and variables). It should not lead to extra css rules being added to that style block, esp. not ones that are global.

vitePreprocess runs vites css pipeline and that would include tailwind v4. Now it is possible that you don't even have to use vitePreprocess at all for style if you use tailwind v4, but if there are usecases where users might want to combine it with other postcss tools or scss (:grimacing:) then this is needed, and it would also be a strange limitation.

do you have a repo to share where this is set up?

[philipp-spiess]

why is that in the output of @import .. reference?

That's because in the case of vitePreprocess, the @import is resolved by the Vite postcss setup before the transformer hooks see it. When Tailwind sees the @media reference { ... } that's going to be inserted because of that reference suffix, it will do the cleanup, but unfortunately that's after the Svelte compiler sees it.

So the flow is something like:

1. Get raw <style> content.
2. Pass it through Vite's preprocessCSS() API. This will inline the imported stylesheets
3. Validate it with the Svelte container.
4. Process emitted CSS chunks via Vite transform hooks.

vitePreprocess runs vites css pipeline and that would include tailwind v4.

Unfortunately it doesn't. When using vitePreprocess, the preprocessor step uses the preprocessCSS() API.

This API will only run css plugins configured in Vite and not transform hooks. That's something that's apparently to change: vitejs/vite#18030

Agree with you that you might not vitePreprocess in most cases but also agree that this is a strange limitation.

do you have a repo to share where this is set up?

Sure: https://github.com/philipp-spiess/tw-svelte

This includes two dev builds of Tailwind from this branch: tailwindlabs/tailwindcss#15436

[dominikg]

cc @bluwy

any suggestions?

is there a way for tailwind to reference these files without using @import ?

[adamwathan]

Would it help if we also supported something like @reference "file.css" as an alternate syntax to avoid the import being processed?

[dominikg]

that could do:

https://svelte.dev/playground/hello-world?version=5.15.0#H4sIAAAAAAAAA3WPwUrEMBRFfyW-TWcgbek2xjLu_AfjoqZ3aCGTlOQ5OpT-uySizoCuAofz7s1dyQ8nkKInOBfEe4huFDuMM2Pck6Tj7JBIPa_ElyV7GZD8vnpcliad4Tiz1yHhL26DZ3hOpEgnG-eFe-MNO7DIungQVemt7o3X7a_h9dT1X_9as7jd6XbqeuN14otDCTlEHBHhLUTVtDzhhMamlKMMT51Y82vYBheiEuch7uq6WHVBMmLcF3cr3SWXJDE-mBTHN2zyn-k_XbfLr_HV8NvMl-0T4zC8tHgBAAA= (see css output tab, the at-rule is preserved and present in the css AST)

there is prior art with scss @use https://sass-lang.com/documentation/at-rules/import/ too

[benmccann]

I may be the odd man out here, but my preference would be to do something like the following:

import { vitePreprocessors } from '@sveltejs/vite-plugin-svelte';

export default 
  preprocess: vitePreprocessors() // returns everything found in plugin.api.preprocessor
};

That would also solve sveltejs/language-tools#2321

Assuming the approach works, it likely wouldn't require much code change on your part. I'm just about to leave for vacation, but you could try prototyping it. I do think in either case though that you really should generate source maps.

[dominikg]

this approach would only work for preprocessors that don't share internal state with the plugin that provided them and requires a lot of overhead as you have to completely resolve the vite config to get all plugins instances.
The easier solution for this case is that the plugin does not use plugin.api.sveltePreprocess but a separate export for the preprocessor and users add that to their svelte config.

but again ideally tailwind v4 does not require a svelte preprocessor at all and works completely in a post step on the emitted css.

there is one limitation to this: emitted css requires compilerOptions.css = 'external' which works for application code and is our default, but during development prebundled libraries have to use 'injected' which puts the css in string literals of the js module, preventing any css post steps from changing it, so libraries asking users to add their code to the applications tailwind config would not work unless tailwinds css processing integrates naturally with vites css pipeline andusing vite-plugin-sveltes vitePreprocess transforms the injected css.