2024-08-07 16:38:44 +02:00
|
|
|
import path from 'node:path'
|
2025-04-29 18:16:58 +02:00
|
|
|
import { candidate, css, html, js, json, retryAssertion, test, ts, yaml } from '../utils'
|
2024-08-07 16:38:44 +02:00
|
|
|
|
|
|
|
|
test(
|
2024-08-08 17:49:06 +02:00
|
|
|
'production build (string)',
|
2024-08-07 16:38:44 +02:00
|
|
|
{
|
|
|
|
|
fs: {
|
|
|
|
|
'package.json': json`{}`,
|
|
|
|
|
'pnpm-workspace.yaml': yaml`
|
|
|
|
|
#
|
|
|
|
|
packages:
|
|
|
|
|
- project-a
|
|
|
|
|
`,
|
|
|
|
|
'project-a/package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"dependencies": {
|
|
|
|
|
"postcss": "^8",
|
|
|
|
|
"postcss-cli": "^10",
|
|
|
|
|
"tailwindcss": "workspace:^",
|
|
|
|
|
"@tailwindcss/postcss": "workspace:^"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/postcss.config.js': js`
|
|
|
|
|
module.exports = {
|
|
|
|
|
plugins: {
|
|
|
|
|
'@tailwindcss/postcss': {},
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/index.html': html`
|
|
|
|
|
<div
|
|
|
|
|
class="underline 2xl:font-bold hocus:underline inverted:flex"
|
|
|
|
|
></div>
|
|
|
|
|
`,
|
|
|
|
|
'project-a/plugin.js': js`
|
|
|
|
|
module.exports = function ({ addVariant }) {
|
|
|
|
|
addVariant('inverted', '@media (inverted-colors: inverted)')
|
|
|
|
|
addVariant('hocus', ['&:focus', '&:hover'])
|
|
|
|
|
}
|
|
|
|
|
`,
|
2024-09-03 16:54:08 +02:00
|
|
|
'project-a/tailwind.config.js': js`
|
|
|
|
|
module.exports = {
|
|
|
|
|
content: ['../project-b/src/**/*.js'],
|
|
|
|
|
}
|
|
|
|
|
`,
|
2024-08-07 16:38:44 +02:00
|
|
|
'project-a/src/index.css': css`
|
Resolve `@import` in core (#14446)
This PR brings `@import` resolution into Tailwind CSS core. This means
that our clients (PostCSS, Vite, and CLI) no longer need to depend on
`postcss` and `postcss-import` to resolve `@import`. Furthermore this
simplifies the handling of relative paths for `@source`, `@plugin`, or
`@config` in transitive CSS files (where the relative root should always
be relative to the CSS file that contains the directive). This PR also
fixes a plugin resolution bug where non-relative imports (e.g. directly
importing node modules like `@plugin '@tailwindcss/typography';`) would
not work in CSS files that are based in a different npm package.
### Resolving `@import`
The core of the `@import` resolution is inside
`packages/tailwindcss/src/at-import.ts`. There, to keep things
performant, we do a two-step process to resolve imports. Imagine the
following input CSS file:
```css
@import "tailwindcss/theme.css";
@import "tailwindcss/utilities.css";
```
Since our AST walks are synchronous, we will do a first traversal where
we start a loading request for each `@import` directive. Once all loads
are started, we will await the promise and do a second walk where we
actually replace the AST nodes with their resolved stylesheets. All of
this is recursive, so that `@import`-ed files can again `@import` other
files.
The core `@import` resolver also includes extensive test cases for
[various combinations of media query and supports conditionals as well
als layered
imports](https://developer.mozilla.org/en-US/docs/Web/CSS/@import).
When the same file is imported multiple times, the AST nodes are
duplicated but duplicate I/O is avoided on a per-file basis, so this
will only load one file, but include the `@theme` rules twice:
```css
@import "tailwindcss/theme.css";
@import "tailwindcss/theme.css";
```
### Adding a new `context` node to the AST
One limitation we had when working with the `postcss-import` plugin was
the need to do an additional traversal to rewrite relative `@source`,
`@plugin`, and `@config` directives. This was needed because we want
these paths to be relative to the CSS file that defines the directive
but when flattening a CSS file, this information is no longer part of
the stringifed CSS representation. We worked around this by rewriting
the content of these directives to be relative to the input CSS file,
which resulted in added complexity and caused a lot of issues with
Windows paths in the beginning.
Now that we are doing the `@import` resolution in core, we can use a
different data structure to persist this information. This PR adds a new
`context` node so that we can store arbitrary context like this inside
the Ast directly. This allows us to share information with the sub tree
_while doing the Ast walk_.
Here's an example of how the new `context` node can be used to share
information with subtrees:
```ts
const ast = [
rule('.foo', [decl('color', 'red')]),
context({ value: 'a' }, [
rule('.bar', [
decl('color', 'blue'),
context({ value: 'b' }, [
rule('.baz', [decl('color', 'green')]),
]),
]),
]),
]
walk(ast, (node, { context }) => {
if (node.kind !== 'declaration') return
switch (node.value) {
case 'red': assert(context.value === undefined)
case 'blue': assert(context.value === 'a')
case 'green': assert(context.value === 'b')
}
})
```
In core, we use this new Ast node specifically to persist the `base`
path of the current CSS file. We put the input CSS file `base` at the
root of the Ast and then overwrite the `base` on every `@import`
substitution.
### Removing the dependency on `postcss-import`
Now that we support `@import` resolution in core, our clients no longer
need a dependency on `postcss-import`. Furthermore, most dependencies
also don't need to know about `postcss` at all anymore (except the
PostCSS client, of course!).
This also means that our workaround for rewriting `@source`, the
`postcss-fix-relative-paths` plugin, can now go away as a shared
dependency between all of our clients. Note that we still have it for
the PostCSS plugin only, where it's possible that users already have
`postcss-import` running _before_ the `@tailwindcss/postcss` plugin.
Here's an example of the changes to the dependencies for our Vite client
✨ :
<img width="854" alt="Screenshot 2024-09-19 at 16 59 45"
src="https://github.com/user-attachments/assets/ae1f9d5f-d93a-4de9-9244-61af3aff1237">
### Performance
Since our Vite and CLI clients now no longer need to use `postcss` at
all, we have also measured a significant improvement to the initial
build times. For a small test setup that contains only a hand full of
files (nothing super-complex), we measured an improvement in the
**3.5x** range:
<img width="1334" alt="Screenshot 2024-09-19 at 14 52 49"
src="https://github.com/user-attachments/assets/06071fb0-7f2a-4de6-8ec8-f202d2cc78e5">
The code for this is in the commit history if you want to reproduce the
results. The test was based on the Vite client.
### Caveats
One thing to note is that we previously relied on finding specific
symbols in the input CSS to _bail out of Tailwind processing
completely_. E.g. if a file does not contain a `@tailwind` or `@apply`
directive, it can never be a Tailwind file.
Since we no longer have a string representation of the flattened CSS
file, we can no longer do this check. However, the current
implementation was already inconsistent with differences on the allowed
symbol list between our clients. Ideally, Tailwind CSS should figure out
wether a CSS file is a Tailwind CSS file. This, however, is left as an
improvement for a future API since it goes hand-in-hand with our planned
API changes for the core `tailwindcss` package.
---------
Co-authored-by: Jordan Pittman <jordan@cryptica.me>
2024-09-23 17:05:55 +02:00
|
|
|
@import 'tailwindcss/utilities';
|
|
|
|
|
@config '../tailwind.config.js';
|
|
|
|
|
@source '../../project-b/src/**/*.html';
|
|
|
|
|
@plugin '../plugin.js';
|
|
|
|
|
`,
|
|
|
|
|
'project-a/src/index.js': js`
|
|
|
|
|
const className = "content-['a/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
|
|
|
|
`,
|
|
|
|
|
'project-b/src/index.html': html`
|
|
|
|
|
<div class="flex" />
|
|
|
|
|
`,
|
|
|
|
|
'project-b/src/index.js': js`
|
|
|
|
|
const className = "content-['b/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
|
|
|
|
`,
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
async ({ root, fs, exec }) => {
|
|
|
|
|
await exec('pnpm postcss src/index.css --output dist/out.css', {
|
|
|
|
|
cwd: path.join(root, 'project-a'),
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
await fs.expectFileToContain('project-a/dist/out.css', [
|
|
|
|
|
candidate`underline`,
|
|
|
|
|
candidate`flex`,
|
|
|
|
|
candidate`content-['a/src/index.js']`,
|
|
|
|
|
candidate`content-['b/src/index.js']`,
|
|
|
|
|
candidate`inverted:flex`,
|
|
|
|
|
candidate`hocus:underline`,
|
|
|
|
|
])
|
|
|
|
|
},
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
test(
|
|
|
|
|
'production build with `postcss-import` (string)',
|
|
|
|
|
{
|
|
|
|
|
fs: {
|
|
|
|
|
'package.json': json`{}`,
|
|
|
|
|
'pnpm-workspace.yaml': yaml`
|
|
|
|
|
#
|
|
|
|
|
packages:
|
|
|
|
|
- project-a
|
|
|
|
|
`,
|
|
|
|
|
'project-a/package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"dependencies": {
|
|
|
|
|
"postcss": "^8",
|
|
|
|
|
"postcss-cli": "^10",
|
|
|
|
|
"postcss-import": "^16",
|
|
|
|
|
"tailwindcss": "workspace:^",
|
|
|
|
|
"@tailwindcss/postcss": "workspace:^"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/postcss.config.js': js`
|
|
|
|
|
module.exports = {
|
|
|
|
|
plugins: {
|
|
|
|
|
'postcss-import': {},
|
|
|
|
|
'@tailwindcss/postcss': {},
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/index.html': html`
|
|
|
|
|
<div
|
|
|
|
|
class="underline 2xl:font-bold hocus:underline inverted:flex"
|
|
|
|
|
></div>
|
|
|
|
|
`,
|
|
|
|
|
'project-a/plugin.js': js`
|
|
|
|
|
module.exports = function ({ addVariant }) {
|
|
|
|
|
addVariant('inverted', '@media (inverted-colors: inverted)')
|
|
|
|
|
addVariant('hocus', ['&:focus', '&:hover'])
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/tailwind.config.js': js`
|
|
|
|
|
module.exports = {
|
|
|
|
|
content: ['../project-b/src/**/*.js'],
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/src/index.css': css`
|
2024-08-07 16:38:44 +02:00
|
|
|
@import 'tailwindcss/utilities';
|
2024-09-03 16:54:08 +02:00
|
|
|
@config '../tailwind.config.js';
|
|
|
|
|
@source '../../project-b/src/**/*.html';
|
2024-08-07 16:38:44 +02:00
|
|
|
@plugin '../plugin.js';
|
|
|
|
|
`,
|
|
|
|
|
'project-a/src/index.js': js`
|
|
|
|
|
const className = "content-['a/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
|
|
|
|
`,
|
2024-09-03 16:54:08 +02:00
|
|
|
'project-b/src/index.html': html`
|
|
|
|
|
<div class="flex" />
|
|
|
|
|
`,
|
2024-08-07 16:38:44 +02:00
|
|
|
'project-b/src/index.js': js`
|
|
|
|
|
const className = "content-['b/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
2024-08-08 17:49:06 +02:00
|
|
|
`,
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
async ({ root, fs, exec }) => {
|
|
|
|
|
await exec('pnpm postcss src/index.css --output dist/out.css', {
|
|
|
|
|
cwd: path.join(root, 'project-a'),
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
await fs.expectFileToContain('project-a/dist/out.css', [
|
|
|
|
|
candidate`underline`,
|
2024-09-03 16:54:08 +02:00
|
|
|
candidate`flex`,
|
2024-08-08 17:49:06 +02:00
|
|
|
candidate`content-['a/src/index.js']`,
|
|
|
|
|
candidate`content-['b/src/index.js']`,
|
|
|
|
|
candidate`inverted:flex`,
|
|
|
|
|
candidate`hocus:underline`,
|
|
|
|
|
])
|
|
|
|
|
},
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
test(
|
|
|
|
|
'production build (ESM)',
|
|
|
|
|
{
|
|
|
|
|
fs: {
|
|
|
|
|
'package.json': json`{}`,
|
|
|
|
|
'pnpm-workspace.yaml': yaml`
|
|
|
|
|
#
|
|
|
|
|
packages:
|
|
|
|
|
- project-a
|
|
|
|
|
`,
|
|
|
|
|
'project-a/package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"dependencies": {
|
|
|
|
|
"postcss": "^8",
|
|
|
|
|
"postcss-cli": "^10",
|
|
|
|
|
"tailwindcss": "workspace:^",
|
|
|
|
|
"@tailwindcss/postcss": "workspace:^"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/postcss.config.mjs': js`
|
|
|
|
|
import tailwindcss from '@tailwindcss/postcss'
|
|
|
|
|
export default {
|
|
|
|
|
plugins: [tailwindcss()],
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/index.html': html`
|
|
|
|
|
<div
|
|
|
|
|
class="underline 2xl:font-bold hocus:underline inverted:flex"
|
|
|
|
|
></div>
|
|
|
|
|
`,
|
|
|
|
|
'project-a/plugin.js': js`
|
|
|
|
|
module.exports = function ({ addVariant }) {
|
|
|
|
|
addVariant('inverted', '@media (inverted-colors: inverted)')
|
|
|
|
|
addVariant('hocus', ['&:focus', '&:hover'])
|
|
|
|
|
}
|
|
|
|
|
`,
|
2024-09-03 16:54:08 +02:00
|
|
|
'project-a/tailwind.config.js': js`
|
|
|
|
|
module.exports = {
|
|
|
|
|
content: ['../project-b/src/**/*.js'],
|
|
|
|
|
}
|
|
|
|
|
`,
|
2024-08-08 17:49:06 +02:00
|
|
|
'project-a/src/index.css': css`
|
|
|
|
|
@import 'tailwindcss/utilities';
|
2024-09-03 16:54:08 +02:00
|
|
|
@config '../tailwind.config.js';
|
|
|
|
|
@source '../../project-b/src/**/*.html';
|
2024-08-08 17:49:06 +02:00
|
|
|
@plugin '../plugin.js';
|
|
|
|
|
`,
|
|
|
|
|
'project-a/src/index.js': js`
|
|
|
|
|
const className = "content-['a/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
|
|
|
|
`,
|
2024-09-03 16:54:08 +02:00
|
|
|
'project-b/src/index.html': html`
|
|
|
|
|
<div class="flex" />
|
|
|
|
|
`,
|
2024-08-08 17:49:06 +02:00
|
|
|
'project-b/src/index.js': js`
|
|
|
|
|
const className = "content-['b/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
|
|
|
|
`,
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
async ({ root, fs, exec }) => {
|
|
|
|
|
await exec('pnpm postcss src/index.css --output dist/out.css', {
|
|
|
|
|
cwd: path.join(root, 'project-a'),
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
await fs.expectFileToContain('project-a/dist/out.css', [
|
|
|
|
|
candidate`underline`,
|
2024-09-03 16:54:08 +02:00
|
|
|
candidate`flex`,
|
2024-08-08 17:49:06 +02:00
|
|
|
candidate`content-['a/src/index.js']`,
|
|
|
|
|
candidate`content-['b/src/index.js']`,
|
|
|
|
|
candidate`inverted:flex`,
|
|
|
|
|
candidate`hocus:underline`,
|
|
|
|
|
])
|
|
|
|
|
},
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
test(
|
|
|
|
|
'production build (CJS)',
|
|
|
|
|
{
|
|
|
|
|
fs: {
|
|
|
|
|
'package.json': json`{}`,
|
|
|
|
|
'pnpm-workspace.yaml': yaml`
|
|
|
|
|
#
|
|
|
|
|
packages:
|
|
|
|
|
- project-a
|
|
|
|
|
`,
|
|
|
|
|
'project-a/package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"dependencies": {
|
|
|
|
|
"postcss": "^8",
|
|
|
|
|
"postcss-cli": "^10",
|
|
|
|
|
"tailwindcss": "workspace:^",
|
|
|
|
|
"@tailwindcss/postcss": "workspace:^"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/postcss.config.cjs': js`
|
|
|
|
|
let tailwindcss = require('@tailwindcss/postcss')
|
|
|
|
|
module.exports = {
|
|
|
|
|
plugins: [tailwindcss()],
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/index.html': html`
|
|
|
|
|
<div
|
|
|
|
|
class="underline 2xl:font-bold hocus:underline inverted:flex"
|
|
|
|
|
></div>
|
|
|
|
|
`,
|
|
|
|
|
'project-a/plugin.js': js`
|
|
|
|
|
module.exports = function ({ addVariant }) {
|
|
|
|
|
addVariant('inverted', '@media (inverted-colors: inverted)')
|
|
|
|
|
addVariant('hocus', ['&:focus', '&:hover'])
|
|
|
|
|
}
|
|
|
|
|
`,
|
2024-09-03 16:54:08 +02:00
|
|
|
'project-a/tailwind.config.js': js`
|
|
|
|
|
module.exports = {
|
|
|
|
|
content: ['../project-b/src/**/*.js'],
|
|
|
|
|
}
|
|
|
|
|
`,
|
2024-08-08 17:49:06 +02:00
|
|
|
'project-a/src/index.css': css`
|
|
|
|
|
@import 'tailwindcss/utilities';
|
2024-09-03 16:54:08 +02:00
|
|
|
@config '../tailwind.config.js';
|
|
|
|
|
@source '../../project-b/src/**/*.html';
|
2024-08-08 17:49:06 +02:00
|
|
|
@plugin '../plugin.js';
|
|
|
|
|
`,
|
|
|
|
|
'project-a/src/index.js': js`
|
|
|
|
|
const className = "content-['a/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
|
|
|
|
`,
|
2024-09-03 16:54:08 +02:00
|
|
|
'project-b/src/index.html': html`
|
|
|
|
|
<div class="flex" />
|
|
|
|
|
`,
|
2024-08-08 17:49:06 +02:00
|
|
|
'project-b/src/index.js': js`
|
|
|
|
|
const className = "content-['b/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
2024-08-07 16:38:44 +02:00
|
|
|
`,
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
async ({ root, fs, exec }) => {
|
|
|
|
|
await exec('pnpm postcss src/index.css --output dist/out.css', {
|
|
|
|
|
cwd: path.join(root, 'project-a'),
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
await fs.expectFileToContain('project-a/dist/out.css', [
|
|
|
|
|
candidate`underline`,
|
2024-09-03 16:54:08 +02:00
|
|
|
candidate`flex`,
|
2024-08-07 16:38:44 +02:00
|
|
|
candidate`content-['a/src/index.js']`,
|
|
|
|
|
candidate`content-['b/src/index.js']`,
|
|
|
|
|
candidate`inverted:flex`,
|
|
|
|
|
candidate`hocus:underline`,
|
|
|
|
|
])
|
|
|
|
|
},
|
|
|
|
|
)
|
|
|
|
|
|
2024-11-19 18:39:49 +01:00
|
|
|
test(
|
|
|
|
|
'module resolution using CJS, ESM, CTS, and MTS',
|
|
|
|
|
{
|
|
|
|
|
fs: {
|
|
|
|
|
'package.json': json`{}`,
|
|
|
|
|
'pnpm-workspace.yaml': yaml`
|
|
|
|
|
#
|
|
|
|
|
packages:
|
|
|
|
|
- project-cjs
|
|
|
|
|
- project-esm
|
|
|
|
|
- plugin-cjs
|
|
|
|
|
- plugin-esm
|
|
|
|
|
- plugin-cts
|
|
|
|
|
- plugin-mts
|
|
|
|
|
`,
|
|
|
|
|
'project-cjs/package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"type": "commonjs",
|
|
|
|
|
"dependencies": {
|
|
|
|
|
"@tailwindcss/postcss": "workspace:^",
|
|
|
|
|
"plugin-cjs": "workspace:*",
|
|
|
|
|
"plugin-cts": "workspace:*",
|
|
|
|
|
"plugin-esm": "workspace:*",
|
|
|
|
|
"plugin-mts": "workspace:*",
|
|
|
|
|
"postcss": "^8",
|
|
|
|
|
"postcss-cli": "^10",
|
|
|
|
|
"tailwindcss": "workspace:^"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-cjs/postcss.config.cjs': js`
|
|
|
|
|
let tailwindcss = require('@tailwindcss/postcss')
|
|
|
|
|
module.exports = {
|
|
|
|
|
plugins: [tailwindcss()],
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-cjs/index.html': html`
|
|
|
|
|
<div class="cjs esm cts mts"></div>
|
|
|
|
|
`,
|
|
|
|
|
'project-cjs/src/index.css': css`
|
|
|
|
|
@import 'tailwindcss/utilities';
|
|
|
|
|
@plugin 'plugin-cjs';
|
|
|
|
|
@plugin 'plugin-esm';
|
|
|
|
|
@plugin 'plugin-cts';
|
|
|
|
|
@plugin 'plugin-mts';
|
|
|
|
|
`,
|
|
|
|
|
|
|
|
|
|
'project-esm/package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"type": "module",
|
|
|
|
|
"dependencies": {
|
|
|
|
|
"@tailwindcss/postcss": "workspace:^",
|
|
|
|
|
"plugin-cjs": "workspace:*",
|
|
|
|
|
"plugin-cts": "workspace:*",
|
|
|
|
|
"plugin-esm": "workspace:*",
|
|
|
|
|
"plugin-mts": "workspace:*",
|
|
|
|
|
"postcss": "^8",
|
|
|
|
|
"postcss-cli": "^10",
|
|
|
|
|
"tailwindcss": "workspace:^"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-esm/postcss.config.mjs': js`
|
|
|
|
|
import tailwindcss from '@tailwindcss/postcss'
|
|
|
|
|
export default {
|
|
|
|
|
plugins: [tailwindcss()],
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-esm/index.html': html`
|
|
|
|
|
<div class="cjs esm cts mts"></div>
|
|
|
|
|
`,
|
|
|
|
|
'project-esm/src/index.css': css`
|
|
|
|
|
@import 'tailwindcss/utilities';
|
|
|
|
|
@plugin 'plugin-cjs';
|
|
|
|
|
@plugin 'plugin-esm';
|
|
|
|
|
@plugin 'plugin-cts';
|
|
|
|
|
@plugin 'plugin-mts';
|
|
|
|
|
`,
|
|
|
|
|
|
|
|
|
|
'plugin-cjs/package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"name": "plugin-cjs",
|
|
|
|
|
"type": "commonjs",
|
|
|
|
|
"exports": {
|
|
|
|
|
".": {
|
|
|
|
|
"require": "./index.cjs"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'plugin-cjs/index.cjs': js`
|
|
|
|
|
module.exports = function ({ addUtilities }) {
|
|
|
|
|
addUtilities({ '.cjs': { content: '"cjs"' } })
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
|
|
|
|
|
'plugin-esm/package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"name": "plugin-esm",
|
|
|
|
|
"type": "module",
|
|
|
|
|
"exports": {
|
|
|
|
|
".": {
|
|
|
|
|
"import": "./index.mjs"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'plugin-esm/index.mjs': js`
|
|
|
|
|
export default function ({ addUtilities }) {
|
|
|
|
|
addUtilities({ '.esm': { content: '"esm"' } })
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
|
|
|
|
|
'plugin-cts/package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"name": "plugin-cts",
|
|
|
|
|
"type": "commonjs",
|
|
|
|
|
"exports": {
|
|
|
|
|
".": {
|
|
|
|
|
"require": "./index.cts"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'plugin-cts/index.cts': ts`
|
|
|
|
|
export default function ({ addUtilities }) {
|
|
|
|
|
addUtilities({ '.cts': { content: '"cts"' as const } })
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
|
|
|
|
|
'plugin-mts/package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"name": "plugin-mts",
|
|
|
|
|
"type": "module",
|
|
|
|
|
"exports": {
|
|
|
|
|
".": {
|
|
|
|
|
"import": "./index.mts"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'plugin-mts/index.mts': ts`
|
|
|
|
|
export default function ({ addUtilities }) {
|
|
|
|
|
addUtilities({ '.mts': { content: '"mts"' as const } })
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
async ({ root, fs, exec }) => {
|
|
|
|
|
await exec(`pnpm postcss src/index.css --output dist/out.css`, {
|
|
|
|
|
cwd: path.join(root, 'project-cjs'),
|
|
|
|
|
})
|
|
|
|
|
await exec(`pnpm postcss src/index.css --output dist/out.css`, {
|
|
|
|
|
cwd: path.join(root, 'project-esm'),
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
await fs.expectFileToContain('./project-cjs/dist/out.css', [
|
|
|
|
|
candidate`cjs`,
|
|
|
|
|
candidate`esm`,
|
|
|
|
|
candidate`cts`,
|
|
|
|
|
candidate`mts`,
|
|
|
|
|
])
|
|
|
|
|
await fs.expectFileToContain('./project-esm/dist/out.css', [
|
|
|
|
|
candidate`cjs`,
|
|
|
|
|
candidate`esm`,
|
|
|
|
|
candidate`cts`,
|
|
|
|
|
candidate`mts`,
|
|
|
|
|
])
|
|
|
|
|
},
|
|
|
|
|
)
|
|
|
|
|
|
2024-08-07 16:38:44 +02:00
|
|
|
test(
|
|
|
|
|
'watch mode',
|
|
|
|
|
{
|
|
|
|
|
fs: {
|
|
|
|
|
'package.json': json`{}`,
|
|
|
|
|
'pnpm-workspace.yaml': yaml`
|
|
|
|
|
#
|
|
|
|
|
packages:
|
|
|
|
|
- project-a
|
|
|
|
|
`,
|
|
|
|
|
'project-a/package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"dependencies": {
|
|
|
|
|
"postcss": "^8",
|
|
|
|
|
"postcss-cli": "^10",
|
|
|
|
|
"tailwindcss": "workspace:^",
|
|
|
|
|
"@tailwindcss/postcss": "workspace:^"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/postcss.config.js': js`
|
|
|
|
|
module.exports = {
|
|
|
|
|
plugins: {
|
|
|
|
|
'@tailwindcss/postcss': {},
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'project-a/index.html': html`
|
|
|
|
|
<div
|
2024-10-01 13:52:12 +02:00
|
|
|
class="underline 2xl:font-bold hocus:underline inverted:flex text-primary"
|
2024-08-07 16:38:44 +02:00
|
|
|
></div>
|
|
|
|
|
`,
|
|
|
|
|
'project-a/plugin.js': js`
|
|
|
|
|
module.exports = function ({ addVariant }) {
|
|
|
|
|
addVariant('inverted', '@media (inverted-colors: inverted)')
|
|
|
|
|
addVariant('hocus', ['&:focus', '&:hover'])
|
|
|
|
|
}
|
|
|
|
|
`,
|
2024-09-03 16:54:08 +02:00
|
|
|
'project-a/tailwind.config.js': js`
|
|
|
|
|
module.exports = {
|
|
|
|
|
content: ['../project-b/src/**/*.js'],
|
|
|
|
|
}
|
|
|
|
|
`,
|
2024-08-07 16:38:44 +02:00
|
|
|
'project-a/src/index.css': css`
|
|
|
|
|
@import 'tailwindcss/utilities';
|
2024-10-01 13:52:12 +02:00
|
|
|
@import './custom-theme.css';
|
2024-09-03 16:54:08 +02:00
|
|
|
@config '../tailwind.config.js';
|
|
|
|
|
@source '../../project-b/src/**/*.html';
|
2024-08-07 16:38:44 +02:00
|
|
|
@plugin '../plugin.js';
|
|
|
|
|
`,
|
2024-10-01 13:52:12 +02:00
|
|
|
'project-a/src/custom-theme.css': css`
|
|
|
|
|
/* Will be overwritten later */
|
|
|
|
|
@theme {
|
|
|
|
|
--color-primary: black;
|
|
|
|
|
}
|
|
|
|
|
`,
|
2024-08-07 16:38:44 +02:00
|
|
|
'project-a/src/index.js': js`
|
|
|
|
|
const className = "content-['a/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
|
|
|
|
`,
|
2024-09-03 16:54:08 +02:00
|
|
|
'project-b/src/index.html': html`
|
|
|
|
|
<div class="flex" />
|
|
|
|
|
`,
|
2024-08-07 16:38:44 +02:00
|
|
|
'project-b/src/index.js': js`
|
|
|
|
|
const className = "content-['b/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
|
|
|
|
`,
|
2024-10-03 16:21:54 +02:00
|
|
|
'project-c/src/index.js': js`
|
|
|
|
|
const className = "content-['c/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
|
|
|
|
`,
|
2024-08-07 16:38:44 +02:00
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
async ({ root, fs, spawn }) => {
|
|
|
|
|
let process = await spawn(
|
|
|
|
|
'pnpm postcss src/index.css --output dist/out.css --watch --verbose',
|
|
|
|
|
{ cwd: path.join(root, 'project-a') },
|
|
|
|
|
)
|
|
|
|
|
await process.onStderr((message) => message.includes('Waiting for file changes...'))
|
|
|
|
|
|
|
|
|
|
await fs.expectFileToContain('project-a/dist/out.css', [
|
|
|
|
|
candidate`underline`,
|
2024-09-03 16:54:08 +02:00
|
|
|
candidate`flex`,
|
2024-08-07 16:38:44 +02:00
|
|
|
candidate`content-['a/src/index.js']`,
|
|
|
|
|
candidate`content-['b/src/index.js']`,
|
|
|
|
|
candidate`inverted:flex`,
|
|
|
|
|
candidate`hocus:underline`,
|
2024-10-01 13:52:12 +02:00
|
|
|
css`
|
|
|
|
|
.text-primary {
|
2024-11-05 15:44:21 -05:00
|
|
|
color: var(--color-primary);
|
2024-10-01 13:52:12 +02:00
|
|
|
}
|
|
|
|
|
`,
|
2024-08-07 16:38:44 +02:00
|
|
|
])
|
|
|
|
|
|
|
|
|
|
await fs.write(
|
|
|
|
|
'project-a/src/index.js',
|
|
|
|
|
js`
|
|
|
|
|
const className = "[.changed_&]:content-['project-a/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
|
|
|
|
`,
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
await fs.expectFileToContain('project-a/dist/out.css', [
|
|
|
|
|
candidate`[.changed_&]:content-['project-a/src/index.js']`,
|
|
|
|
|
])
|
|
|
|
|
|
|
|
|
|
await fs.write(
|
|
|
|
|
'project-b/src/index.js',
|
|
|
|
|
js`
|
|
|
|
|
const className = "[.changed_&]:content-['project-b/src/index.js']"
|
|
|
|
|
module.exports = { className }
|
|
|
|
|
`,
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
await fs.expectFileToContain('project-a/dist/out.css', [
|
|
|
|
|
candidate`[.changed_&]:content-['project-b/src/index.js']`,
|
|
|
|
|
])
|
2024-10-01 13:52:12 +02:00
|
|
|
|
|
|
|
|
await fs.write(
|
|
|
|
|
'project-a/src/custom-theme.css',
|
|
|
|
|
css`
|
|
|
|
|
/* Overriding the primary color */
|
|
|
|
|
@theme {
|
|
|
|
|
--color-primary: red;
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
await fs.expectFileToContain('project-a/dist/out.css', [
|
|
|
|
|
css`
|
|
|
|
|
.text-primary {
|
2024-11-05 15:44:21 -05:00
|
|
|
color: var(--color-primary);
|
2024-10-01 13:52:12 +02:00
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
])
|
2024-10-03 16:21:54 +02:00
|
|
|
|
|
|
|
|
// Adding a new @source directive will scan for new candidates
|
|
|
|
|
await fs.write(
|
|
|
|
|
'project-a/src/index.css',
|
|
|
|
|
css`
|
|
|
|
|
@import 'tailwindcss/utilities';
|
|
|
|
|
@import './custom-theme.css';
|
|
|
|
|
@config '../tailwind.config.js';
|
|
|
|
|
@source '../../project-b/src/**/*.html';
|
|
|
|
|
@plugin '../plugin.js';
|
|
|
|
|
@source '../../project-c/src/**/*.js';
|
|
|
|
|
`,
|
|
|
|
|
)
|
|
|
|
|
await fs.expectFileToContain('project-a/dist/out.css', [candidate`content-['c/src/index.js']`])
|
2024-08-07 16:38:44 +02:00
|
|
|
},
|
|
|
|
|
)
|
2025-04-25 12:02:10 +02:00
|
|
|
|
2025-04-29 18:16:58 +02:00
|
|
|
test(
|
|
|
|
|
'rebuild error recovery',
|
|
|
|
|
{
|
|
|
|
|
fs: {
|
|
|
|
|
'package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"devDependencies": {
|
|
|
|
|
"postcss": "^8",
|
|
|
|
|
"postcss-cli": "^10",
|
|
|
|
|
"tailwindcss": "workspace:^",
|
|
|
|
|
"@tailwindcss/postcss": "workspace:^"
|
2025-04-28 10:53:39 +02:00
|
|
|
}
|
2025-04-29 18:16:58 +02:00
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'postcss.config.js': js`
|
|
|
|
|
module.exports = {
|
|
|
|
|
plugins: {
|
|
|
|
|
'@tailwindcss/postcss': {},
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'src/index.html': html`
|
2025-04-25 12:02:10 +02:00
|
|
|
<div class="underline"></div>
|
|
|
|
|
`,
|
2025-04-29 18:16:58 +02:00
|
|
|
'src/index.css': css` @import './tailwind.css'; `,
|
|
|
|
|
'src/tailwind.css': css`
|
|
|
|
|
@reference 'tailwindcss/does-not-exist';
|
|
|
|
|
@import 'tailwindcss/utilities';
|
|
|
|
|
`,
|
2025-04-25 12:02:10 +02:00
|
|
|
},
|
2025-04-29 18:16:58 +02:00
|
|
|
},
|
|
|
|
|
async ({ fs, expect, spawn }) => {
|
|
|
|
|
let process = await spawn('pnpm postcss src/index.css --output dist/out.css --watch --verbose')
|
2025-04-25 12:02:10 +02:00
|
|
|
|
2025-04-29 18:16:58 +02:00
|
|
|
await process.onStderr((message) =>
|
|
|
|
|
message.includes('does-not-exist is not exported from package'),
|
|
|
|
|
)
|
2025-04-25 12:02:10 +02:00
|
|
|
|
2025-04-29 18:16:58 +02:00
|
|
|
await retryAssertion(async () => expect(await fs.read('dist/out.css')).toEqual(''))
|
2025-04-25 12:02:10 +02:00
|
|
|
|
2025-04-29 18:16:58 +02:00
|
|
|
await process.onStderr((message) => message.includes('Waiting for file changes...'))
|
2025-04-25 12:02:10 +02:00
|
|
|
|
2025-04-29 18:16:58 +02:00
|
|
|
// Fix the CSS file
|
|
|
|
|
await fs.write(
|
|
|
|
|
'src/tailwind.css',
|
|
|
|
|
css`
|
|
|
|
|
@reference 'tailwindcss/theme';
|
|
|
|
|
@import 'tailwindcss/utilities';
|
|
|
|
|
`,
|
|
|
|
|
)
|
|
|
|
|
await process.onStderr((message) => message.includes('Finished'))
|
2025-04-25 12:02:10 +02:00
|
|
|
|
2025-04-29 18:16:58 +02:00
|
|
|
expect(await fs.dumpFiles('dist/*.css')).toMatchInlineSnapshot(`
|
2025-04-25 12:02:10 +02:00
|
|
|
"
|
|
|
|
|
--- dist/out.css ---
|
|
|
|
|
.underline {
|
|
|
|
|
text-decoration-line: underline;
|
|
|
|
|
}
|
|
|
|
|
"
|
|
|
|
|
`)
|
|
|
|
|
|
2025-04-29 18:16:58 +02:00
|
|
|
// Now break the CSS file again
|
|
|
|
|
await fs.write(
|
|
|
|
|
'src/tailwind.css',
|
|
|
|
|
css`
|
|
|
|
|
@reference 'tailwindcss/does-not-exist';
|
|
|
|
|
@import 'tailwindcss/utilities';
|
|
|
|
|
`,
|
|
|
|
|
)
|
|
|
|
|
await process.onStderr((message) =>
|
|
|
|
|
message.includes('does-not-exist is not exported from package'),
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
await retryAssertion(async () => expect(await fs.read('dist/out.css')).toEqual(''))
|
|
|
|
|
},
|
|
|
|
|
)
|
Add support for source maps (#17775)
Closes #13694
Closes #13591
# Source Maps Support for Tailwind CSS
This PR adds support for source maps to Tailwind CSS v4 allowing us to
track where styles come from whether that be user CSS, imported
stylesheets, or generated utilities. This will improve debuggability in
browser dev tools and gives us a good foundation for producing better
error messages. I'll go over the details on how end users can enable
source maps, any limitations in our implementation, changes to the
internal `compile(…)` API, and some details and reasoning around the
implementation we chose.
## Usage
### CLI
Source maps can be enabled in the CLI by using the command line argument
`--map` which will generate an inline source map comment at the bottom
of your CSS. A separate file may be generated by passing a file name to
`--map`:
```bash
# Generates an inline source map
npx tailwindcss -i input.css -o output.css --map
# Generates a separate source map file
npx tailwindcss -i input.css -o output.css --map output.css.map
```
### PostCSS
Source maps are supported when using Tailwind as a PostCSS plugin *in
development mode only*. They may or may not be enabled by default
depending on your build tool. If they are not you may be able to
configure them within your PostCSS config:
```jsonc
// package.json
{
// …
"postcss": {
"map": { "inline": true },
"plugins": {
"@tailwindcss/postcss": {},
},
}
}
```
### Vite
Source maps are supported when using the Tailwind CSS Vite plugin in
*development mode only* by enabling the `css.devSourcemap` setting:
```js
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [tailwindcss()],
css: {
devSourcemap: true,
},
})
```
Now when a CSS file is requested by the browser it'll have an inline
source map comment that the browser can use.
## Limitations
- Production build source maps are currently disabled due to a bug in
Lightning CSS. See
https://github.com/parcel-bundler/lightningcss/pull/971 for more
details.
- In Vite, minified CSS build source maps are not supported at all. See
https://github.com/vitejs/vite/issues/2830 for more details.
- In PostCSS, minified CSS source maps are not supported. This is due to
the complexity required around re-associating every AST node with a
location in the generated, optimized CSS. This complexity would also
have a non-trivial performance impact.
## Testing
Here's how to test the source map functionality in different
environments:
### Testing the CLI
1. Setup typical project that the CLI can use and with sources to scan.
```css
@import "tailwindcss";
@utilty my-custom-utility {
color: red;
}
/* to test `@apply` */
.card {
@apply bg-white text-center shadow-md;
}
```
2. Build with source maps:
```bash
bun /path/to/tailwindcss/packages/@tailwindcss-cli/src/index.ts --input input.css -o output.css --map
```
3. Open Chrome DevTools, inspect an element with utility classes, and
you should see rules pointing to `input.css` or
`node_modules/tailwindcss/index.css`
### Testing with Vite
Testing in Vite will require building and installing necessary files
under `dist/*.tgz`.
1. Create a Vite project and enable source maps in `vite.config.js`:
```js
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [tailwindcss()],
css: {
// This line is required for them to work
devSourcemap: true,
},
})
```
2. Add a component that uses Tailwind classes and custom CSS:
```jsx
// ./src/app.jsx
export default function App() {
return (
<div className="bg-blue-500 my-custom-class">
Hello World
</div>
)
}
```
```css
/* ./src/styles.css */
@import "tailwindcss";
@utilty my-custom-utility {
color: red;
}
/* to test `@apply` */
.card {
@apply bg-white text-center shadow-md;
}
```
3. Run `npm run dev`, open DevTools, and inspect elements to verify
source mapping works for both utility classes and custom CSS.
### Testing with PostCSS CLI
1. Create a test file and update your PostCSS config:
```css
/* input.css */
@import "tailwindcss";
@layer components {
.card {
@apply p-6 rounded-lg shadow-lg;
}
}
```
```jsonc
// package.json
{
// …
"postcss": {
"map": {
"inline": true
},
"plugins": {
"/path/to/tailwindcss/packages/packages/@tailwindcss-postcss/src/index.ts": {}
}
}
}
```
2. Run PostCSS through Bun:
```bash
bunx --bun postcss ./src/index.css -o out.css
```
3. Inspect the output CSS - it should include an inline source map
comment at the bottom.
### Testing with PostCSS + Next.js
Testing in Next.js will require building and installing necessary files
under `dist/*.tgz`. However, I've not been able to get CSS source maps
to work in Next.js without this hack:
```js
const nextConfig: NextConfig = {
// next.js overwrites config.devtool so we prevent it from doing so
// please don't actually do this…
webpack: (config) =>
Object.defineProperty(config, "devtool", {
get: () => "inline-source-map",
set: () => {},
}),
};
```
This is definitely not supported and also doesn't work with turbopack.
This can be used to test them temporarily but I suspect that they just
don't work there.
### Manual source map analysis
You can analyze source maps using Evan Wallace's [Source Map
Visualization](https://evanw.github.io/source-map-visualization/) tool
which will help to verify the accuracy and quality of source maps. This
is what I used extensively while developing this implementation.
It'll help verify that custom, user CSS maps back to itself in the
input, that generated utilities all map back to `@tailwind utilities;`,
that source locations from imported files are also handled correctly,
etc… It also highlights the ranges of stuff so it's easy to see if there
are off-by-one errors.
It's easiest to use inline source maps with this tool because you can
take the CSS file and drop it on the page and it'll analyze it while
showing the file content.
If you're using Vite you'll want to access the CSS file with `?direct`
at the end so you don't get a JS module back.
## Implementation
The source map implementation follows the ECMA-426 specification and
includes several key components to aid in that goal:
### Source Location Tracking
Each emittable AST node in the compilation pipeline tracks two types of
source locations:
- `src`: Original source location - [source file, start offset, end
offset]
- `dst`: Generated source location - [output file, start offset, end
offset]
This dual tracking allows us to maintain mappings between the original
source and generated output for things like user CSS, generated
utilities, uses of `@apply`, and tracking theme variables.
It is important to note that source locations for nodes _never overlap_
within a file which helps simplify source map generation. As such each
type of node tracks a specific piece of itself rather than its entire
"block":
| Node | What a `SourceLocation` represents |
| ----------- |
---------------------------------------------------------------- |
| Style Rule | The selector |
| At Rule | Rule name and params, includes the `@` |
| Declaration | Property name and value, excludes the semicolon |
| Comment | The entire comment, includes the start `/*` and end `*/`
markers |
### Windows line endings when parsing CSS
Because our AST tracks nodes through offsets we must ensure that any
mutations to the file do *not* change the lenth of the string. We were
previously replacing `\r\n` with `\n` (see [filter code
points](https://drafts.csswg.org/css-syntax/#css-filter-code-points)
from the spec) — which changes the length of the string and all offsets
may end up incorrect. The CSS parser was updated to handle the CRLF
token directly by skipping over the `\r` and letting remaining code
handle `\n` as it did previously. Some additional tweaks were required
when "peeking" the input but those changes were fairly small.
### Tracking of imports
Source maps need paths to the actual imported stylesheets but the
resolve step for stylesheets happens inside the call to `loadStylesheet`
which make the file path unavailable to us. Because of this the
`loadStylesheet` API was augmented such that it has to return a `path`
property that we can then use to identify imported sources. I've also
made the same change to the `loadModule` API for consistency but nothing
currently uses this property.
The `path` property likely makes `base` redundant but elminating that
(if we even want to) is a future task.
### Optimizing the AST
Our optimization pass may intoduce some nodes, for example, fallbacks we
create for `@property`. These nodes are linked back to `@tailwind
utilities` as ultimately that is what is responsible for creating them.
### Line Offset Tables
A key component to our source map generation is the line offset table,
which was inspired by some ESBuild internals. It stores a sorted list of
offsets for the start of each line allowing us to translate offsets to
line/column `Position`s in `O(log N)` time and from `Position`s to
offsets in `O(1)` time. Creation of the table takes `O(N)` time.
This means that we can store code point offsets for source locations and
not have to worry about computing or tracking line/column numbers during
parsing and serialization. Only when a source map is generated do these
offsets need to be computed. This ensures the performance penalty when
not using source maps is minimal.
### Source Map Generation
The source map returned by `buildSourceMap()` is designed to follow the
[ECMA-426 spec](https://tc39.es/ecma426). Because that spec is not
completely finalized we consider the result of `buildSourceMap()` to be
internal API that may change as the spec chamges.
The produces source map is a "decoded" map such that all sources and
mappings are in an object graph. A library like `source-map-js` must be
used to convert this to an encoded source map of the right version where
mappings are encoded with base 64 VLQs.
Any specific integration (Vite, PostCSS, etc…) can then use
`toSourceMap()` from `@tailwindcss/node` to convert from the internal
source map to an spec-compliant encoded source map that can be
understood by other tools.
### Handling minification in Lightning
Since we use Lightning CSS for optimization, and it takes in an input
map, we generate an encoded source map that we then pass to lightning.
The output source map *from lighting itself* is then passed back in
during the second optimization pass. The final map is then passed from
lightning to the CLI (but not Vite or PostCSS — see the limitations
section for details).
In some cases we have to "fix up" the output CSS. When this happens we
use `magic-string` to do the replacement in a way that is trackable and
`@amppproject/remapping` to map that change back onto the original
source map. Once the need for these fix ups disappear these dependencies
can go away.
Notes:
- The accuracy of source maps run though lightning is reduced as it only
tracks on a per-rule level. This is sufficient enough for browser dev
tools so should be fine.
- Source maps during optimization do not function properly at this time
because of a bug in Lightning CSS regarding license comments. Once this
bug is fixed they will start working as expected.
### How source locations flow through the system
1. During initial CSS parsing, source locations are preserved.
2. During parsing these source locations are also mapped to the
destinations which supports an optimization for when no utilities are
generated.
3. Throughout the compilation process, transformations maintain source
location data
4. Generated utilities are explicitly pointed to `@tailwind utilities`
unless generated by `@apply`.
5. When optimization is enabled, source maps are remapped through
lightningcss
6. Final source maps are written in the requested format (inline or
separate file)
2025-05-08 16:29:49 -04:00
|
|
|
|
|
|
|
|
test(
|
|
|
|
|
'dev mode + source maps',
|
|
|
|
|
{
|
|
|
|
|
fs: {
|
|
|
|
|
'package.json': json`
|
|
|
|
|
{
|
|
|
|
|
"dependencies": {
|
|
|
|
|
"postcss": "^8",
|
|
|
|
|
"postcss-cli": "^11",
|
|
|
|
|
"tailwindcss": "workspace:^",
|
|
|
|
|
"@tailwindcss/postcss": "workspace:^"
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'postcss.config.js': js`
|
|
|
|
|
module.exports = {
|
|
|
|
|
map: { inline: true },
|
|
|
|
|
plugins: {
|
|
|
|
|
'@tailwindcss/postcss': {},
|
|
|
|
|
},
|
|
|
|
|
}
|
|
|
|
|
`,
|
|
|
|
|
'src/index.html': html`
|
|
|
|
|
<div class="flex"></div>
|
|
|
|
|
`,
|
|
|
|
|
'src/index.css': css`
|
|
|
|
|
@import 'tailwindcss/utilities';
|
|
|
|
|
@source not inline("inline");
|
|
|
|
|
/* */
|
|
|
|
|
`,
|
|
|
|
|
},
|
|
|
|
|
},
|
|
|
|
|
async ({ fs, exec, expect, parseSourceMap }) => {
|
|
|
|
|
await exec('pnpm postcss src/index.css --output dist/out.css')
|
|
|
|
|
|
|
|
|
|
await fs.expectFileToContain('dist/out.css', [candidate`flex`])
|
|
|
|
|
|
|
|
|
|
let map = parseSourceMap(await fs.read('dist/out.css'))
|
|
|
|
|
|
|
|
|
|
expect(map.at(1, 0)).toMatchObject({
|
|
|
|
|
source: '<no source>',
|
|
|
|
|
original: '(none)',
|
|
|
|
|
generated: '/*! tailwi...',
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
expect(map.at(2, 0)).toMatchObject({
|
2025-05-08 16:56:49 -04:00
|
|
|
source: expect.stringContaining('utilities.css'),
|
Add support for source maps (#17775)
Closes #13694
Closes #13591
# Source Maps Support for Tailwind CSS
This PR adds support for source maps to Tailwind CSS v4 allowing us to
track where styles come from whether that be user CSS, imported
stylesheets, or generated utilities. This will improve debuggability in
browser dev tools and gives us a good foundation for producing better
error messages. I'll go over the details on how end users can enable
source maps, any limitations in our implementation, changes to the
internal `compile(…)` API, and some details and reasoning around the
implementation we chose.
## Usage
### CLI
Source maps can be enabled in the CLI by using the command line argument
`--map` which will generate an inline source map comment at the bottom
of your CSS. A separate file may be generated by passing a file name to
`--map`:
```bash
# Generates an inline source map
npx tailwindcss -i input.css -o output.css --map
# Generates a separate source map file
npx tailwindcss -i input.css -o output.css --map output.css.map
```
### PostCSS
Source maps are supported when using Tailwind as a PostCSS plugin *in
development mode only*. They may or may not be enabled by default
depending on your build tool. If they are not you may be able to
configure them within your PostCSS config:
```jsonc
// package.json
{
// …
"postcss": {
"map": { "inline": true },
"plugins": {
"@tailwindcss/postcss": {},
},
}
}
```
### Vite
Source maps are supported when using the Tailwind CSS Vite plugin in
*development mode only* by enabling the `css.devSourcemap` setting:
```js
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [tailwindcss()],
css: {
devSourcemap: true,
},
})
```
Now when a CSS file is requested by the browser it'll have an inline
source map comment that the browser can use.
## Limitations
- Production build source maps are currently disabled due to a bug in
Lightning CSS. See
https://github.com/parcel-bundler/lightningcss/pull/971 for more
details.
- In Vite, minified CSS build source maps are not supported at all. See
https://github.com/vitejs/vite/issues/2830 for more details.
- In PostCSS, minified CSS source maps are not supported. This is due to
the complexity required around re-associating every AST node with a
location in the generated, optimized CSS. This complexity would also
have a non-trivial performance impact.
## Testing
Here's how to test the source map functionality in different
environments:
### Testing the CLI
1. Setup typical project that the CLI can use and with sources to scan.
```css
@import "tailwindcss";
@utilty my-custom-utility {
color: red;
}
/* to test `@apply` */
.card {
@apply bg-white text-center shadow-md;
}
```
2. Build with source maps:
```bash
bun /path/to/tailwindcss/packages/@tailwindcss-cli/src/index.ts --input input.css -o output.css --map
```
3. Open Chrome DevTools, inspect an element with utility classes, and
you should see rules pointing to `input.css` or
`node_modules/tailwindcss/index.css`
### Testing with Vite
Testing in Vite will require building and installing necessary files
under `dist/*.tgz`.
1. Create a Vite project and enable source maps in `vite.config.js`:
```js
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [tailwindcss()],
css: {
// This line is required for them to work
devSourcemap: true,
},
})
```
2. Add a component that uses Tailwind classes and custom CSS:
```jsx
// ./src/app.jsx
export default function App() {
return (
<div className="bg-blue-500 my-custom-class">
Hello World
</div>
)
}
```
```css
/* ./src/styles.css */
@import "tailwindcss";
@utilty my-custom-utility {
color: red;
}
/* to test `@apply` */
.card {
@apply bg-white text-center shadow-md;
}
```
3. Run `npm run dev`, open DevTools, and inspect elements to verify
source mapping works for both utility classes and custom CSS.
### Testing with PostCSS CLI
1. Create a test file and update your PostCSS config:
```css
/* input.css */
@import "tailwindcss";
@layer components {
.card {
@apply p-6 rounded-lg shadow-lg;
}
}
```
```jsonc
// package.json
{
// …
"postcss": {
"map": {
"inline": true
},
"plugins": {
"/path/to/tailwindcss/packages/packages/@tailwindcss-postcss/src/index.ts": {}
}
}
}
```
2. Run PostCSS through Bun:
```bash
bunx --bun postcss ./src/index.css -o out.css
```
3. Inspect the output CSS - it should include an inline source map
comment at the bottom.
### Testing with PostCSS + Next.js
Testing in Next.js will require building and installing necessary files
under `dist/*.tgz`. However, I've not been able to get CSS source maps
to work in Next.js without this hack:
```js
const nextConfig: NextConfig = {
// next.js overwrites config.devtool so we prevent it from doing so
// please don't actually do this…
webpack: (config) =>
Object.defineProperty(config, "devtool", {
get: () => "inline-source-map",
set: () => {},
}),
};
```
This is definitely not supported and also doesn't work with turbopack.
This can be used to test them temporarily but I suspect that they just
don't work there.
### Manual source map analysis
You can analyze source maps using Evan Wallace's [Source Map
Visualization](https://evanw.github.io/source-map-visualization/) tool
which will help to verify the accuracy and quality of source maps. This
is what I used extensively while developing this implementation.
It'll help verify that custom, user CSS maps back to itself in the
input, that generated utilities all map back to `@tailwind utilities;`,
that source locations from imported files are also handled correctly,
etc… It also highlights the ranges of stuff so it's easy to see if there
are off-by-one errors.
It's easiest to use inline source maps with this tool because you can
take the CSS file and drop it on the page and it'll analyze it while
showing the file content.
If you're using Vite you'll want to access the CSS file with `?direct`
at the end so you don't get a JS module back.
## Implementation
The source map implementation follows the ECMA-426 specification and
includes several key components to aid in that goal:
### Source Location Tracking
Each emittable AST node in the compilation pipeline tracks two types of
source locations:
- `src`: Original source location - [source file, start offset, end
offset]
- `dst`: Generated source location - [output file, start offset, end
offset]
This dual tracking allows us to maintain mappings between the original
source and generated output for things like user CSS, generated
utilities, uses of `@apply`, and tracking theme variables.
It is important to note that source locations for nodes _never overlap_
within a file which helps simplify source map generation. As such each
type of node tracks a specific piece of itself rather than its entire
"block":
| Node | What a `SourceLocation` represents |
| ----------- |
---------------------------------------------------------------- |
| Style Rule | The selector |
| At Rule | Rule name and params, includes the `@` |
| Declaration | Property name and value, excludes the semicolon |
| Comment | The entire comment, includes the start `/*` and end `*/`
markers |
### Windows line endings when parsing CSS
Because our AST tracks nodes through offsets we must ensure that any
mutations to the file do *not* change the lenth of the string. We were
previously replacing `\r\n` with `\n` (see [filter code
points](https://drafts.csswg.org/css-syntax/#css-filter-code-points)
from the spec) — which changes the length of the string and all offsets
may end up incorrect. The CSS parser was updated to handle the CRLF
token directly by skipping over the `\r` and letting remaining code
handle `\n` as it did previously. Some additional tweaks were required
when "peeking" the input but those changes were fairly small.
### Tracking of imports
Source maps need paths to the actual imported stylesheets but the
resolve step for stylesheets happens inside the call to `loadStylesheet`
which make the file path unavailable to us. Because of this the
`loadStylesheet` API was augmented such that it has to return a `path`
property that we can then use to identify imported sources. I've also
made the same change to the `loadModule` API for consistency but nothing
currently uses this property.
The `path` property likely makes `base` redundant but elminating that
(if we even want to) is a future task.
### Optimizing the AST
Our optimization pass may intoduce some nodes, for example, fallbacks we
create for `@property`. These nodes are linked back to `@tailwind
utilities` as ultimately that is what is responsible for creating them.
### Line Offset Tables
A key component to our source map generation is the line offset table,
which was inspired by some ESBuild internals. It stores a sorted list of
offsets for the start of each line allowing us to translate offsets to
line/column `Position`s in `O(log N)` time and from `Position`s to
offsets in `O(1)` time. Creation of the table takes `O(N)` time.
This means that we can store code point offsets for source locations and
not have to worry about computing or tracking line/column numbers during
parsing and serialization. Only when a source map is generated do these
offsets need to be computed. This ensures the performance penalty when
not using source maps is minimal.
### Source Map Generation
The source map returned by `buildSourceMap()` is designed to follow the
[ECMA-426 spec](https://tc39.es/ecma426). Because that spec is not
completely finalized we consider the result of `buildSourceMap()` to be
internal API that may change as the spec chamges.
The produces source map is a "decoded" map such that all sources and
mappings are in an object graph. A library like `source-map-js` must be
used to convert this to an encoded source map of the right version where
mappings are encoded with base 64 VLQs.
Any specific integration (Vite, PostCSS, etc…) can then use
`toSourceMap()` from `@tailwindcss/node` to convert from the internal
source map to an spec-compliant encoded source map that can be
understood by other tools.
### Handling minification in Lightning
Since we use Lightning CSS for optimization, and it takes in an input
map, we generate an encoded source map that we then pass to lightning.
The output source map *from lighting itself* is then passed back in
during the second optimization pass. The final map is then passed from
lightning to the CLI (but not Vite or PostCSS — see the limitations
section for details).
In some cases we have to "fix up" the output CSS. When this happens we
use `magic-string` to do the replacement in a way that is trackable and
`@amppproject/remapping` to map that change back onto the original
source map. Once the need for these fix ups disappear these dependencies
can go away.
Notes:
- The accuracy of source maps run though lightning is reduced as it only
tracks on a per-rule level. This is sufficient enough for browser dev
tools so should be fine.
- Source maps during optimization do not function properly at this time
because of a bug in Lightning CSS regarding license comments. Once this
bug is fixed they will start working as expected.
### How source locations flow through the system
1. During initial CSS parsing, source locations are preserved.
2. During parsing these source locations are also mapped to the
destinations which supports an optimization for when no utilities are
generated.
3. Throughout the compilation process, transformations maintain source
location data
4. Generated utilities are explicitly pointed to `@tailwind utilities`
unless generated by `@apply`.
5. When optimization is enabled, source maps are remapped through
lightningcss
6. Final source maps are written in the requested format (inline or
separate file)
2025-05-08 16:29:49 -04:00
|
|
|
original: '@tailwind...',
|
|
|
|
|
generated: '.flex {...',
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
expect(map.at(3, 2)).toMatchObject({
|
2025-05-08 16:56:49 -04:00
|
|
|
source: expect.stringContaining('utilities.css'),
|
Add support for source maps (#17775)
Closes #13694
Closes #13591
# Source Maps Support for Tailwind CSS
This PR adds support for source maps to Tailwind CSS v4 allowing us to
track where styles come from whether that be user CSS, imported
stylesheets, or generated utilities. This will improve debuggability in
browser dev tools and gives us a good foundation for producing better
error messages. I'll go over the details on how end users can enable
source maps, any limitations in our implementation, changes to the
internal `compile(…)` API, and some details and reasoning around the
implementation we chose.
## Usage
### CLI
Source maps can be enabled in the CLI by using the command line argument
`--map` which will generate an inline source map comment at the bottom
of your CSS. A separate file may be generated by passing a file name to
`--map`:
```bash
# Generates an inline source map
npx tailwindcss -i input.css -o output.css --map
# Generates a separate source map file
npx tailwindcss -i input.css -o output.css --map output.css.map
```
### PostCSS
Source maps are supported when using Tailwind as a PostCSS plugin *in
development mode only*. They may or may not be enabled by default
depending on your build tool. If they are not you may be able to
configure them within your PostCSS config:
```jsonc
// package.json
{
// …
"postcss": {
"map": { "inline": true },
"plugins": {
"@tailwindcss/postcss": {},
},
}
}
```
### Vite
Source maps are supported when using the Tailwind CSS Vite plugin in
*development mode only* by enabling the `css.devSourcemap` setting:
```js
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [tailwindcss()],
css: {
devSourcemap: true,
},
})
```
Now when a CSS file is requested by the browser it'll have an inline
source map comment that the browser can use.
## Limitations
- Production build source maps are currently disabled due to a bug in
Lightning CSS. See
https://github.com/parcel-bundler/lightningcss/pull/971 for more
details.
- In Vite, minified CSS build source maps are not supported at all. See
https://github.com/vitejs/vite/issues/2830 for more details.
- In PostCSS, minified CSS source maps are not supported. This is due to
the complexity required around re-associating every AST node with a
location in the generated, optimized CSS. This complexity would also
have a non-trivial performance impact.
## Testing
Here's how to test the source map functionality in different
environments:
### Testing the CLI
1. Setup typical project that the CLI can use and with sources to scan.
```css
@import "tailwindcss";
@utilty my-custom-utility {
color: red;
}
/* to test `@apply` */
.card {
@apply bg-white text-center shadow-md;
}
```
2. Build with source maps:
```bash
bun /path/to/tailwindcss/packages/@tailwindcss-cli/src/index.ts --input input.css -o output.css --map
```
3. Open Chrome DevTools, inspect an element with utility classes, and
you should see rules pointing to `input.css` or
`node_modules/tailwindcss/index.css`
### Testing with Vite
Testing in Vite will require building and installing necessary files
under `dist/*.tgz`.
1. Create a Vite project and enable source maps in `vite.config.js`:
```js
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [tailwindcss()],
css: {
// This line is required for them to work
devSourcemap: true,
},
})
```
2. Add a component that uses Tailwind classes and custom CSS:
```jsx
// ./src/app.jsx
export default function App() {
return (
<div className="bg-blue-500 my-custom-class">
Hello World
</div>
)
}
```
```css
/* ./src/styles.css */
@import "tailwindcss";
@utilty my-custom-utility {
color: red;
}
/* to test `@apply` */
.card {
@apply bg-white text-center shadow-md;
}
```
3. Run `npm run dev`, open DevTools, and inspect elements to verify
source mapping works for both utility classes and custom CSS.
### Testing with PostCSS CLI
1. Create a test file and update your PostCSS config:
```css
/* input.css */
@import "tailwindcss";
@layer components {
.card {
@apply p-6 rounded-lg shadow-lg;
}
}
```
```jsonc
// package.json
{
// …
"postcss": {
"map": {
"inline": true
},
"plugins": {
"/path/to/tailwindcss/packages/packages/@tailwindcss-postcss/src/index.ts": {}
}
}
}
```
2. Run PostCSS through Bun:
```bash
bunx --bun postcss ./src/index.css -o out.css
```
3. Inspect the output CSS - it should include an inline source map
comment at the bottom.
### Testing with PostCSS + Next.js
Testing in Next.js will require building and installing necessary files
under `dist/*.tgz`. However, I've not been able to get CSS source maps
to work in Next.js without this hack:
```js
const nextConfig: NextConfig = {
// next.js overwrites config.devtool so we prevent it from doing so
// please don't actually do this…
webpack: (config) =>
Object.defineProperty(config, "devtool", {
get: () => "inline-source-map",
set: () => {},
}),
};
```
This is definitely not supported and also doesn't work with turbopack.
This can be used to test them temporarily but I suspect that they just
don't work there.
### Manual source map analysis
You can analyze source maps using Evan Wallace's [Source Map
Visualization](https://evanw.github.io/source-map-visualization/) tool
which will help to verify the accuracy and quality of source maps. This
is what I used extensively while developing this implementation.
It'll help verify that custom, user CSS maps back to itself in the
input, that generated utilities all map back to `@tailwind utilities;`,
that source locations from imported files are also handled correctly,
etc… It also highlights the ranges of stuff so it's easy to see if there
are off-by-one errors.
It's easiest to use inline source maps with this tool because you can
take the CSS file and drop it on the page and it'll analyze it while
showing the file content.
If you're using Vite you'll want to access the CSS file with `?direct`
at the end so you don't get a JS module back.
## Implementation
The source map implementation follows the ECMA-426 specification and
includes several key components to aid in that goal:
### Source Location Tracking
Each emittable AST node in the compilation pipeline tracks two types of
source locations:
- `src`: Original source location - [source file, start offset, end
offset]
- `dst`: Generated source location - [output file, start offset, end
offset]
This dual tracking allows us to maintain mappings between the original
source and generated output for things like user CSS, generated
utilities, uses of `@apply`, and tracking theme variables.
It is important to note that source locations for nodes _never overlap_
within a file which helps simplify source map generation. As such each
type of node tracks a specific piece of itself rather than its entire
"block":
| Node | What a `SourceLocation` represents |
| ----------- |
---------------------------------------------------------------- |
| Style Rule | The selector |
| At Rule | Rule name and params, includes the `@` |
| Declaration | Property name and value, excludes the semicolon |
| Comment | The entire comment, includes the start `/*` and end `*/`
markers |
### Windows line endings when parsing CSS
Because our AST tracks nodes through offsets we must ensure that any
mutations to the file do *not* change the lenth of the string. We were
previously replacing `\r\n` with `\n` (see [filter code
points](https://drafts.csswg.org/css-syntax/#css-filter-code-points)
from the spec) — which changes the length of the string and all offsets
may end up incorrect. The CSS parser was updated to handle the CRLF
token directly by skipping over the `\r` and letting remaining code
handle `\n` as it did previously. Some additional tweaks were required
when "peeking" the input but those changes were fairly small.
### Tracking of imports
Source maps need paths to the actual imported stylesheets but the
resolve step for stylesheets happens inside the call to `loadStylesheet`
which make the file path unavailable to us. Because of this the
`loadStylesheet` API was augmented such that it has to return a `path`
property that we can then use to identify imported sources. I've also
made the same change to the `loadModule` API for consistency but nothing
currently uses this property.
The `path` property likely makes `base` redundant but elminating that
(if we even want to) is a future task.
### Optimizing the AST
Our optimization pass may intoduce some nodes, for example, fallbacks we
create for `@property`. These nodes are linked back to `@tailwind
utilities` as ultimately that is what is responsible for creating them.
### Line Offset Tables
A key component to our source map generation is the line offset table,
which was inspired by some ESBuild internals. It stores a sorted list of
offsets for the start of each line allowing us to translate offsets to
line/column `Position`s in `O(log N)` time and from `Position`s to
offsets in `O(1)` time. Creation of the table takes `O(N)` time.
This means that we can store code point offsets for source locations and
not have to worry about computing or tracking line/column numbers during
parsing and serialization. Only when a source map is generated do these
offsets need to be computed. This ensures the performance penalty when
not using source maps is minimal.
### Source Map Generation
The source map returned by `buildSourceMap()` is designed to follow the
[ECMA-426 spec](https://tc39.es/ecma426). Because that spec is not
completely finalized we consider the result of `buildSourceMap()` to be
internal API that may change as the spec chamges.
The produces source map is a "decoded" map such that all sources and
mappings are in an object graph. A library like `source-map-js` must be
used to convert this to an encoded source map of the right version where
mappings are encoded with base 64 VLQs.
Any specific integration (Vite, PostCSS, etc…) can then use
`toSourceMap()` from `@tailwindcss/node` to convert from the internal
source map to an spec-compliant encoded source map that can be
understood by other tools.
### Handling minification in Lightning
Since we use Lightning CSS for optimization, and it takes in an input
map, we generate an encoded source map that we then pass to lightning.
The output source map *from lighting itself* is then passed back in
during the second optimization pass. The final map is then passed from
lightning to the CLI (but not Vite or PostCSS — see the limitations
section for details).
In some cases we have to "fix up" the output CSS. When this happens we
use `magic-string` to do the replacement in a way that is trackable and
`@amppproject/remapping` to map that change back onto the original
source map. Once the need for these fix ups disappear these dependencies
can go away.
Notes:
- The accuracy of source maps run though lightning is reduced as it only
tracks on a per-rule level. This is sufficient enough for browser dev
tools so should be fine.
- Source maps during optimization do not function properly at this time
because of a bug in Lightning CSS regarding license comments. Once this
bug is fixed they will start working as expected.
### How source locations flow through the system
1. During initial CSS parsing, source locations are preserved.
2. During parsing these source locations are also mapped to the
destinations which supports an optimization for when no utilities are
generated.
3. Throughout the compilation process, transformations maintain source
location data
4. Generated utilities are explicitly pointed to `@tailwind utilities`
unless generated by `@apply`.
5. When optimization is enabled, source maps are remapped through
lightningcss
6. Final source maps are written in the requested format (inline or
separate file)
2025-05-08 16:29:49 -04:00
|
|
|
original: '@tailwind...',
|
|
|
|
|
generated: 'display: f...',
|
|
|
|
|
})
|
|
|
|
|
|
|
|
|
|
expect(map.at(4, 0)).toMatchObject({
|
2025-05-08 16:56:49 -04:00
|
|
|
source: expect.stringContaining('utilities.css'),
|
Add support for source maps (#17775)
Closes #13694
Closes #13591
# Source Maps Support for Tailwind CSS
This PR adds support for source maps to Tailwind CSS v4 allowing us to
track where styles come from whether that be user CSS, imported
stylesheets, or generated utilities. This will improve debuggability in
browser dev tools and gives us a good foundation for producing better
error messages. I'll go over the details on how end users can enable
source maps, any limitations in our implementation, changes to the
internal `compile(…)` API, and some details and reasoning around the
implementation we chose.
## Usage
### CLI
Source maps can be enabled in the CLI by using the command line argument
`--map` which will generate an inline source map comment at the bottom
of your CSS. A separate file may be generated by passing a file name to
`--map`:
```bash
# Generates an inline source map
npx tailwindcss -i input.css -o output.css --map
# Generates a separate source map file
npx tailwindcss -i input.css -o output.css --map output.css.map
```
### PostCSS
Source maps are supported when using Tailwind as a PostCSS plugin *in
development mode only*. They may or may not be enabled by default
depending on your build tool. If they are not you may be able to
configure them within your PostCSS config:
```jsonc
// package.json
{
// …
"postcss": {
"map": { "inline": true },
"plugins": {
"@tailwindcss/postcss": {},
},
}
}
```
### Vite
Source maps are supported when using the Tailwind CSS Vite plugin in
*development mode only* by enabling the `css.devSourcemap` setting:
```js
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [tailwindcss()],
css: {
devSourcemap: true,
},
})
```
Now when a CSS file is requested by the browser it'll have an inline
source map comment that the browser can use.
## Limitations
- Production build source maps are currently disabled due to a bug in
Lightning CSS. See
https://github.com/parcel-bundler/lightningcss/pull/971 for more
details.
- In Vite, minified CSS build source maps are not supported at all. See
https://github.com/vitejs/vite/issues/2830 for more details.
- In PostCSS, minified CSS source maps are not supported. This is due to
the complexity required around re-associating every AST node with a
location in the generated, optimized CSS. This complexity would also
have a non-trivial performance impact.
## Testing
Here's how to test the source map functionality in different
environments:
### Testing the CLI
1. Setup typical project that the CLI can use and with sources to scan.
```css
@import "tailwindcss";
@utilty my-custom-utility {
color: red;
}
/* to test `@apply` */
.card {
@apply bg-white text-center shadow-md;
}
```
2. Build with source maps:
```bash
bun /path/to/tailwindcss/packages/@tailwindcss-cli/src/index.ts --input input.css -o output.css --map
```
3. Open Chrome DevTools, inspect an element with utility classes, and
you should see rules pointing to `input.css` or
`node_modules/tailwindcss/index.css`
### Testing with Vite
Testing in Vite will require building and installing necessary files
under `dist/*.tgz`.
1. Create a Vite project and enable source maps in `vite.config.js`:
```js
import tailwindcss from "@tailwindcss/vite";
import { defineConfig } from "vite";
export default defineConfig({
plugins: [tailwindcss()],
css: {
// This line is required for them to work
devSourcemap: true,
},
})
```
2. Add a component that uses Tailwind classes and custom CSS:
```jsx
// ./src/app.jsx
export default function App() {
return (
<div className="bg-blue-500 my-custom-class">
Hello World
</div>
)
}
```
```css
/* ./src/styles.css */
@import "tailwindcss";
@utilty my-custom-utility {
color: red;
}
/* to test `@apply` */
.card {
@apply bg-white text-center shadow-md;
}
```
3. Run `npm run dev`, open DevTools, and inspect elements to verify
source mapping works for both utility classes and custom CSS.
### Testing with PostCSS CLI
1. Create a test file and update your PostCSS config:
```css
/* input.css */
@import "tailwindcss";
@layer components {
.card {
@apply p-6 rounded-lg shadow-lg;
}
}
```
```jsonc
// package.json
{
// …
"postcss": {
"map": {
"inline": true
},
"plugins": {
"/path/to/tailwindcss/packages/packages/@tailwindcss-postcss/src/index.ts": {}
}
}
}
```
2. Run PostCSS through Bun:
```bash
bunx --bun postcss ./src/index.css -o out.css
```
3. Inspect the output CSS - it should include an inline source map
comment at the bottom.
### Testing with PostCSS + Next.js
Testing in Next.js will require building and installing necessary files
under `dist/*.tgz`. However, I've not been able to get CSS source maps
to work in Next.js without this hack:
```js
const nextConfig: NextConfig = {
// next.js overwrites config.devtool so we prevent it from doing so
// please don't actually do this…
webpack: (config) =>
Object.defineProperty(config, "devtool", {
get: () => "inline-source-map",
set: () => {},
}),
};
```
This is definitely not supported and also doesn't work with turbopack.
This can be used to test them temporarily but I suspect that they just
don't work there.
### Manual source map analysis
You can analyze source maps using Evan Wallace's [Source Map
Visualization](https://evanw.github.io/source-map-visualization/) tool
which will help to verify the accuracy and quality of source maps. This
is what I used extensively while developing this implementation.
It'll help verify that custom, user CSS maps back to itself in the
input, that generated utilities all map back to `@tailwind utilities;`,
that source locations from imported files are also handled correctly,
etc… It also highlights the ranges of stuff so it's easy to see if there
are off-by-one errors.
It's easiest to use inline source maps with this tool because you can
take the CSS file and drop it on the page and it'll analyze it while
showing the file content.
If you're using Vite you'll want to access the CSS file with `?direct`
at the end so you don't get a JS module back.
## Implementation
The source map implementation follows the ECMA-426 specification and
includes several key components to aid in that goal:
### Source Location Tracking
Each emittable AST node in the compilation pipeline tracks two types of
source locations:
- `src`: Original source location - [source file, start offset, end
offset]
- `dst`: Generated source location - [output file, start offset, end
offset]
This dual tracking allows us to maintain mappings between the original
source and generated output for things like user CSS, generated
utilities, uses of `@apply`, and tracking theme variables.
It is important to note that source locations for nodes _never overlap_
within a file which helps simplify source map generation. As such each
type of node tracks a specific piece of itself rather than its entire
"block":
| Node | What a `SourceLocation` represents |
| ----------- |
---------------------------------------------------------------- |
| Style Rule | The selector |
| At Rule | Rule name and params, includes the `@` |
| Declaration | Property name and value, excludes the semicolon |
| Comment | The entire comment, includes the start `/*` and end `*/`
markers |
### Windows line endings when parsing CSS
Because our AST tracks nodes through offsets we must ensure that any
mutations to the file do *not* change the lenth of the string. We were
previously replacing `\r\n` with `\n` (see [filter code
points](https://drafts.csswg.org/css-syntax/#css-filter-code-points)
from the spec) — which changes the length of the string and all offsets
may end up incorrect. The CSS parser was updated to handle the CRLF
token directly by skipping over the `\r` and letting remaining code
handle `\n` as it did previously. Some additional tweaks were required
when "peeking" the input but those changes were fairly small.
### Tracking of imports
Source maps need paths to the actual imported stylesheets but the
resolve step for stylesheets happens inside the call to `loadStylesheet`
which make the file path unavailable to us. Because of this the
`loadStylesheet` API was augmented such that it has to return a `path`
property that we can then use to identify imported sources. I've also
made the same change to the `loadModule` API for consistency but nothing
currently uses this property.
The `path` property likely makes `base` redundant but elminating that
(if we even want to) is a future task.
### Optimizing the AST
Our optimization pass may intoduce some nodes, for example, fallbacks we
create for `@property`. These nodes are linked back to `@tailwind
utilities` as ultimately that is what is responsible for creating them.
### Line Offset Tables
A key component to our source map generation is the line offset table,
which was inspired by some ESBuild internals. It stores a sorted list of
offsets for the start of each line allowing us to translate offsets to
line/column `Position`s in `O(log N)` time and from `Position`s to
offsets in `O(1)` time. Creation of the table takes `O(N)` time.
This means that we can store code point offsets for source locations and
not have to worry about computing or tracking line/column numbers during
parsing and serialization. Only when a source map is generated do these
offsets need to be computed. This ensures the performance penalty when
not using source maps is minimal.
### Source Map Generation
The source map returned by `buildSourceMap()` is designed to follow the
[ECMA-426 spec](https://tc39.es/ecma426). Because that spec is not
completely finalized we consider the result of `buildSourceMap()` to be
internal API that may change as the spec chamges.
The produces source map is a "decoded" map such that all sources and
mappings are in an object graph. A library like `source-map-js` must be
used to convert this to an encoded source map of the right version where
mappings are encoded with base 64 VLQs.
Any specific integration (Vite, PostCSS, etc…) can then use
`toSourceMap()` from `@tailwindcss/node` to convert from the internal
source map to an spec-compliant encoded source map that can be
understood by other tools.
### Handling minification in Lightning
Since we use Lightning CSS for optimization, and it takes in an input
map, we generate an encoded source map that we then pass to lightning.
The output source map *from lighting itself* is then passed back in
during the second optimization pass. The final map is then passed from
lightning to the CLI (but not Vite or PostCSS — see the limitations
section for details).
In some cases we have to "fix up" the output CSS. When this happens we
use `magic-string` to do the replacement in a way that is trackable and
`@amppproject/remapping` to map that change back onto the original
source map. Once the need for these fix ups disappear these dependencies
can go away.
Notes:
- The accuracy of source maps run though lightning is reduced as it only
tracks on a per-rule level. This is sufficient enough for browser dev
tools so should be fine.
- Source maps during optimization do not function properly at this time
because of a bug in Lightning CSS regarding license comments. Once this
bug is fixed they will start working as expected.
### How source locations flow through the system
1. During initial CSS parsing, source locations are preserved.
2. During parsing these source locations are also mapped to the
destinations which supports an optimization for when no utilities are
generated.
3. Throughout the compilation process, transformations maintain source
location data
4. Generated utilities are explicitly pointed to `@tailwind utilities`
unless generated by `@apply`.
5. When optimization is enabled, source maps are remapped through
lightningcss
6. Final source maps are written in the requested format (inline or
separate file)
2025-05-08 16:29:49 -04:00
|
|
|
original: ';...',
|
|
|
|
|
generated: '}...',
|
|
|
|
|
})
|
|
|
|
|
},
|
|
|
|
|
)
|