🧩 vite-plugin-vue-auto-tailwind-reference

Powered by Payiano Team | GitHub

A Vite plugin that automatically adds @reference directive to Vue SFC <style> blocks (if it contains @apply). This is done at Vite code transformation step so nothing will be added in your codebase! 👻

⚡ This seamless integration allows developers to leverage Tailwind CSS v4 features while maintaining compatibility with their existing codebase, making migration a breeze.

⚡ By automatically handling @reference directive, this plugin ensures consistent styling across your application as you transition to Tailwind CSS v4.

⚡ Whether you're migrating from Tailwind CSS v3 or just starting out with Tailwind CSS v4, this plugin provides an efficient way to globally manage styles in your Vue projects.

Compatibility

Tested with Node 20+, Vite 6, Vue 3.5 and Tailwind CSS v4. It might work with older versions but is untested and unsupported there.

Installation

Install the plugin from npm with your preferred package manager:

# NPM
npm install vite-plugin-vue-auto-tailwind-reference --save-dev

# Yarn
yarn add vite-plugin-vue-auto-tailwind-reference --dev

# PNPM
pnpm add vite-plugin-vue-auto-tailwind-reference -D

Usage

Basic Setup

Import and register the plugin in your vite.config.js or vite.config.ts. By default, the plugin assumes your CSS file is located at src/index.css. You can override this in advanced configuration.

⚠️ Important: Register this plugin before the official tailwindcss() plugin.

import { defineConfig } from "vite";
import vue from "@vitejs/plugin-vue";
import tailwindAutoReference from "vite-plugin-vue-auto-tailwind-reference";
import tailwindcss from "@tailwindcss/vite";

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

Use the @apply directive normally in your Vue component style blocks:

<template>
  <div class="myClass">Hello, Tailwind!</div>
</template>

<style scoped>
.myClass {
  @apply bg-blue-500 text-white p-4;
}
</style>

Advanced Configuration

You can customize the plugin with parameters:

• cssFile: Path(s) to your Tailwind CSS file(s). Default is ./src/index.css. Can be a string, an array of strings, or a function returning paths.
• opts: Additional options such as include, exclude, and skip patterns.

Example:

tailwindAutoReference("./src/tailwind.css", {
  include: [/\.vue\?.*type=style/, /\.scss/],
  exclude: /node_modules/,
  skip: (code, id) => code.includes("@reference"),
});

See the Usage section for more details on advanced options.

Contributing

Contributions are welcome! Please open issues or pull requests if you want to suggest improvements or fixes.

Development commands

npm run dev     # Watch and compile in development
npm run build   # Build production files
npm run lint    # Run ESLint

License

This project is licensed under the MIT License - see the LICENSE file for details.

Code of Conduct

This project follows the Contributor Code of Conduct. By participating, you agree to abide by its terms.

Sponsoring

If you find this project helpful, please consider supporting me on Buy Me a Coffee! Your support helps me continue developing open-source software.