0
# @tailwindcss/vite
1

2
@tailwindcss/vite is a Vite plugin for Tailwind CSS v4 that provides seamless integration with the Vite build tool. It handles candidate scanning from source files, CSS generation in both development and production modes, and CSS optimization including minification.
3

4
## Package Information
5

6
- **Package Name**: @tailwindcss/vite
7
- **Package Type**: npm
8
- **Language**: TypeScript
9
- **Installation**: `npm install @tailwindcss/vite`
10

11
## Core Imports
12

13
```typescript
14
import tailwindcss from "@tailwindcss/vite";
15
```
16

17
For CommonJS:
18

19
```javascript
20
const tailwindcss = require("@tailwindcss/vite").default;
21
```
22

23
When working with Vite plugin types:
24

25
```typescript
26
import type { Plugin, ResolvedConfig, ViteDevServer } from 'vite';
27
import tailwindcss from "@tailwindcss/vite";
28
```
29

30
## Basic Usage
31

32
```typescript
33
import { defineConfig } from "vite";
34
import tailwindcss from "@tailwindcss/vite";
35

36
export default defineConfig({
37
  plugins: [
38
    tailwindcss(),
39
    // ... other plugins
40
  ],
41
});
42
```
43

44
## Architecture
45

46
The plugin is built around a three-phase approach:
47

48
- **Scan Phase**: Configures Vite server and resolves build configuration
49
- **Serve Phase**: Handles CSS generation during development with hot module replacement
50
- **Build Phase**: Processes CSS for production with optimization and minification
51

52
The plugin automatically detects CSS files that should be processed by Tailwind CSS and transforms them through the Tailwind compilation pipeline.
53

54
## Capabilities
55

56
### Main Plugin Function
57

58
Creates a Vite plugin array for Tailwind CSS v4 integration. The function takes no parameters and returns three plugins that handle different phases of the build process.
59

60
```typescript { .api }
61
/**
62
 * Creates a Vite plugin array for Tailwind CSS v4 integration
63
 * @returns Array of three Vite plugins handling scan, serve, and build phases
64
 */
65
declare function tailwindcss(): Plugin[];
66

67
export default tailwindcss;
68
```
69

70
## Types
71

72
```typescript { .api }
73
// Types imported from 'vite' package
74
interface Plugin {
75
  name: string;
76
  enforce?: 'pre' | 'post';
77
  apply?: 'build' | 'serve' | ((config: any, env: { command: string, mode: string }) => boolean);
78
  configureServer?: (server: ViteDevServer) => void;
79
  configResolved?: (config: ResolvedConfig) => void;
80
  transform?: (code: string, id: string, options?: any) => any | Promise<any>;
81
}
82

83
interface ViteDevServer {
84
  // Vite development server instance used in configureServer hook
85
}
86

87
interface ResolvedConfig {
88
  // Vite resolved configuration containing build settings, resolvers, and options
89
  root: string;
90
  build: {
91
    cssMinify: boolean | string;
92
    ssr: boolean | string;
93
  };
94
  css: {
95
    devSourcemap?: boolean;
96
  };
97
  createResolver: (options: any) => (id: string, base: string, skipSelf?: boolean, ssr?: boolean) => Promise<string | false | undefined>;
98
  resolve: any;
99
}
100
```
101

102
## Plugin Implementation Details
103

104
The returned plugin array contains three plugins:
105

106
1. **@tailwindcss/vite:scan** - Pre-enforcement plugin that:
107
   - Configures the Vite development server
108
   - Resolves Vite configuration
109
   - Sets up CSS and JavaScript module resolvers
110

111
2. **@tailwindcss/vite:generate:serve** - Development mode plugin that:
112
   - Transforms CSS files during development
113
   - Integrates with Vite's file watching system
114
   - Supports source maps for debugging
115

116
3. **@tailwindcss/vite:generate:build** - Production build plugin that:
117
   - Transforms CSS files for production builds
118
   - Applies CSS optimization and minification
119
   - Generates optimized source maps
120

121
## CSS File Detection
122

123
The plugin automatically processes CSS files that match these criteria:
124

125
- Files with `.css` extension
126
- Files with `&lang.css` query parameter
127
- Files matching inline style ID pattern (`?index=\d+\.css$`)
128

129
The plugin excludes:
130

131
- Special Vite queries (`?worker`, `?sharedworker`, `?raw`, `?url`)
132
- CommonJS proxy files (`?commonjs-proxy`)
133
- Files in the `.vite` directory
134

135
## Dependencies
136

137
The plugin leverages several Tailwind CSS workspace packages:
138

139
- **@tailwindcss/node**: Core compilation functions and utilities
140
- **@tailwindcss/oxide**: Fast candidate scanning
141
- **tailwindcss**: Main Tailwind CSS package
142

143
## Peer Dependencies
144

145
- **vite**: `^5.2.0 || ^6 || ^7` - Required Vite version for compatibility