“Setting Up Tailwind CSS v3 with SvelteKit and Bun (While v4 has issues)”

Introduction

SvelteKit offers a fantastic framework for building web applications, and Bun brings incredible speed to the JavaScript ecosystem. Pairing these with the utility-first power of Tailwind CSS seems like a perfect match. However the latest Tailwind CSS v4, currently faces compatibility hurdles when used with Bun in SvelteKit projects.

But don’t let that stop you! Tailwind CSS v3 remains a powerful tool that integrates smoothly with SvelteKit and Bun. This post will guide you through setting up a reliable development environment using Tailwind CSS v3, SvelteKit, and Bun, complete with PostCSS, Autoprefixer, and plugin support.

What You’ll Achieve:

• A minimal SvelteKit project running on Bun.
• Tailwind CSS v3 successfully integrated using PostCSS and Autoprefixer.
• The ability to add popular Tailwind CSS plugins (like Typography, Forms, etc.).
• A clear, step-by-step process to get you coding quickly.

🧰 Automate It – Use the shell script if you want to skip ahead and get Tailwind v3 + SvelteKit + Bun set up in seconds. Its what I currently use to setup projects.

Otherwise let’s dive in to the detail.

Prerequisites

Before starting, ensure you have Bun installed on your system. You can find installation instructions on the official Bun website.

Step 1: Create Your SvelteKit Project

First, let’s create a new SvelteKit project using Bun’s package runner (bunx). Choose your preferred options when prompted by the SvelteKit initializer (It needs to be a demo project and have TypeScript support though). DO NOT select the option to add Tailwind CSS during the sv create process. It will be added later.

Using Bash type:

bunx sv create my-app
cd my-app
bun install

This creates a new directory my-app, navigates into it, and installs the necessary dependencies using Bun’s fast installer.

Step 2: Install Tailwind CSS v3 and Dependencies

Next, we need to install Tailwind CSS itself, along with PostCSS (a tool for transforming CSS with JavaScript plugins) and Autoprefixer (a PostCSS plugin to parse CSS and add vendor prefixes). We specifically install version 3 of Tailwind (tailwindcss@3).

bun add -D tailwindcss@3 postcss autoprefixer

Note: The -D flag installs these as development dependencies.

Step 3: Initialize Tailwind CSS Configuration

Generate the Tailwind configuration file (tailwind.config.js). Again, we explicitly use tailwindcss@3 here to ensure we get the v3 configuration structure.

bunx tailwindcss@3 init

This command creates a basic tailwind.config.js file in your project root.

Step 4: Create PostCSS Configuration

Tailwind CSS requires PostCSS to work its magic. Create a postcss.config.js file in the root of your project and add the following configuration:

The JavaScript postcss.config.js file needs to be created or updated as below:

// postcss.config.js
export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

This tells PostCSS to process your CSS using the Tailwind CSS and Autoprefixer plugins.

Step 5: Configure Tailwind Content Sources

Now, edit the generated tailwind.config.js file to tell Tailwind where to look for class names. Update the content array to include your Svelte components and any other template files.

JavaScript

// tailwind.config.js
/** @type {import('tailwindcss').Config} */
module.exports = {
  content: ['./src/**/*.{html,js,svelte,ts}'], // Scan these files for Tailwind classes
  theme: {
    extend: {},
  },
  plugins: [], // We'll add plugins here later if needed
}

Step 6: Add Tailwind Directives to Your CSS

You need a global CSS file where Tailwind’s base styles, component classes, and utility classes can be injected. Create a file named src/app.css (or update it if it already exists) and add the following Tailwind directives:

CSS

/* src/app.css */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* You can add your own custom base styles below this line */

Step 7: Import the CSS into Your Application

Ensure your global CSS file is imported into your SvelteKit application. The most common place to do this is in your root layout file, src/routes/+layout.svelte.

TypeScript

// src/routes/+layout.svelte
<script lang="ts">
  import '../app.css'; // Import the global CSS file
</script>

<slot />

Step 8: Run the Development Server

You’re all set up! Start your SvelteKit development server using Bun:

bun run dev

Step 9: Test Your Tailwind Installation

To verify that Tailwind CSS is working correctly, open any Svelte component (e.g., src/routes/+page.svelte) and add an element with some Tailwind utility classes:

<h1 class="text-3xl font-bold underline mb-4">Welcome to SvelteKit</h1>

<div class="p-6 m-4 max-w-sm rounded-xl bg-gradient-to-r from-blue-500 to-cyan-400 text-white shadow-lg">
  <h2 class="text-xl font-semibold">Hello Tailwind!</h2>
  <p class="mt-2">If this card is styled, Tailwind CSS v3 is working with SvelteKit and Bun!</p>
</div>

<p>Visit <a href="https://kit.svelte.dev" class="text-blue-600 hover:underline">kit.svelte.dev</a> to read the documentation</p>

Navigate to your application in the browser (usually http://localhost:5173). If you see a styled div element matching the classes you applied, congratulations – Tailwind CSS v3 is successfully integrated!

Extending with Tailwind Plugins

One of the great things about Tailwind is its ecosystem of plugins. For example, to add the official Typography plugin:

Install the plugin:

bun add -D @tailwindcss/typography

Add it to your Tailwind configuration: JavaScript

// tailwind.config.js /** @type {import('tailwindcss').Config} */ module.exports = { content: ['./src/**/*.{html,js,svelte,ts}'], theme: { extend: {}, }, plugins: [ require('@tailwindcss/typography'), // Add the plugin here // require('@tailwindcss/forms'), // Example: Add other plugins // require('@tailwindcss/aspect-ratio'), // Example: Add other plugins ], }

Important Considerations

• Avoid Tailwind CSS v4 (for now): As mentioned, stick with tailwindcss@3 when using Bun with SvelteKit due to current compatibility issues. Keep an eye on updates from the Bun, SvelteKit, and Tailwind teams for future compatibility.
• Plugin Installation: Remember to install plugins as dev dependencies (bun add -D @tailwindcss/plugin-name) and require them in your tailwind.config.js.

⚡️ Want to skip the manual steps?

If you’d rather get straight to coding, I’ve written a shell script that automates this entire setup — including Tailwind v3, PostCSS, Autoprefixer, and optional plugin support.

Just run this from your terminal:

curl -sSL https://raw.githubusercontent.com/robdeas/bun-tools/main/bin/init-sveltekit-tailwind.sh | bash -s my-app --plugins forms typography

Or clone it locally from bun-tools on GitHub and run:

./init-sveltekit-tailwind.sh my-app --plugins forms typography

✅ Supports:

• Plugin flags (--plugins forms typography)
• Tailwind CSS v3 only
• Bun-native project setup with bunx sv create

Conclusion

You now have a robust setup combining the speed of Bun, the elegance of SvelteKit, and the utility-first styling power of Tailwind CSS v3. While we eagerly await seamless Tailwind v4 integration in this stack, this v3 setup provides a stable and highly productive environment for building modern web applications today. You can either follow the manual steps above, or automate the entire process using the setup script from my bun-tools repo. It’s MIT licensed and ready for reuse.

Happy coding!