skip to content

In Tailwind CSS v4, why does `@apply` fail inside a Vue or Svelte `<style>` block or a CSS Module, and what does `@reference` fix?

level: middleimportance: should knowfreq 12%

answer

  1. each block built on its own
  2. an empty theme in that compile
  3. import for lookup, emit nothing
  4. a path to the main stylesheet
  5. or skip it with var()

basics

~20 s

In Tailwind CSS v4, each component style block and CSS Module is compiled separately, without your main stylesheet's theme, custom utilities or custom variants. @reference loads those definitions for lookup without emitting any CSS; plain var(--color-…) references sidestep it for single values.

solid answer

~40 s

Build tools process every CSS Module and every Vue, Svelte or Astro `<style>` block as its own stylesheet, so Tailwind compiles each one without the main file's `@theme`. `@apply bg-civic-600` then fails — Tailwind even asks whether you are missing `@reference` — and custom variants from the main file are invisible. `@reference "../app.css"` loads that file's theme variables, custom utilities and custom variants for lookup only and emits none of its CSS; `@reference "tailwindcss"` is enough with no customisations. Writing `@import` there instead would copy the whole framework output into every component. Tailwind's own advice is to avoid such blocks, or to use theme variables such as `var(--color-civic-600)`, which needs no Tailwind processing — fifty modules otherwise mean fifty Tailwind runs.

code

html · 15 lines
html
<!-- PermitStatus.svelte -->
<span class="status"><slot /></span>

<style>
  @reference "../app.css";

  .status {
    @apply rounded-md bg-civic-600 px-2 text-white;
  }

  /* the cheaper alternative: no Tailwind processing needed */
  .status-muted {
    background-color: var(--color-civic-100);
  }
</style>

go deeper

for a junior

Recall that a component's own style block or CSS Module is built separately and needs @reference to your main stylesheet before @apply works there.

for a middle

Explain why the block has no theme, what @reference brings in — theme variables, custom utilities and custom variants — and why it emits no CSS, unlike @import.

for a senior

Diagnose the unknown utility class error and a dark variant that ignores the app's class toggle, and weigh @reference against plain var() references for build speed.

for a principal

Set the policy for component style blocks in a Tailwind codebase — utilities in markup by default, var() where a block is unavoidable — and plan the migration of legacy CSS Modules.

## Why a component style block cannot see your theme Build tools process each CSS Module and each `<style>` block in a Vue, Svelte or Astro component as **its own stylesheet**. When **Tailwind CSS v4** runs on one of them, it compiles only that text. Your main stylesheet — the one with `@import "tailwindcss"`, your `@theme` block, your `@custom-variant` and `@utility` definitions — is not part of that compile, so inside the block: - there are **no theme variables**, so `@apply bg-civic-600` — and even a default colour such as `bg-sky-700` — cannot resolve; - your **custom utilities** and **custom variants** do not exist; - functions that read the theme, such as `--spacing()`, fail because no `--spacing` variable is defined. When the theme is empty, Tailwind's error says so: > Cannot apply unknown utility class bg-civic-600. Are you using CSS modules or similar and missing @reference? ## What `@reference` does `@reference` imports a stylesheet **for lookup only**. Tailwind reads its theme variables, custom utilities and custom variants so that `@apply` and `@variant` resolve, but emits none of that file's CSS into the block's output — only the declarations your own rules produce. ```html <span class="status"><slot /></span> <style> @reference "../app.css"; .status { @apply rounded-md bg-civic-600 px-2 text-white; } </style> ``` - `@reference "../app.css"` — the path to your main stylesheet, relative to the component file. - `@reference "tailwindcss"` — enough when the project uses the default theme with no `@theme`, `@custom-variant` or `@plugin` customisations. - `@reference "#app.css"` — with the CLI, Vite or PostCSS integrations, a Node subpath import declared under `imports` in `package.json` replaces a fragile relative path. The same line works at the top of a `.module.css` file. It changes nothing about how the block is scoped: Vue's `scoped` attribute and a module's generated class names behave exactly as before. ## `@reference`, `@import` and plain variables compared | In the component block | What the block can use | What lands in the output | Build cost | |---|---|---|---| | nothing | no theme; `@apply` of a theme utility errors | — | still a separate compile | | `@import "../app.css"` | everything | **a full copy** of the main stylesheet in every component | high, and duplicated CSS | | `@reference "../app.css"` | theme, custom utilities, custom variants | only the applied declarations | one Tailwind run per block | | `background: var(--color-civic-600)` | the value, resolved at runtime | just that declaration | Tailwind can skip the file | ## Tailwind's own advice: avoid the block, or use variables The documentation is direct: it recommends **not** using `<style>` blocks with Tailwind at all, and styling with utilities in the markup. Its reasons: 1. **Performance.** Each module or block is a separate Tailwind run, so fifty CSS Modules mean fifty runs and slower builds. 2. **Scoping is already handled.** A utility does the same thing wherever it is used, so the collision problem that per-file scoping solves barely arises. 3. **Variables need no processing.** `var(--color-civic-600)` reads the theme's custom property in the browser, so Tailwind does not need to touch the file. For the council portal's leftover CSS Modules this suggests an order of work: first add `@reference` so the existing `@apply` rules build; then replace single-value `@apply` lines with `var(--…)`; finally move what remains into the markup as utilities whenever a component is next touched. ## Custom variants need it too `@reference` also carries **custom variants**. If the main stylesheet switches dark mode to a `.dark` class, a Svelte block's `@variant dark { … }` follows that switch only when the block references the main stylesheet. Without it, the block compiles against Tailwind's built-in `dark` variant — the `prefers-color-scheme` media query — so that one component ignores the app's toggle while everything else obeys it. Unlike the `@apply` case, nothing errors, which makes this the harder failure to spot. ## A checklist for each separately compiled block - Does it use `@apply`, `@variant` or `--spacing()`? If not, it needs no `@reference` and Tailwind can skip it. - If it does, does the referenced path point at the stylesheet that holds `@import "tailwindcss"` and the project's `@theme`? - Is anything imported with `@import` that should have been `@reference`? Look for Preflight rules duplicated in a component's CSS output. - Could a single `var(--…)` replace the `@apply` line? Usually yes when only one property is set. - Does the block use `dark` or another variant the app redefines? Then the reference is mandatory, even if nothing errors.

  • In Tailwind CSS v4, the main stylesheet switches dark mode to a `.dark` class. Why must a Svelte block that uses `@variant dark` also use `@reference`?
    The block is compiled on its own, so it cannot see the main file's custom variant definition. Without `@reference` it compiles against the built-in `dark` variant, the `prefers-color-scheme` media query, and that component follows the OS setting while the rest of the app follows the class. Nothing errors, so the mismatch only shows in the UI.
  • In Tailwind CSS v4, when is `@reference "tailwindcss"` enough instead of a path to your own stylesheet?
    When the project uses the default theme with no customisations — no `@theme`, `@custom-variant`, `@plugin` or custom utilities. As soon as the block applies a project colour like `bg-civic-600` or a custom variant, it must reference the main stylesheet that defines them.
  • In a Tailwind CSS v4 project, why does replacing `@apply` with `var(--color-…)` in CSS Modules speed up the build?
    Each module is compiled separately, so every module that needs `@apply` costs its own Tailwind run. A rule that only reads a theme variable needs no Tailwind feature, so Tailwind can skip the file, and the browser resolves the custom property at runtime.

@reference is like reading a supplier's catalogue to learn what exists and what it is called, without ordering anything: the block learns the names and values, but nothing from the catalogue is shipped into its output.

  • Put @import "tailwindcss" at the top of every component style block
  • @reference copies the main stylesheet's CSS into the component's output
  • A CSS Module inherits the global theme because app.css is imported first
  • Wrapping the rule in :global() lets @apply find the theme
  • var(--color-…) only works inside files that Tailwind processes

Assumes Tailwind CSS v4 (checked against 4.3.3); @reference is a v4 directive, needed because v4 compiles each CSS Module and component style block separately.