This PR adds CSS codemods for migrating existing `@tailwind` directives
to the new alternatives.
This PR has the ability to migrate the following cases:
---
Typical default usage of `@tailwind` directives in v3.
Input:
```css
@tailwind base;
@tailwind components;
@tailwind utilities;
```
Output:
```css
@import 'tailwindcss';
```
---
Similar as above, but always using `@import` instead of `@import`
directly.
Input:
```css
@import 'tailwindcss/base';
@import 'tailwindcss/components';
@import 'tailwindcss/utilities';
```
Output:
```css
@import 'tailwindcss';
```
---
When you are _only_ using `@tailwind base`:
Input:
```css
@tailwind base;
```
Output:
```css
@import 'tailwindcss/theme' layer(theme);
@import 'tailwindcss/preflight' layer(base);
```
---
When you are _only_ using `@tailwind utilities`:
Input:
```css
@tailwind utilities;
```
Output:
```css
@import 'tailwindcss/utilities' layer(utilities);
```
---
If the default order changes (aka, `@tailwind utilities` was defined
_before_ `@tailwind base`), then an additional `@layer` will be added to
the top to re-define the default order.
Input:
```css
@tailwind utilities;
@tailwind base;
```
Output:
```css
@layer theme, components, utilities, base;
@import 'tailwindcss';
```
---
When you are _only_ using `@tailwind base; @tailwind utilities;`:
Input:
```css
@tailwind base;
@tailwind utilities;
```
Output:
```css
@import 'tailwindcss';
```
We currently don't have a concept of `@tailwind components` in v4, so if
you are not using `@tailwind components`, we can expand to the default
`@import 'tailwindcss';` instead of the individual imports.
---
`@tailwind screens` and `@tailwind variants` are not supported/necessary
in v4, so we can safely remove them.
Input:
```css
@tailwind screens;
@tailwind variants;
```
Output:
```css
```
This PR adds some initial tooling for codemods. We are currently only
interested in migrating CSS files, so we will be using PostCSS under the
hood to do this. This PR also implements the "migrate `@apply`" codemod
from #14412.
The usage will look like this:
```sh
npx @tailwindcss/upgrade
```
You can pass in CSS files to transform as arguments:
```sh
npx @tailwindcss/upgrade src/**/*.css
```
But, if none are provided, it will search for CSS files in the current
directory and its subdirectories.
```
≈ tailwindcss v4.0.0-alpha.24
│ No files provided. Searching for CSS files in the current
│ directory and its subdirectories…
│ Migration complete. Verify the changes and commit them to
│ your repository.
```
The tooling also requires the Git repository to be in a clean state.
This is a common convention to ensure that everything is undo-able. If
we detect that the git repository is dirty, we will abort the migration.
```
≈ tailwindcss v4.0.0-alpha.24
│ Git directory is not clean. Please stash or commit your
│ changes before migrating.
│ You may use the `--force` flag to override this safety
│ check.
```
---
This PR alsoo adds CSS codemods for migrating existing `@apply`
directives to the new version.
This PR has the ability to migrate the following cases:
---
In v4, the convention is to put the important modifier `!` at the end of
the utility class instead of right before it. This makes it easier to
reason about, especially when you are variants.
Input:
```css
.foo {
@apply !flex flex-col! hover:!items-start items-center;
}
```
Output:
```css
.foo {
@apply flex! flex-col! hover:items-start! items-center;
}
```
---
In v4 we don't support `!important` as a marker at the end of `@apply`
directives. Instead, you can append the `!` to each utility class to
make it `!important`.
Input:
```css
.foo {
@apply flex flex-col !important;
}
```
Output:
```css
.foo {
@apply flex! flex-col!;
}
```
Tailwind V3 used [jiti](https://github.com/unjs/jiti/) to allow
importing of TypeScript files for the config and plugins. This PR adds
the new Jiti V2 beta to our `@tailwindcss/node` and uses it if a native
`import()` fails. I added a new integration test to the CLI config
setup, to ensure it still works with our module cache cleanup.
When you configure custom content globs inside an `@config` file, we
want to tread these globs as being relative to that config file and not
the CSS file that requires the content file. A config can be used by
multiple CSS configs.
---------
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
Builds on #14239 — that PR needs to be merged first.
This PR allows plugins defined with `plugin.withOptions` to receive
options in CSS when using `@plugin` as long as the options are simple
key/value pairs.
For example, the following is now valid and will include the forms
plugin with only the base styles enabled:
```css
@plugin "@tailwindcss/forms" {
strategy: base;
}
```
We handle `null`, `true`, `false`, and numeric values as expected and
will convert them to their JavaScript equivalents. Comma separated
values are turned into arrays. All other values are converted to
strings.
For example, in the following plugin definition, the options that are
passed to the plugin will be the correct types:
- `debug` will be the boolean value `true`
- `threshold` will be the number `0.5`
- `message` will be the string `"Hello world"`
- `features` will be the array `["base", "responsive"]`
```css
@plugin "my-plugin" {
debug: false;
threshold: 0.5;
message: Hello world;
features: base, responsive;
}
```
If you need to pass a number or boolean value as a string, you can do so
by wrapping the value in quotes:
```css
@plugin "my-plugin" {
debug: "false";
threshold: "0.5";
message: "Hello world";
}
```
When duplicate options are encountered the last value wins:
```css
@plugin "my-plugin" {
message: Hello world;
message: Hello plugin; /* this will be the value of `message` */
}
```
It's important to note that this feature is **only available for plugins
defined with `plugin.withOptions`**. If you try to pass options to a
plugin that doesn't support them, you'll get an error message when
building:
```css
@plugin "my-plugin" {
debug: false;
threshold: 0.5;
}
/* Error: The plugin "my-plugin" does not accept options */
```
Additionally, if you try to pass in more complex values like objects or
selectors you'll get an error message:
```css
@plugin "my-plugin" {
color: { red: 100; green: 200; blue: 300 };
}
/* Error: Objects are not supported in `@plugin` options. */
```
```css
@plugin "my-plugin" {
.some-selector > * {
primary: "blue";
secondary: "green";
}
}
/* Error: `@plugin` can only contain declarations. */
```
---------
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
In Tailwind v4 the CSS file is the main entry point to your project and
is generally configured via `@theme`. However, given that all v3
projects were configured via a `tailwind.config.js` file we definitely
need to support those. This PR adds support for loading existing
Tailwind config files by adding an `@config` directive to the CSS —
similar to how v3 supported multiple config files except that this is
now _required_ to use a config file.
You can load a config file like so:
```
@import "tailwindcss";
@config "./path/to/tailwind.config.js";
```
A few notes:
- Both CommonJS and ESM config files are supported (loaded directly via
`import()` in Node)
- This is not yet supported in Intellisense or Prettier — should
hopefully land next week
- TypeScript is **not yet** supported in the config file — this will be
handled in a future PR.
---------
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
This PR adds a new standalone client: A single-binary file that you can
use to run Tailwind v4 without having a node setup. To make this work we
use Bun's single-binary build which can properly package up native
modules and the bun runtime for us so we do not have to rely on any
expand-into-tmp-folder-at-runtime workarounds.
When running locally, `pnpm build` will now standalone artifacts inside
`packages/@tailwindcss-standalone/dist`. Note that since we do not build
Oxide for other environments in the local setup, you won't be able to
use the standalone artifacts for other platforms in local dev mode.
Unfortunately Bun does not have support for Windows ARM builds yet but
we found that using the `bun-baseline` runtime for Windows x64 would
make the builds work fine in ARM emulation mode:
Some Bun related issues we faced and worked around:
- We found that the regular Windows x64 build of `bun` does not run on
Windows ARM via emulation. Instead, we have to use the `bun-baseline`
builds which emulate correctly.
- When we tried to bundle artifacts with [embed
directories](https://bun.sh/docs/bundler/executables#embed-directories),
node binary dependencies were no longer resolved correctly even though
they would still be bundled and accessible within the [`embeddedFiles`
list](https://bun.sh/docs/bundler/executables#listing-embedded-files).
We worked around this by using the `import * as from ... with { type:
"file" };` and patching the resolver we use in our CLI.
- If you have an import to a module that is used as a regular import
_and_ a `with { type: "file" }`, it will either return the module in
both cases _or_ the file path when we would expect only the `with {
type: "file" }` import to return the path. We do read the Tailwind CSS
version via the file system and `require.resolve()` in the CLI and via
`import * from './package.json'` in core and had to work around this by
patching the version resolution in our CLI.
```ts
import packageJson from "./package.json"
import packageJsonPath from "./package.json" with {type: "file"}
// We do not expect these to be equal
packageJson === packageJsonPath
```
- We can not customize the app icon used for Windows `.exe` builds
without decompiling the binary. For now we will leave the default but
one workaround is to [use tools like
ResourceHacker](698d9c4bd1)
to decompile the binary first.
---------
Co-authored-by: Jordan Pittman <jordan@cryptica.me>
Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
Currently if a plugin adds a utility called `duration` it will take
precedence over the built-in utilities — or any utilities with the same
name in previously included plugins. However, in v3, we emitted matches
from _all_ plugins where possible.
Take this plugin for example which adds utilities for
`animation-duration` via the `duration-*` class:
```ts
import plugin from 'tailwindcss/plugin'
export default plugin(
function ({ matchUtilities, theme }) {
matchUtilities(
{ duration: (value) => ({ animationDuration: value }) },
{ values: theme("animationDuration") },
)
},
{
theme: {
extend: {
animationDuration: ({ theme }) => ({
...theme("transitionDuration"),
}),
}
},
}
)
```
Before this PR this plugin's `duration` utility would override the
built-in `duration` utility so you'd get this for a class like
`duration-3500`:
```css
.duration-3000 {
animation-duration: 3500ms;
}
```
Now, after this PR, we'll emit rules for `transition-duration`
(Tailwind's built-in `duration-*` utility) and `animation-duration`
(from the above plugin) and you'll get this instead:
```css
.duration-3000 {
transition-duration: 3500ms;
}
.duration-3000 {
animation-duration: 3500ms;
}
```
These are output as separate rules to ensure that they can all be sorted
appropriately against other utilities.
---------
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
This PR enables compatibility for the `@tailwindcss/typography` and
`@tailwindcss/forms` plugins. This required the addition of new Plugin
APIs and new package exports.
## New Plugin APIs and compatibility improvements
We added support for `addComponents`, `matchComponents`, and `prefix`.
The component APIs are an alias for the utilities APIs because the
sorting in V4 is different and emitting components in a custom `@layer`
is not necessary. Since `prefix` is not supported in V4, the `prefix()`
API is currently an identity function.
```js
addComponents({
'.btn': {
padding: '.5rem 1rem',
borderRadius: '.25rem',
fontWeight: '600',
},
'.btn-blue': {
backgroundColor: '#3490dc',
color: '#fff',
'&:hover': {
backgroundColor: '#2779bd',
},
},
'.btn-red': {
backgroundColor: '#e3342f',
color: '#fff',
'&:hover': {
backgroundColor: '#cc1f1a',
},
},
})
```
The behavioral changes effect the `addUtilities` and `matchUtilities`
functions, we now:
- Allow arrays of CSS property objects to be emitted:
```js
addUtilities({
'.text-trim': [
{'text-box-trim': 'both'},
{'text-box-edge': 'cap alphabetic'},
],
})
```
- Allow arrays of utilities
```js
addUtilities([
{
'.text-trim':{
'text-box-trim': 'both',
'text-box-edge': 'cap alphabetic',
},
}
])
```
- Allow more complicated selector names
```js
addUtilities({
'.form-input, .form-select, .form-radio': {
/* styles here */
},
'.form-input::placeholder': {
/* styles here */
},
'.form-checkbox:indeterminate:checked': {
/* styles here */
}
})
```
## New `tailwindcss/color` and `tailwindcss/defaultTheme` export
To be compatible to v3, we're adding two new exports to the tailwindcss
package. These match the default theme values as defined in v3:
```ts
import colors from 'tailwindcss/colors'
console.log(colors.red[600])
```
```ts
import theme from 'tailwindcss/defaultTheme'
console.log(theme.spacing[4])
```
---------
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
This PR is an umbrella PR where we will add support for the new
`@source` directive. This will allow you to add explicit content glob
patterns if you want to look for Tailwind classes in other files that
are not automatically detected yet.
Right now this is an addition to the existing auto content detection
that is automatically enabled in the `@tailwindcss/postcss` and
`@tailwindcss/cli` packages. The `@tailwindcss/vite` package doesn't use
the auto content detection, but uses the module graph instead.
From an API perspective there is not a lot going on. There are only a
few things that you have to know when using the `@source` directive, and
you probably already know the rules:
1. You can use multiple `@source` directives if you want.
2. The `@source` accepts a glob pattern so that you can match multiple
files at once
3. The pattern is relative to the current file you are in
4. The pattern includes all files it is matching, even git ignored files
1. The motivation for this is so that you can explicitly point to a
`node_modules` folder if you want to look at `node_modules` for whatever
reason.
6. Right now we don't support negative globs (starting with a `!`) yet,
that will be available in the near future.
Usage example:
```css
/* ./src/input.css */
@import "tailwindcss";
@source "../laravel/resources/views/**/*.blade.php";
@source "../../packages/monorepo-package/**/*.js";
```
It looks like the PR introduced a lot of changes, but this is a side
effect of all the other plumbing work we had to do to make this work.
For example:
1. We added dedicated integration tests that run on Linux and Windows in
CI (just to make sure that all the `path` logic is correct)
2. We Have to make sure that the glob patterns are always correct even
if you are using `@import` in your CSS and use `@source` in an imported
file. This is because we receive the flattened CSS contents where all
`@import`s are inlined.
3. We have to make sure that we also listen for changes in the files
that match any of these patterns and trigger a rebuild.
PRs:
- [x] https://github.com/tailwindlabs/tailwindcss/pull/14063
- [x] https://github.com/tailwindlabs/tailwindcss/pull/14085
- [x] https://github.com/tailwindlabs/tailwindcss/pull/14079
- [x] https://github.com/tailwindlabs/tailwindcss/pull/14067
- [x] https://github.com/tailwindlabs/tailwindcss/pull/14076
- [x] https://github.com/tailwindlabs/tailwindcss/pull/14080
- [x] https://github.com/tailwindlabs/tailwindcss/pull/14127
- [x] https://github.com/tailwindlabs/tailwindcss/pull/14135
Once all the PRs are merged, then this umbrella PR can be merged.
> [!IMPORTANT]
> Make sure to merge this without rebasing such that each individual PR
ends up on the main branch.
---------
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
Co-authored-by: Jordan Pittman <jordan@cryptica.me>
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
