Skip to content
Tutorials Center
My learning

Topics

Lesson 20 of 37 ยท Styling and Assets

Tailwind CSS and Sass in Astro

Add Tailwind CSS 4 and Sass to an Astro project, organise design tokens, avoid purge mistakes and decide when utilities beat scoped styles.

Scoped CSS covers a lot, but many teams want utility classes (Tailwind) or a preprocessor (Sass). Astro supports both through Vite, with almost no setup. This lesson shows how to install them, how they interact with scoped styles, and how to decide which tool to use where.

Tailwind CSS in Astro

Current Astro projects use Tailwind v4 through its official Vite plugin. The CLI does the wiring for you:

Terminal
npx astro add tailwind

That command installs tailwindcss and @tailwindcss/vite and edits your config. The result is equivalent to:

JavaScript
// astro.config.mjs
import { defineConfig } from 'astro/config';
import tailwindcss from '@tailwindcss/vite';

export default defineConfig({
  vite: {
    plugins: [tailwindcss()],
  },
});

Then create one stylesheet and import it in your root layout:

CSS
/* src/styles/global.css */
@import "tailwindcss";

@theme {
  --color-brand: #6d28d9;
  --font-display: "Fraunces", serif;
}
ASTRO
---
// src/layouts/Base.astro
import '../styles/global.css';
---
<html lang="en">
  <body class="bg-white text-slate-900 dark:bg-slate-950 dark:text-slate-100">
    <slot />
  </body>
</html>

Now every .astro file (and every React, Vue or Svelte island) can use utilities such as p-4, grid, md:flex or bg-brand. Tailwind scans your source files, so only the classes you actually use end up in the final CSS.

Older tutorials use the @astrojs/tailwind integration and a tailwind.config.mjs. That is the Tailwind 3 route. For new projects prefer the Vite plugin and CSS-first @theme configuration.

Dynamic class names: the one mistake

Tailwind finds classes by reading your files as text. It cannot understand string building:

ASTRO
---
const color = 'red';
---
<!-- Wrong: "bg-red-500" never appears in the source, so it is not generated -->
<div class={`bg-${color}-500`}>...</div>

<!-- Right: write complete class names and choose between them -->
<div class:list={[color === 'red' ? 'bg-red-500' : 'bg-blue-500']}>...</div>

A lookup object with full class names ({ red: 'bg-red-500', blue: 'bg-blue-500' }) is the cleanest pattern.

Mixing utilities and scoped CSS

They coexist happily. A common split:

  • Utilities for layout, spacing and quick states in markup.
  • A scoped <style> for things utilities express badly: complex animations, :has() selectors, long gradients.
  • @apply inside a scoped style is possible, but in Tailwind v4 you must reference the config first with @reference "../styles/global.css"; at the top of that <style>.
ASTRO
<style>
  @reference "../styles/global.css";
  .callout {
    @apply rounded-lg border-l-4 border-brand bg-brand/5 p-4;
  }
</style>

Sass (SCSS) in Astro

Install the compiler and write lang="scss":

Terminal
npm install -D sass
ASTRO
<ul class="menu">
  <li><a href="/docs">Docs</a></li>
  <li><a href="/blog">Blog</a></li>
</ul>

<style lang="scss">
  $gap: 1rem;

  .menu {
    display: flex;
    gap: $gap;
    list-style: none;
    padding: 0;

    a {
      text-decoration: none;
      &:hover { text-decoration: underline; }
    }
  }
</style>

Scoping still happens after Sass compiles, so nesting like .menu a is scoped correctly. You can import .scss files in the frontmatter exactly as you would plain CSS. For shared variables and mixins, Vite lets you inject a file into every Sass file:

JavaScript
// astro.config.mjs
export default defineConfig({
  vite: {
    css: {
      preprocessorOptions: {
        scss: { additionalData: `@use "/src/styles/vars" as *;` },
      },
    },
  },
});

Other preprocessors (Less, Stylus) work the same way: install the package, set the lang attribute. Native CSS now has nesting, variables and color-mix(), so you may not need Sass at all for new code.

Choosing a styling approach

Need Good fit
Small site, content pages Scoped <style> blocks
Design system with many variants Tailwind utilities + a few components
Existing Sass codebase lang="scss" and the same partials
Theming (light/dark, brand colors) CSS custom properties in one global file

Whatever you pick, put tokens in custom properties: they travel into islands, Markdown content and third-party widgets alike.

Try it: how Tailwind finds classes

This stand-in scans source text for class tokens and generates CSS for a few utilities. It shows why dynamic names such as `bg-${color}-500` produce nothing.

JS Utility scanner

Press Run (or Ctrl + Enter) to see the console output here.

No output.

The second run emits only .flex: the text bg-red-500 never appears, so the utility is never generated.

Try it: a mini design-token builder

Tokens in one object become CSS custom properties, which every component and island can read.

JS Tokens to CSS variables

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Which command wires Tailwind into an Astro project?

    astro add installs the packages and edits astro.config for you, as it does for other integrations.
  2. 2. Why does class={bg-${color}-500} fail to produce CSS?

    Tailwind detects class names by scanning source text. A complete name must appear somewhere in your files.
  3. 3. How do you write Sass in a component style block?

    Vite handles preprocessors. Install the compiler and set the lang attribute; scoping is applied afterwards.
  4. 4. Where should design tokens such as brand colors live so islands can use them?

    Custom properties inherit through the DOM, so Astro components, framework islands and Markdown content can all use them.

Summary

  • npx astro add tailwind sets up Tailwind v4 through its Vite plugin; configure themes in CSS with @theme.
  • Always write full utility class names; never assemble them from fragments.
  • lang="scss" plus the sass package enables Sass; scoping happens after compilation.
  • Mix approaches by role: utilities for layout, scoped CSS for the special cases, custom properties for tokens.

Next: Images and the Image Component