vite-plugin-tailwind-ref 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 awaiden
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,225 @@
+# vite-plugin-tailwind-ref
+
+A Vite plugin that automatically adds `@reference` directives to CSS files using Tailwind CSS `@apply`, enabling utility class usage without manual imports.
+
+## Problem
+
+When using Tailwind's `@apply` directive in CSS files (including framework-scoped styles like Svelte or Vue components), you typically need to manually add `@reference` directives:
+
+```css
+@reference "tailwindcss";
+
+.my-class {
+  @apply flex items-center;
+}
+```
+
+This is repetitive and easy to forget.
+
+## Solution
+
+This plugin automatically injects the necessary `@reference` directive when it detects `@apply` usage in your CSS files.
+
+## Installation
+
+```bash
+npm install -D vite-plugin-tailwind-ref
+```
+
+## Usage
+
+Add the plugin to your `vite.config.ts`:
+
+```typescript
+import { defineConfig } from "vite";
+import tailwindAutoReference from "vite-plugin-tailwind-ref";
+
+export default defineConfig({
+  plugins: [tailwindAutoReference()],
+});
+```
+
+Now you can use `@apply` in your CSS files without manually adding `@reference` directives:
+
+```css
+.my-class {
+  @apply flex items-center justify-center;
+}
+```
+
+The plugin will automatically inject:
+
+```css
+@reference "tailwindcss";
+
+.my-class {
+  @apply flex items-center justify-center;
+}
+```
+
+### Svelte
+
+For Svelte component style blocks, configure the `include` pattern to match Svelte's style query:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import { svelte } from "@sveltejs/vite-plugin-svelte";
+import tailwindAutoReference from "vite-plugin-tailwind-ref";
+
+export default defineConfig({
+  plugins: [
+    svelte(),
+    tailwindAutoReference("tailwindcss", {
+      include: [/\.svelte\?.*svelte&type=style/],
+    }),
+  ],
+});
+```
+
+Then use `@apply` freely in your components:
+
+```svelte
+<style>
+  .my-class {
+    @apply flex items-center justify-center;
+  }
+</style>
+```
+
+### Vue
+
+For Vue component style blocks, match Vue's style query:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import vue from "@vitejs/plugin-vue";
+import tailwindAutoReference from "vite-plugin-tailwind-ref";
+
+export default defineConfig({
+  plugins: [
+    vue(),
+    tailwindAutoReference("tailwindcss", {
+      include: [/\.vue\?.*type=style/],
+    }),
+  ],
+});
+```
+
+Then use `@apply` in your components:
+
+```vue
+<style scoped>
+.my-class {
+  @apply flex items-center justify-center;
+}
+</style>
+```
+
+### Multiple frameworks / CSS files together
+
+You can combine multiple patterns to cover both standalone CSS files and framework style blocks:
+
+```typescript
+tailwindAutoReference("tailwindcss", {
+  include: [/\.css$/, /\.svelte\?.*svelte&type=style/],
+});
+```
+
+## Configuration
+
+### Basic Options
+
+```typescript
+tailwindAutoReference(cssFile, options);
+```
+
+#### `cssFile` (optional)
+
+Type: `string | string[] | (code?: string, id?: string) => string | string[] | Promise<string | string[]>`  
+Default: `"tailwindcss"`
+
+The path(s) to your Tailwind CSS file, or a function that returns the path(s).
+
+**Examples:**
+
+```typescript
+// String path
+tailwindAutoReference("./src/styles/tailwind.css");
+
+// Multiple paths
+tailwindAutoReference(["./src/styles/tailwind.css", "./src/styles/custom.css"]);
+
+// Dynamic function
+tailwindAutoReference((code, id) => {
+  return id.includes("admin") ? "./admin-tailwind.css" : "./tailwind.css";
+});
+
+// Async function
+tailwindAutoReference(async (code, id) => {
+  const config = await loadConfig();
+  return config.cssPath;
+});
+```
+
+#### `options` (optional)
+
+Type: `object`
+
+- **`include`** (optional)  
+  Type: `FilterPattern` (string | RegExp | Array<string | RegExp>)  
+  Default: `[/\.css$/]`  
+  Patterns to match files for transformation.
+
+- **`exclude`** (optional)  
+  Type: `FilterPattern`  
+  Default: `[]`  
+  Patterns to exclude from transformation.
+
+- **`skip`** (optional)  
+  Type: `(code?: string, id?: string) => boolean`  
+  Default: `() => false`  
+  Custom function to skip transformation based on file content or path.
+
+### Advanced Examples
+
+```typescript
+// Custom include/exclude patterns
+tailwindAutoReference("./src/styles/tailwind.css", {
+  include: [/\.css$/, /\.svelte\?.*svelte&type=style/],
+  exclude: [/node_modules/],
+});
+
+// Skip specific files
+tailwindAutoReference("./src/styles/tailwind.css", {
+  skip: (code, id) => {
+    return code?.includes("@reference") ?? false;
+  },
+});
+```
+
+## How It Works
+
+1. The plugin runs in Vite's `pre` enforce phase
+2. It intercepts CSS files (or files matching the configured `include` pattern)
+3. When it detects `@apply` usage, it injects the `@reference` directive
+4. If `@use` statements exist, the `@reference` is placed after the last `@use`
+5. Otherwise, it's placed at the beginning of the file
+6. Files that already contain `@reference` or `@import "tailwindcss"` are skipped
+
+## Requirements
+
+- Vite 5.x, 6.x, 7.x, or 8.x
+
+## Credits
+
+This plugin is inspired by [vite-plugin-vue-tailwind-auto-reference](https://github.com/M1CK431/vite-plugin-vue-tailwind-auto-reference) by M1CK431.
+
+## License
+
+MIT
+
+## Contributing
+
+Issues and pull requests are welcome at [https://github.com/awaiden/vite-plugin-tailwind-ref](https://github.com/awaiden/vite-plugin-tailwind-ref)

package/dist/index.d.mts

@@ -0,0 +1,33 @@
+import { FilterPattern, Plugin } from "vite";
+
+//#region src/index.d.ts
+/**
+ * A callback that determines which "@reference" should be added by the tailwindAutoReference plugin.
+ * Returns the path to the Tailwind CSS file or an array of them.
+ */
+type CssFileFn = (code?: string, id?: string) => Promise<string | string[]> | string | string[];
+/**
+ * An options object for the tailwindAutoReference plugin.
+ */
+interface PluginOption {
+  /** A list of picomatch patterns that match files to be excluded from transformation */
+  exclude?: FilterPattern;
+  /** A list of picomatch patterns that match files to be transformed */
+  include?: FilterPattern;
+  /** A function that determines whether a file should be skipped */
+  skip: SkipFn;
+}
+/**
+ * A callback that determines whether a file should be skipped by the tailwindAutoReference plugin.
+ * Returns true if the file should be skipped, false otherwise.
+ */
+type SkipFn = (code?: string, id?: string) => boolean;
+/**
+ * A Vite plugin that automatically adds "@reference" directives to CSS files using @apply.
+ *
+ * @param cssFile - The path to the Tailwind CSS file or an array of them or a sync or async function that returns it or them.
+ * @param opts - An options object for configuring the plugin behavior.
+ */
+declare const tailwindAutoReference: (cssFile?: CssFileFn | string | string[], opts?: PluginOption) => Plugin;
+//#endregion
+export { tailwindAutoReference as default };

package/dist/index.mjs

@@ -0,0 +1,49 @@
+import { resolve } from "node:path";
+import { createFilter } from "vite";
+//#region src/index.ts
+const defaultOpts = {
+	exclude: [],
+	include: [/\.css$/],
+	skip: () => false
+};
+const resolveFn = (fn, ...args) => Promise.resolve(fn instanceof Function ? fn(args) : fn);
+/**
+* A Vite plugin that automatically adds "@reference" directives to CSS files using @apply.
+*
+* @param cssFile - The path to the Tailwind CSS file or an array of them or a sync or async function that returns it or them.
+* @param opts - An options object for configuring the plugin behavior.
+*/
+const tailwindAutoReference = (cssFile = "tailwindcss", opts = defaultOpts) => {
+	const { exclude, include, skip } = {
+		...defaultOpts,
+		...opts
+	};
+	let fileFilter, root;
+	const getReferenceStr = (reference) => (Array.isArray(reference) ? reference : [reference]).reduce((acc, file) => `${acc}\n@reference "${resolve(root, file)}";`, "");
+	return {
+		configResolved: (config) => {
+			root = config.root;
+			fileFilter = createFilter(include, exclude, { resolve: root });
+		},
+		enforce: "pre",
+		name: "tailwind-auto-reference",
+		transform: async (code, id) => {
+			if (!fileFilter(id)) return null;
+			if (!code.includes("@apply ") || skip(code, id)) return null;
+			if (code.includes("@reference ") || code.includes("@import \"tailwindcss\"")) return null;
+			const lastUseMatch = [...code.matchAll(/^\s*@use.*\n/gm)].at(-1);
+			if (!lastUseMatch) return {
+				code: `${getReferenceStr(await resolveFn(cssFile, code, id))}\n${code}`,
+				map: null
+			};
+			const before = code.substring(0, lastUseMatch.index);
+			const after = code.substring(lastUseMatch.index + lastUseMatch[0].length);
+			return {
+				code: `${before}${getReferenceStr(await resolveFn(cssFile, code, id))}\n${after}`,
+				map: null
+			};
+		}
+	};
+};
+//#endregion
+export { tailwindAutoReference as default };

package/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "vite-plugin-tailwind-ref",
+  "version": "1.0.0",
+  "description": "A Vite plugin that automatically adds @reference directives to CSS files and framework style blocks (Svelte, Vue, etc.) using Tailwind CSS @apply",
+  "keywords": [
+    "vite",
+    "vite-plugin",
+    "tailwindcss",
+    "tailwind",
+    "css",
+    "svelte",
+    "vue",
+    "reference",
+    "apply"
+  ],
+  "homepage": "https://github.com/awaiden/vite-plugin-tailwind-ref#readme",
+  "bugs": {
+    "url": "https://github.com/awaiden/vite-plugin-tailwind-ref/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/awaiden/vite-plugin-tailwind-ref.git"
+  },
+  "license": "MIT",
+  "author": "awaiden",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.mts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "format": "prettier --write .",
+    "lint": "eslint .",
+    "prepare": "husky",
+    "prepublishOnly": "bun run build"
+  },
+  "lint-staged": {
+    "*.{ts,js,mjs}": [
+      "eslint --fix",
+      "prettier --write"
+    ],
+    "*.{json,md}": [
+      "prettier --write"
+    ]
+  },
+  "dependencies": {},
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "@types/node": "^25.9.1",
+    "eslint": "^10.4.0",
+    "eslint-plugin-perfectionist": "^5.9.0",
+    "husky": "^9.1.7",
+    "lint-staged": "^17.0.5",
+    "prettier": "^3.8.3",
+    "prettier-plugin-packagejson": "^3.0.2",
+    "tsdown": "^0.22.0",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.60.0",
+    "unrun": "^0.3.0"
+  },
+  "peerDependencies": {
+    "vite": "^8.0.14"
+  }
+}