How to Use Tailwind CSS with Astro: Complete Guide
Step-by-step guide to integrating Tailwind CSS with your Astro website. Installation, configuration, and best practices.
Tailwind CSS and Astro are a natural pair. Astro ships zero JavaScript by default, and Tailwind purges unused styles at build time, so you end up with a tiny CSS bundle and fast pages. Astro has first-class Tailwind support through an official integration that handles all the configuration for you.
Prerequisites
- Node.js 18+
- An Astro project (
npm create astro@latest)
Installation
The easiest way to add Tailwind to Astro:
npx astro add tailwindcss
This installs @astrojs/tailwind and tailwindcss, creates a tailwind.config.mjs file, and updates your Astro config. One command, done.
If you prefer to do it manually:
npm install @astrojs/tailwind tailwindcss
Configuration
After running the add command, your Astro config is updated automatically:
// astro.config.mjs
import { defineConfig } from "astro/config";
import tailwindcss from "@astrojs/tailwind";
export default defineConfig({
integrations: [tailwindcss()],
});
The generated tailwind.config.mjs looks like this:
// tailwind.config.mjs
/** @type {import('tailwindcss').Config} */
export default {
content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
theme: {
extend: {},
},
plugins: [],
};
The content array tells Tailwind where to look for class names. Astro sets this up correctly by default.
Basic Usage
Start using Tailwind classes directly in your Astro components:
---
// src/pages/index.astro
import BaseLayout from "../layouts/BaseLayout.astro";
---
<BaseLayout title="Home">
<main class="max-w-4xl mx-auto px-4 py-12">
<h1 class="text-4xl font-bold text-gray-900 dark:text-white mb-4">
Welcome to My Site
</h1>
<p class="text-lg text-gray-600 dark:text-gray-300 leading-relaxed">
Built with Astro and styled with Tailwind CSS.
</p>
<a
href="/blog"
class="inline-block mt-6 px-6 py-3 bg-blue-600 text-white rounded-lg
hover:bg-blue-700 transition-colors"
>
Read the Blog
</a>
</main>
</BaseLayout>
Adding Custom Styles and Plugins
Extend your Tailwind config with custom colors, fonts, and plugins:
// tailwind.config.mjs
export default {
content: ["./src/**/*.{astro,html,js,jsx,md,mdx,svelte,ts,tsx,vue}"],
theme: {
extend: {
colors: {
brand: {
50: "#eff6ff",
500: "#3b82f6",
900: "#1e3a5f",
},
},
fontFamily: {
sans: ["Inter", "system-ui", "sans-serif"],
},
},
},
plugins: [
require("@tailwindcss/typography"),
require("@tailwindcss/forms"),
],
};
Install the plugins:
npm install @tailwindcss/typography @tailwindcss/forms
The typography plugin is especially useful for blog content. Wrap your article body in a prose class and it handles all the typography for you:
<article class="prose prose-lg dark:prose-invert max-w-none">
<slot />
</article>
Dark Mode
Tailwind's dark mode works well with Astro. Set the strategy in your config:
// tailwind.config.mjs
export default {
darkMode: "class",
// ...rest of config
};
Then toggle a dark class on the <html> element. Use dark: variants in your markup:
<div class="bg-white dark:bg-gray-900">
<h1 class="text-gray-900 dark:text-white">Hello</h1>
</div>
Production Tips
Use the typography plugin for prose content. It styles rendered Markdown and HTML beautifully without manual class wrangling. One class, professional typography.
Enable JIT mode (it is the default now). Tailwind v4 and v3.4+ use just-in-time compilation, so only the classes you use end up in your final CSS. No manual purging needed.
Create component classes with
@apply. For repeated patterns, use@applyin a global CSS file rather than repeating long class strings everywhere:
/* src/assets/styles/global.css */
@layer components {
.btn-primary {
@apply px-6 py-3 bg-blue-600 text-white rounded-lg hover:bg-blue-700 transition-colors;
}
}
Keep your config organized. As your design system grows, split custom values into separate files or use the
presetfeature to share config across projects.Use the Tailwind VS Code extension. It gives you autocomplete for class names, inline previews of colors, and lint warnings for conflicting utilities.
Alternatives to Consider
- UnoCSS if you want a faster, more customizable atomic CSS engine that is compatible with Tailwind's class syntax. Also has an official Astro integration.
- Open Props if you prefer CSS custom properties over utility classes. Provides design tokens you can use with regular CSS.
- Vanilla Extract if you want type-safe CSS in TypeScript with zero runtime cost. Good for larger, more structured projects.
Wrapping Up
Tailwind CSS is the most popular way to style an Astro site for good reason. The official integration makes setup trivial, the utility-first approach keeps your styles co-located with your markup, and the build output is tiny. If you are starting a new Astro project, just run astro add tailwindcss and start building.
Related Articles
How to Use Algolia with Astro: Complete Guide
Step-by-step guide to integrating Algolia with your Astro website.
How to Integrate Auth0 with Astro: Complete Guide
Step-by-step guide to integrating Auth0 with your Astro website. Setup, configuration, and best practices.
How to Use AWS Amplify with Astro: Complete Guide
Step-by-step guide to integrating AWS Amplify with your Astro website.