Add @tailwindcss/webpack loader for Tailwind CSS v4 (#19610)
## Summary
This PR adds a new `@tailwindcss/webpack` package that provides a
dedicated webpack loader for Tailwind CSS v4. This loader works with
both standard webpack and Turbopack's webpack loader compatibility
layer.
### Why a dedicated loader?
The current webpack integration uses `postcss-loader` +
`@tailwindcss/postcss`. While this works, a dedicated loader:
- **Eliminates PostCSS as a middleman** - works directly with CSS
strings (no AST conversions)
- **Simpler and more efficient** - follows the same pattern as
`@tailwindcss/vite`
- **Better for Turbopack** - gives direct control over dependency
reporting via webpack's loader API
### How it works
The loader mirrors the Vite plugin's approach:
1. Uses `compile()` from `@tailwindcss/node` to parse CSS and resolve
`@apply` directives
2. Uses `Scanner` from `@tailwindcss/oxide` to scan content files for
utility candidates
3. Reports dependencies via `this.addDependency()` and
`this.addContextDependency()`
4. Optionally optimizes output with Lightning CSS
### Usage
```javascript
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /.css$/i,
use: [
MiniCssExtractPlugin.loader,
'css-loader',
'@tailwindcss/webpack', // No PostCSS needed!
],
},
],
},
}
```
### Options
- `base` - The base directory to scan for class candidates (defaults to
`process.cwd()`)
- `optimize` - Whether to optimize/minify the output CSS (defaults to
`true` in production)
### Files added
- `packages/@tailwindcss-webpack/` - New package
- `src/index.ts` - Main loader implementation
- `src/index.cts` - CommonJS entry point for webpack compatibility
- `package.json`, `tsconfig.json`, `tsup.config.ts`, `README.md`
- `integrations/webpack/loader.test.ts` - Integration tests
- `integrations/utils.ts` - Added webpack override for transitive
dependencies
### Test plan
- [x] Build test - verifies basic compilation
- [x] Watch test - verifies HMR when adding new Tailwind classes
- [x] `@apply` test - verifies `@apply` directives work correctly
- [x] Optimization test - verifies minification works
---------
Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
2026-01-29 15:16:31 +01:00
|
|
|
# @tailwindcss/webpack
|
|
|
|
|
|
|
|
|
|
A webpack loader for Tailwind CSS v4.
|
|
|
|
|
|
|
|
|
|
## Installation
|
|
|
|
|
|
|
|
|
|
```sh
|
|
|
|
|
npm install @tailwindcss/webpack
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Usage
|
|
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
|
// webpack.config.js
|
|
|
|
|
const MiniCssExtractPlugin = require('mini-css-extract-plugin')
|
|
|
|
|
|
|
|
|
|
module.exports = {
|
|
|
|
|
plugins: [new MiniCssExtractPlugin()],
|
|
|
|
|
module: {
|
|
|
|
|
rules: [
|
|
|
|
|
{
|
|
|
|
|
test: /\.css$/i,
|
|
|
|
|
use: [MiniCssExtractPlugin.loader, 'css-loader', '@tailwindcss/webpack'],
|
|
|
|
|
},
|
|
|
|
|
],
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
Then create a CSS file that imports Tailwind:
|
|
|
|
|
|
|
|
|
|
```css
|
|
|
|
|
/* src/index.css */
|
2026-02-20 12:03:25 +01:00
|
|
|
@import 'tailwindcss';
|
Add @tailwindcss/webpack loader for Tailwind CSS v4 (#19610)
## Summary
This PR adds a new `@tailwindcss/webpack` package that provides a
dedicated webpack loader for Tailwind CSS v4. This loader works with
both standard webpack and Turbopack's webpack loader compatibility
layer.
### Why a dedicated loader?
The current webpack integration uses `postcss-loader` +
`@tailwindcss/postcss`. While this works, a dedicated loader:
- **Eliminates PostCSS as a middleman** - works directly with CSS
strings (no AST conversions)
- **Simpler and more efficient** - follows the same pattern as
`@tailwindcss/vite`
- **Better for Turbopack** - gives direct control over dependency
reporting via webpack's loader API
### How it works
The loader mirrors the Vite plugin's approach:
1. Uses `compile()` from `@tailwindcss/node` to parse CSS and resolve
`@apply` directives
2. Uses `Scanner` from `@tailwindcss/oxide` to scan content files for
utility candidates
3. Reports dependencies via `this.addDependency()` and
`this.addContextDependency()`
4. Optionally optimizes output with Lightning CSS
### Usage
```javascript
// webpack.config.js
module.exports = {
module: {
rules: [
{
test: /.css$/i,
use: [
MiniCssExtractPlugin.loader,
'css-loader',
'@tailwindcss/webpack', // No PostCSS needed!
],
},
],
},
}
```
### Options
- `base` - The base directory to scan for class candidates (defaults to
`process.cwd()`)
- `optimize` - Whether to optimize/minify the output CSS (defaults to
`true` in production)
### Files added
- `packages/@tailwindcss-webpack/` - New package
- `src/index.ts` - Main loader implementation
- `src/index.cts` - CommonJS entry point for webpack compatibility
- `package.json`, `tsconfig.json`, `tsup.config.ts`, `README.md`
- `integrations/webpack/loader.test.ts` - Integration tests
- `integrations/utils.ts` - Added webpack override for transitive
dependencies
### Test plan
- [x] Build test - verifies basic compilation
- [x] Watch test - verifies HMR when adding new Tailwind classes
- [x] `@apply` test - verifies `@apply` directives work correctly
- [x] Optimization test - verifies minification works
---------
Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
2026-01-29 15:16:31 +01:00
|
|
|
```
|
|
|
|
|
|
|
|
|
|
## Options
|
|
|
|
|
|
|
|
|
|
### `base`
|
|
|
|
|
|
|
|
|
|
The base directory to scan for class candidates. Defaults to the current working directory.
|
|
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
|
{
|
|
|
|
|
loader: '@tailwindcss/webpack',
|
|
|
|
|
options: {
|
|
|
|
|
base: process.cwd(),
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
```
|
|
|
|
|
|
|
|
|
|
### `optimize`
|
|
|
|
|
|
|
|
|
|
Whether to optimize and minify the output CSS. Defaults to `true` in production mode.
|
|
|
|
|
|
|
|
|
|
```javascript
|
|
|
|
|
{
|
|
|
|
|
loader: '@tailwindcss/webpack',
|
|
|
|
|
options: {
|
|
|
|
|
optimize: true, // or { minify: true }
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
```
|