This PR improves the upgrade tool to make sure that newly upgraded
`--spacing(2)` CSS functions is pretty printed to prevent unambiguous
looking classes (even though it compiles correctly).
If you have a class such as `m-[calc(100dvh-theme(spacing.2))]`, then we
used to convert it to `m-[calc(100dvh-calc(var(--spacing)*2))]`. But
recently we introduced the `--spacing(2)` CSS function which means that
the output now looks like this instead: `m-[calc(100dvh---spacing(2))]`.
The triple `-` is valid because the first `-` is the minus sign, the
next two `-` characters are from the function.
One solution is to introduce spaces via underscores:
```
m-[calc(100dvh_-_--spacing(2))]
```
But a simpler solution, is to wrap the `--spacing(2)` in parens to
remove the underscores and improve the readability of the `---`
characters.
```
m-[calc(100dvh-(--spacing(2)))]
```
This PR improves the codemod tool to simplify 2 things:
1. Whenever you have a `theme(…)` call, we try to change it to a
`var(…)`, but if that doesn't work for some reason, we will make sure to
at least convert it to the more modern `--theme(…)`.
2. When converting `theme(spacing.2)`, we used to convert it to
`calc(var(--spacing)*2)`, but now we will convert it to `--spacing(2)`
instead.
This PR prevents the migration of utilities detected in function names,
e.g.: the use of `shadow` inside `filter: 'drop-shadow(…)'`.
## Test plan
Have content like this in a project you're migrating using the upgrade
tool:
```js
{
filter: 'drop-shadow(0 0 0.5rem #000)'
}
```
This was verified by adding unit tests to the specific codemods and
adding an integration test.
`overflow-clip` was the name for `text-clip` in v4. However, that was
changed in v3 already so in v3 `overflow-clip` is already doing the same
as in v4. Hence a codemod is not necessary.
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
This PR improves the performance of the `@tailwindcss/postcss` and
`@tailwindcss/vite` implementations.
The issue is that in some scenarios, if you have multiple `.css` files,
then all of the CSS files are ran through the Tailwind CSS compiler. The
issue with this is that in a lot of cases, the CSS files aren't even
related to Tailwind CSS at all.
E.g.: in a Next.js project, if you use the `next/font/local` tool, then
every font you used will be in a separate CSS file. This means that we
run Tailwind CSS in all these files as well.
That said, running Tailwind CSS on these files isn't the end of the
world because we still need to handle `@import` in case `@tailwind
utilities` is being used. However, we also run the auto source detection
logic for every CSS file in the system. This part is bad.
To solve this, this PR introduces an internal `features` to collect what
CSS features are used throughout the system (`@import`, `@plugin`,
`@apply`, `@tailwind utilities`, etc…)
The `@tailwindcss/postcss` and `@tailwindcss/vite` plugin can use that
information to decide if they can take some shortcuts or not.
---
Overall, this means that we don't run the slow parts of Tailwind CSS if
we don't need to.
---------
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
Resolves#15193
This PR fixes an issue where `group` and `peer` would not have their
prefixes migrated as part of the upgrade script. We do this by
registering `group` and `peer` as utilities during the codemods. This
way, `parseCandidate` will find these classes to be valid Tailwind
candidates and the prefix can be migrated just like any other utility.
## Test Plan
Tried it with the v3 upgrade playground in the repo and it worked fine:
<img width="1257" alt="Screenshot 2024-11-27 at 12 17 25"
src="https://github.com/user-attachments/assets/1ee101e1-1d6a-4ce0-b0d4-8d51e5f6b0d2">
I've also added tests to our prefix upgrade integration test and the
prefix migration unit tests.
This PR ensures that when we inject `layer(…)` into an `@import` that it
always gets inserted as the first param. The `layer(…)` has to come
first by spec.
Input:
```css
@import "./foo" supports(--foo);
```
Before:
```css
@import "./foo" supports(--foo) layer(utilities);
```
After:
```css
@import "./foo" layer(utilities) supports(--foo);
```
Closes#15071
This PR reverts the changes in #15036 which add consistent base styles
for buttons and form controls to Preflight.
While this felt like a good idea (for the reasons explained in that PR),
practically this is just too disruptive of a change for people upgrading
from v3 to v4.
While updating some of our projects to v4 we found ourselves adding
classes to undo styles more often than we expected, and it also felt
inconsistent to have to use a different set of classes to style a link
or a button when we wanted them to look the same.
We also decided it feels a little strange that you could change the
border color of an element without ever specifying that it should have a
border, for example this just feels a little wrong:
```html
<button class="border-blue-500">
```
We also needed to set a default `color-scheme` value for any of this
stuff to work which breaks the ability to use the `color-scheme` meta
tag.
Since this change was a fairly major breaking change and we aren't
feeling much benefit from it, it doesn't feel worth making this change
for v4.
---------
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
This PR improves compatibility for named `opacity` theme values. One of
the changes in v4 is that we use the CSS `color-mix()` function to apply
opacity to colors. This, however, is limited to percentage values only:
```css
color: color-mix(in oklch, var(--color-red-500) 50%, transparent);
/* ^^^ */
/* This needs to be a percentage value */
```
In v3, however, it was common to specify custom opacity values as
decimal numbers. That's also what we did in our default config:
6069a81187/stubs/config.full.js (L703-L725)
This PR improves interop with these values by:
1. Converting decimal numbers in the range of `[0, 1]` to their
percentage value equivalent when using the interop layer.
2. Adjusts the codemod that migrates `opacity` theme keys to Tailwind v4
theme variables to include the same conversion.
3. Furthermore, due to the added support of named opacity modifers, we
can also drop theme keys that would now be the default. For example the
following config would not be necessary in v4 as the opacity modifier
would accept the value `50` by default:
```js
module.exports = {
theme: {
opacity: {
50: 0.5
}
}
}
```
## Test Plan
Added a new integration test for the codemod and a unit test for the
interop layer. I also re-ran the codemod on the Commit template and it's
now working as expected (left is v3, right is v4):
<img width="2560" alt="Screenshot 2024-11-21 at 17 25 32"
src="https://github.com/user-attachments/assets/f0c87243-ca80-4c39-ae5e-c1ab48fbe614">
While testing the latest alpha release across Tailwind v3 projects, we
noticed one regression in relation to the default color of `<button>`
elements. In v3, the reset would change the default to `inherit` but in
v4 we would _not include it in the reset snippet inserted by the upgrade
too_.
This PR changes the upgrade snippet to include it:
```diff
/*
In Tailwind CSS v4, basic styles are applied to form elements by default. To
maintain compatibility with v3, the following resets have been added:
*/
@layer base {
input,
textarea,
select,
button {
border: 0px solid;
border-radius: 0;
padding: 0;
+ color: inherit;
background-color: transparent;
}
}
```
This PR also ensures that there's a newline between the two code
snippets.
## Test Plan
### Before
### After
<img width="1354" alt="Screenshot 2024-11-21 at 15 42 58"
src="https://github.com/user-attachments/assets/9a4503fe-683f-4d08-abf2-7dd111ed5428">
This PR makes the candidate parser more strict by not allowing empty
arbitrary values.
Examples that are not allowed anymore:
- `bg-[]` — arbitrary value
- `bg-()` — arbitrary value, var shorthand
- `bg-[length:]` — arbitrary value, with typehint
- `bg-(length:)` — arbitrary value, with typehint, var shorthand
- `bg-red-500/[]` — arbitrary modifier
- `bg-red-500/()` — arbitrary modifier, var shorthand
- `data-[]:flex` — arbitrary value for variant
- `data-():flex` — arbitrary value for variant, var shorthand
- `group-visible/[]:flex` — arbitrary modifier for variant
- `group-visible/():flex` — arbitrary modifier for variant, var
shorthand
If you are trying to trick the parser by injecting some spaces like
this:
- `bg-[_]`
Then that is also not allowed.
This PR introduces consistent base styles for buttons and form controls
in Tailwind CSS v4.
## Motivation
In v3, form elements lack default styles, which can be
confusing—especially when certain elements, like a text input without a
placeholder or value, are rendered completely invisible on the page.
The goal of this change is to provide reasonable default styles for
buttons, inputs, selects, and textareas that are (mostly) consistent
across all browsers while remaining easy to customize with your own
styles.
This improvement should make Tailwind more accessible for developers new
to the framework and more convenient in scenarios where you need to
quickly create demos (e.g., using Tailwind Play).
## Light and dark mode support
These styles support both light and dark mode, achieved using the
`light-dark()` CSS function. While browser support for this function is
still somewhat limited, Lightning CSS transpiles it to a CSS
variable-based approach that works in older browsers.
For this approach to function correctly, a default `color-scheme` must
be set in your CSS (as explained in [the Lightning CSS
documentation](https://lightningcss.dev/transpilation.html#light-dark()-color-function)).
This PR addresses this requirement by setting the `color-scheme` to
`light` on the `html` element in Preflight.
<img width="1712" alt="image"
src="https://github.com/user-attachments/assets/dba56368-1427-47b3-9419-7c2f6313a944">
<img width="1709" alt="image"
src="https://github.com/user-attachments/assets/3d84fcd2-9606-4626-8e03-164a1dce9018">
## Breaking changes
While we don’t expect these changes to significantly impact v3 users
upgrading to v4, there may be minor differences for those relying on the
simpler v3 styles.
For example, Preflight now applies a `border-radius` to buttons and form
controls. If you weren’t explicitly setting the border radius to `0` in
your project, you’ll need to do so to restore the previous look.
Thankfully, reverting to the v3 styles is straightforward—just add the
following reset to your CSS:
```css
@layer base {
input,
textarea,
select,
button {
border: 0px solid;
border-radius: 0;
padding: 0;
background-color: transparent;
}
}
```
It’s worth noting that this reset doesn't touch the
`::file-selector-button` styles that were added in this PR. This is
because it's not possible to reliably "undo" these styles and restore
the original user-agent styles (which is what was used in v3), as these
are different in each browser. However, these new styles actually match
the defaults in most browsers pretty closely, so hopefully this just
won't be an issue.
## Codemod
This PR includes a codemod that automatically inserts the above
mentioned v3 reset to help avoid breaking changes during the upgrade.
The codemod will insert the following CSS:
```css
/*
In Tailwind CSS v4, basic styles are applied to form elements by default. To
maintain compatibility with v3, the following resets have been added:
*/
@layer base {
input,
textarea,
select,
button {
border: 0px solid;
border-radius: 0;
padding: 0;
background-color: transparent;
}
}
```
## Testing
These changes have been tested across a wide range of browsers,
including Chrome, Safari, Firefox, Edge, and Opera on macOS and Windows,
as well as Safari, Chrome, Firefox, and several lesser-known browsers on
iOS and Android.
However, some quirks still exist in certain mobile browsers, such as iOS
Safari, which adds too much bottom padding below date and time inputs:
<img width="1548" alt="Screenshot 2024-11-20 at 3 57 20 PM"
src="https://github.com/user-attachments/assets/507c7724-ac41-4634-a2b3-61ac4917ebce">
The only reliable way to address these issues is by applying
`appearance: none` to these form controls. However, this felt too
opinionated for Preflight, so we’ve opted to leave such adjustments to
user-land implementations.
---------
Co-authored-by: Jonathan Reinink <jonathan@reinink.ca>
Co-authored-by: Jordan Pittman <jordan@cryptica.me>
While testing the codemods on some projects, I noticed some issues with
the migration to the new `in-*` variant.
One such example is that we checked for `&` at the end, instead of ` &`
(the whitespace is significant).
This meant that `[figure>&]:my-0` was converted to `in-[figure>]:my-0`
which is wrong. In this case, we want to keep it as `[figure>&]:my-0`.
Additionally this PR brings back the migration from `group-[]:flex` to
`in-[.group]:flex`. If you are using a prefix, then `group-[]:tw-flex`
is migrated to `tw:in-[.tw\:group]:flex`.
Last but not least, this does some internal refactors to group
migrations logically together.
This PR fixes an issue where the Tailwind root file detection was wrong.
Whenever a CSS file contains any of the `@tailwind` directives or an
`@import` to any of the Tailwind files, the file is considered a
Tailwind root file.
If multiple CSS files are part of the same tree, then we make the
nearest common parent the root file.
This root file will be the file where we add `@config` and/or inject
other changes during the migration process.
However, if your folder structure looked like this:
```css
/* index.css */
@import "./base.css";
@import "./typography.css";
@import "tailwindcss/components"; /* This makes index.css a root file */
@import "./utilities.css";
/* base.css */
@tailwind base; /* This makes base.css a root file */
/* utilities.css */
@tailwind utilities; /* This makes utilities.css a root file */
```
Then we computed that `index.css` nad `base.css` were considered root
files even though they belong to the same tree (because `base.css` is
imported by `index.css`).
This PR fixes that behaviour by essentially being less smart, and just
checking again if any sheets are part of the same tree.
# Test plan:
Added an integration test that covers this scenario and fails before the
fix.
Also ran it on our tailwindcss.com codebase.
| Before | After |
| --- | --- |
| <img width="1072" alt="image"
src="https://github.com/user-attachments/assets/8ee99a59-335e-4221-b368-a8cd81e85191">
| <img width="1072" alt="image"
src="https://github.com/user-attachments/assets/fe5acae4-d3fc-43a4-bd31-eee768a3a6a5">
|
(Yes, I know the migration still fails, but that's a different issue.)
If you have a PostCSS config file, that is not simple (has functions,
requires, ...). In that case we don't migrate the PostCSS file. Because
we don't migrate, the `didMigrate` is still false and we continue with
the next migration.
The issue here is that there are 2 states encoded in the same variable
and they should be two separate variables because there is a difference
between:
1. Not finding a file at all
2. Finding a file, but not migrating it
Before this change, the output looks like this if you have a complex
PostCSS file:
```
│ Migrating PostCSS configuration…
│ The PostCSS config contains dynamic JavaScript and can not be automatically migrated.
│ No PostCSS config found, skipping migration.
```
After this change, the output looks like this:
```
│ Migrating PostCSS configuration…
│ ↳ The PostCSS config contains dynamic JavaScript and can not be automatically migrated.
```
Also updated the output to include `↳ ` to be consistent with the other
logs.
This PR uses the `enhanced-resolve` instead of
`createRequire(…).resolve` which improves the usability when running the
upgrade tool locally using Bun.
While testing, we also noticed that it is not possible to use a
`cjs`-only plugin inside of an `esm` project. It was also not possible
to use an `esm`-only plugin inside of a `cjs` project.
# Test plan
We added integration tests in both the CLI (the CLI is an mjs project)
and in the PostCSS (where we can configure a `cjs` and `esm` PostCSS
config) integration tests where we created an `esm` and `cjs` based
project with 4 plugins (`cjs`-only, `esm`-only, and TypeScript based
plugins: `cts`-only and `mts`-only).
This implements backwards compatibility for colors that use the old
`<alpha-value>` feature from v3. We can do this by replacing
`<alpha-value>` with `1` because we use `color-mix` to actually apply
opacity modifiers in v4.
In some local testing we ran the `@tailwindcss/upgrade` command twice in
a row. It would be great to get some feedback that this is not working,
so this PR now checks if it can resolve the installed version of
`tailwindcss` and if it can, it requires it to be < 4 (you can bypass
this check with `--force`).
---------
Co-authored-by: Robin Malfait <malfait.robin@gmail.com>
This PR improves the discoverability of Tailwind config files when we
are trying to link them to your CSS files.
When you have multiple "root" CSS files in your project, and if they
don't include an `@config` directive, then we tried to find the Tailwind
config file in your current working directory.
This means that if you run the upgrade command from the root of your
project, and you have a nested folder with a separate Tailwind setup,
then the nested CSS file would link to the root Tailwind config file.
Visually, you can think of it like this:
```
.
├── admin
│ ├── src
│ │ └── styles
│ │ └── index.css <-- This will be linked to (1)
│ └── tailwind.config.js (2)
├── src
│ └── styles
│ └── index.css <-- This will be linked to (1)
└── tailwind.config.js (1)
```
If you run the upgrade command from the root of your project, then the
`/src/styles/index.css` will be linked to `/tailwind.config.js` which is
what we expect.
But `/admin/src/styles/index.css` will _also_ be linked to
`/tailwind.config.js`
With this PR we improve this behavior by looking at the CSS file, and
crawling up the parent tree. This mens that the new behavior looks like
this:
```
.
├── admin
│ ├── src
│ │ └── styles
│ │ └── index.css <-- This will be linked to (2)
│ └── tailwind.config.js (2)
├── src
│ └── styles
│ └── index.css <-- This will be linked to (1)
└── tailwind.config.js (1)
```
Now `/src/styles/index.css` will be linked to `/tailwind.config.js`, and
`/admin/src/styles/index.css` will be linked to
`/admin/tailwind.config.js`.
When we discover the Tailwind config file, we will also print a message
to the user to let them know which CSS file is linked to which Tailwind
config file.
This should be a safe improvement because if your Tailwind config file
had a different name, or if it lived in a sibling folder then Tailwind
wouldn't find it either and you already required a `@config "…";`
directive in your CSS file to point to the correct file.
In the unlikely event that it turns out that 2 (or more) CSS files
resolve to the same to the same Tailwind config file, then an upgrade
might not be safe and some manual intervention might be needed. In this
case, we will show a warning about this.
<img width="1552" alt="image"
src="https://github.com/user-attachments/assets/7a1ad11d-18c5-4b7d-9a02-14f0116ae955">
Test plan:
---
- Added an integration test that properly links the nearest Tailwind
config file by looking up the tree
- Added an integration test that resolves 2 or more CSS files to the
same config file, resulting in an error where manual intervention is
needed
- Ran it on the Tailwind UI codebase
Running this on Tailwind UI's codebase it looks like this:
<img width="1552" alt="image"
src="https://github.com/user-attachments/assets/21785428-5e0d-47f7-80ec-dab497f58784">
---------
Co-authored-by: Jordan Pittman <jordan@cryptica.me>
This PR adds a new `in-*` variant that allows you to apply utilities
when you are in a certain selector.
While doing research for codemods, we notice that some people use
`group-[]:flex` (yep, the arbitrary value is empty…). The idea behind is
that people want to know if you are in a `.group` or not.
Similarly, some people use `group-[]/name:flex` to know when you are in
a `.group/name` class or not.
This new `in-*` variant allows you to do that without any hacks.
If you want to check whether you are inside of a `p` tag, then you can
write `in-[p]:flex`. If you want to check that you are inside of a
`.group`, you can write `in-[.group]`.
This variant is also a compound variant, which means that you can write
`in-data-visible:flex` which generates the following CSS:
```css
:where([data-visible]) .in-data-visible\:flex {
display: flex;
}
```
This variant also compounds with `not-*`, for example:
`not-in-[.group]:flex`.
Additionally, this PR also includes a codemod to convert `group-[]:flex`
to `in-[.group]:flex`.
---
This was proposed before for v3 in #13912
---------
Co-authored-by: Eloy Espinaco <eloyesp@gmail.com>
Co-authored-by: Jordan Pittman <jordan@cryptica.me>
This PR adds a migration to convert the `[&>*]` variant to the `*`
variant. Additionally this PR also converts the `[&_*]` variant to the
`**` variant.
We use this variant in Catalyst for example, and now that the
specificity is the same as `*`, we can use the more modern syntax
instead.
# Test plan:
Running this on Catalyst results in a diff like:
<img width="615" alt="image"
src="https://github.com/user-attachments/assets/f384885e-cae1-4b6b-80ab-85f76fa89a33">
<img width="833" alt="image"
src="https://github.com/user-attachments/assets/8a185e1d-0f1b-4fe6-9e06-ca7597534398">
Note: the swapped order of variants is another codemod at work
---------
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
This PR re-introduces the automatic var injection feature.
For some backstory, we used to support classes such as `bg-[--my-color]`
that resolved as-if you wrote `bg-[var(--my-color)]`.
The is issue is that some newer CSS properties accepts dashed-idents
(without the `var(…)`). This means that some properties accept
`view-timeline-name: --my-name;` (see:
https://developer.mozilla.org/en-US/docs/Web/CSS/view-timeline-name).
To make this a tiny bit worse, these properties _also_ accept
`var(--my-name-reference)` where the variable `--my-name-reference`
could reference a dashed-ident such as `--my-name`.
This makes the `bg-[--my-color]` ambiguous because we don't know if you
want `var(--my-color)` or `--my-color`.
With this PR, we bring back the automatic var injection feature as
syntactic sugar, but we use a different syntax to avoid the ambiguity.
Instead of `bg-[--my-color]`, you can now write `bg-(--my-color)` to get
the same effect as `bg-[var(--my-color)]`.
This also applies to modifiers, so `bg-red-500/[var(--my-opacity)]` can
be written as `bg-red-500/(--my-opacity)`. To go full circle, you can
rewrite `bg-[var(--my-color)]/[var(--my-opacity)]` as
`bg-(--my-color)/(--my-opacity)`.
---
This is implemented as syntactical sugar at the parsing stage and
handled when re-printing. Internally the system (and every plugin) still
see the proper `var(--my-color)` value.
Since this is also handled during printing of the candidate, codemods
don't need to be changed but they will provide the newly updated syntax.
E.g.: running this on the Catalyst codebase, you'll now see changes like
this:
<img width="542" alt="image"
src="https://github.com/user-attachments/assets/8f0e26f8-f4c9-4cdc-9f28-52307c38610e">
Whereas before we converted this to the much longer
`min-w-[var(--button-width)]`.
---
Additionally, this required some changes to the Oxide scanner to make
sure that `(` and `)` are valid characters for arbitrary-like values.
---------
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
This PR adds an improvement to the upgrade tool to make sure that if you
pass a single CSS file, that the upgrade tool resolves all the imports
in that file and processes them as well.
Test plan:
---
Created a project where `index.css` imports `other.css`. Another
`leave-me-alone.css` is created to proof that this file is _not_
changed. Running the upgrade guide using `index.css` also migrates
`other.css` but not `leave-me-alone.css`.
Here is a video so you don't have to manually create it:
https://github.com/user-attachments/assets/20decf77-77d2-4a7c-8ff1-accb1c77f8c1
We noticed that in the current alpha 34 release, the `package.json` file
of the `@tailwindcss/node` package only defines `tailwindcss` as a dev
dependency. This makes it very easy for version mismatches to happen
when a v3 version (or an earlier v4 alpha for that matter) was installed
in the same project:
```json
{
"name": "@tailwindcss/node",
"version": "4.0.0-alpha.34",
"description": "A utility-first CSS framework for rapidly building custom user interfaces.",
"license": "MIT",
"repository": {
"type": "git",
"url": "https://github.com/tailwindlabs/tailwindcss.git",
"directory": "packages/@tailwindcss-node"
},
"bugs": "https://github.com/tailwindlabs/tailwindcss/issues",
"homepage": "https://tailwindcss.com",
"files": [
"dist/"
],
"publishConfig": {
"provenance": true,
"access": "public"
},
"exports": {
".": {
"types": "./dist/index.d.ts",
"import": "./dist/index.mjs",
"require": "./dist/index.js"
},
"./require-cache": {
"types": "./dist/require-cache.d.ts",
"default": "./dist/require-cache.js"
},
"./esm-cache-loader": {
"types": "./dist/esm-cache.loader.d.mts",
"default": "./dist/esm-cache.loader.mjs"
}
},
"devDependencies": {
"tailwindcss": "4.0.0-alpha.34"
},
"dependencies": {
"enhanced-resolve": "^5.17.1",
"jiti": "^2.0.0-beta.3"
},
"scripts": {
"build": "tsup-node",
"dev": "pnpm run build -- --watch"
}
}
```
Furthermore, we were trying to fix issues where our integration test
setup could not install `tailwindcss@3` because of how we did pnpm
overrides.
This PR fixes this by:
- Ensuring every client that calls into `tailwindcss` core marks it as a
version-pinned dependency. You are still required to install
`tailwindcss` in your project along side a client (e.g.
`@tailwindcss/vite`) but we now only use your installed version for
importing the respective `.css` files. For the core logic, we are now
requiring each package to use `tailwindcss` at the same version. This
should help resolve issues like
https://github.com/tailwindlabs/tailwindcss/discussions/14652
- We tried to eliminate the dependency on `tailwindcss` from the
`@tailwindcss/upgrade` package. Unfortunately this is not possible to do
right now because we need to load the CSS files from v4 to create the
right environment. In a future version we could bundle the required CSS
files with `@tailwidncss/upgrade` but it doesn't seem necessary for now.
- We then changed our integration test overrides to only override the
`tailwindcss` package that are dependencies of the known list of
packages that we have `tailwindcss` dependencies on: `@tailwindcss/node`
and `@tailwindcss/upgrade`. This ensures that we can install v3 of
`tailwindcss` in the integration tests and it will work. Something we
want to do for some upgrade tests.
# Test plan
Integration work again. Furthermore we added a quick setup with the CLI
using the local tarballs and ensured it works:
```bash
pnpm init
pnpm install ../../tailwindcss/dist/tailwindcss-cli.tgz
pnpm install ../../tailwindcss/dist/tailwindcss.tgz
echo '@import "tailwindcss";' > index.css
echo '<div class="underline"></div>' > index.html
pnpm tailwindcss -i index.css -o out.css
cat out.css
```
This PR adds support for handling v3 [`container` customizations
](https://tailwindcss.com/docs/container#customizing). This is done by
adding a custom utility to extend the core `container` utility. A
concrete example can be taken from the added integration test.
### Input
```ts
/** @type {import('tailwindcss').Config} */
export default {
content: ['./src/**/*.html'],
theme: {
container: {
center: true,
padding: {
DEFAULT: '2rem',
'2xl': '4rem',
},
screens: {
md: '48rem', // Matches a default --breakpoint
xl: '1280px',
'2xl': '1536px',
},
},
},
}
```
### Output
```css
@import "tailwindcss";
@utility container {
margin-inline: auto;
padding-inline: 2rem;
@media (width >= theme(--breakpoint-sm)) {
max-width: none;
}
@media (width >= 48rem) {
max-width: 48rem;
}
@media (width >= 1280px) {
max-width: 1280px;
}
@media (width >= 1536px) {
max-width: 1536px;
padding-inline: 4rem;
}
}
````
## Test Plan
This PR adds extensive tests to the compat layer as part of unit tests.
Additionally it does at a test to the codemod setup that shows that the
right `@utility` code is generated. Furthermore I compared the
implementation against v3 on both the compat layer and the custom
`@utility`:
https://github.com/user-attachments/assets/44d6cbfb-4861-4225-9593-602b719f628f
This PR fixes an issue where imports above Tailwind directives didn't
get a `layer(…)` argument.
Given this CSS:
```css
@import "./typography.css";
@tailwind base;
@tailwind components;
@tailwind utilities;
```
It was migrated to:
```css
@import "./typography.css";
@import "tailwindcss";
```
But to ensure that the typography styles end up in the correct location,
it requires the `layer(…)` argument.
This PR now migrates the input to:
```css
@import "./typography.css" layer(base);
@import "tailwindcss";
```
Test plan:
---
Added an integration test where an import receives the `layer(…)`, but
an import that eventually contains `@utility` does not receive the
`layer(…)` argument. This is necessary otherwise the `@utility` will be
nested when we are processing the inlined CSS.
Running this on the Commit template, we do have a proper `layer(…)`
<img width="585" alt="image"
src="https://github.com/user-attachments/assets/538055e6-a9ac-490d-981f-41065a6b59f9">
This PR fixes an issue where an `@config` was injected in a strange
location if you have multiple CSS files with Tailwind directives.
Let's say you have this setup:
```css
/* ./src/index.css */
@import "./tailwind-setup.css";
/* ./src/tailwind-setup.css */
@import "./base.css";
@import "./components.css";
@import "./utilities.css";
/* ./src/base.css */
@tailwind base;
/* ./src/components.css */
@tailwind components;
/* ./src/utilities.css */
@tailwind utilities;
```
In this case, `base.css`, `components.css`, and `utilities.css` are all
considered Tailwind roots because they contain Tailwind directives or
imports.
Since there are multiple roots, the nearest common ancestor should
become the tailwind root (where `@config` is injected). In this case,
the nearest common ancestor is `tailwind-setup.css` (not `index.css`
because that's further away).
Before this change, we find the common ancestor between `base.css` and
`components.css` which would be `index.css` instead of
`tailwind-setup.css`.
In a next iteration, we compare `index.css` with `utilities.css` and
find that there is no common ancestor (because the `index.css` file has
no parents). This resulted in the `@config` being injected in
`index.css` and in `utilities.css`.
Continuing with the rest of the migrations, we migrate the `index.css`'s
`@config` away, but we didn't migrate the `@config` from
`utilities.css`.
With this PR, we don't even have the `@config` in the `utilities.css`
file anymore.
Test plan
---
1. Added an integration test with a non-migrateable config file to
ensure that the `@config` is injected in the correct file.
2. Added an integration test with a migrateable config file to ensure
that the CSS config is injected in the correct file. h/t @philipp-spiess
3. Ran the upgrade on the https://commit.tailwindui.com project and
ensured that
1. The `@config` does not exist in the `utilities.css` file (this was
the first bug we solved)
2. The `@config` is replaced in the `tailwind.css` file correctly.
<img width="592" alt="image"
src="https://github.com/user-attachments/assets/02e3f6ea-a85d-46c2-ac93-09f34ac4a4b8">
<img width="573" alt="image"
src="https://github.com/user-attachments/assets/e372eb5f-5732-4052-ab39-096ba7970ff6">
This PR fixes an issue where we migrated classes such as `rounded` to
`rounded-sm` (see:
https://github.com/tailwindlabs/tailwindcss/pull/14875)
However, if you override the values in your `tailwind.config.js` file,
then the migration might not be correct.
This PR makes sure to only migrate the classes if you haven't overridden
the values in your `tailwind.config.js` file.
---------
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
This PR removes the `negative` flag from the `Candidate` AST. The system
itself doesn't this information at all, but it's up to each plugin to
handle the `negative` flag themselves.
This also means that if you _don't_ handle it, that `foo` and `-foo`
results in the same CSS output.
To make sure that the negative version of utilities that supported it
still work, this PR also adds the negative versions as separate
utilities. E.g.: `-scale` is registered in addition to `scale`.
This is an internal refactor only, and doesn't change any behavior.
---------
Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
This PR converts legacy commas in arbitrary values to spaces.
In Tailwind CSS v3, we allowed commas in arbitrary values for
`grid-cols-[…]`, `grid-rows-[…]`, and `object-[…]` for backwards
compatibility. The underlying CSS value did use spaces instead of
commas.
This PR adds a code mod where convert the commas to spaces when we see
them.
Test plan:
---
Running this on Catalyst it goes from this:
<img width="393" alt="image"
src="https://github.com/user-attachments/assets/03cbda73-41f9-4601-b77a-5b511226b876">
To the expected value of:
<img width="376" alt="image"
src="https://github.com/user-attachments/assets/dd9bbe01-5eb1-4340-937b-70c435e7e4f0">
---------
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
This PR adds a migration where we detect arbitrary variants and try to
upgrade them to built-in variants.
For example, if you are using `[[data-visible]]:flex`, we can convert it
to `data-visible:flex`. We can also upgrade more advanced examples such
as `has-[[data-visible]]:flex` to a compound variant which becomes
`has-data-visible:flex`.
A table of example migrations:
| Before | After |
| ------------------------------------------ |
---------------------------------- |
| `[[data-visible]]:flex` | `data-visible:flex` |
| `[&[data-visible]]:flex` | `data-visible:flex` |
| `[[data-visible]&]:flex` | `data-visible:flex` |
| `[[data-url*="example"]]:flex` | `data-[url*="example"]:flex` |
| `[[data-url$=".com"_i]]:flex` | `data-[url$=".com"_i]:flex` |
| `[[data-url$=.com_i]]:flex` | `data-[url$=.com_i]:flex` |
| `[&:is([data-visible])]:flex` | `data-visible:flex` |
| `has-[[data-visible]]:flex` | `has-data-visible:flex` |
| `has-[&:is([data-visible])]:flex` | `has-data-visible:flex` |
| `has-[[data-slot=description]]:flex` |
`has-data-[slot=description]:flex` |
| `has-[&:is([data-slot=description])]:flex` |
`has-data-[slot=description]:flex` |
| `has-[[aria-visible="true"]]:flex` | `has-aria-visible:flex` |
| `has-[[aria-visible]]:flex` | `has-aria-[visible]:flex` |
We can also convert combinators from `[&>[data-visible]]:flex` to just
`*:data-visible:flex` and `[&_[data-visible]]:flex` to
`**:data-visible:flex`.
| Before | After |
| --- | --- |
| `[&>[data-visible]]:flex` | `*:data-visible:flex` |
| `[&_>_[data-visible]]:flex` | `*:data-visible:flex` |
| `[&_[data-visible]]:flex` | `**:data-visible:flex` |
Additionally, if you have complex selectors with `:not()`, we can
convert this to a compound `not-*` variant in some cases as well:
| Before | After |
| --- | --- |
| `[&:nth-child(2)]:flex` | `nth-2:flex` |
| `[&:not(:nth-child(2))]:flex` | `not-nth-2:flex` |
If some of the values in `nth-child(…)` are a bit too complex, then we
still try to convert them but to arbitrary values instead.
| Before | After |
| --- | --- |
| `[&:nth-child(-n+3)]:flex` | `nth-[-n+3]:flex` |
| `[&:not(:nth-child(-n+3))]:flex` | `not-nth-[-n+3]:flex` |
This also implements some optimizations around `even` and `odd`:
| Before | After |
| --- | --- |
| `[&:nth-child(odd)]:flex` | `odd:flex` |
| `[&:not(:nth-child(odd))]:flex` | `even:flex` |
| `[&:nth-child(even)]:flex` | `even:flex` |
| `[&:not(:nth-child(even))]:flex` | `odd:flex` |
Some examples that stay as-is:
- `has-[&>[data-visible]]:flex` we can't upgrade this one because
`has-*` is not a valid variant.
- `has-[[data-visible][data-dark]]:flex` we can't upgrade this one
because `[data-visible][data-dark]` has to be on the same element. If we
convert this to `has-data-visible:has-data-dark:flex` then this
condition will be true if an element exists with `data-visible` and
another element exists with `data-dark` but we don't guarantee that they
are the same element.
---
Running this on the Catalyst codebase results in some updates that look
like this:
<img width="676" alt="image"
src="https://github.com/user-attachments/assets/6f0ff21d-5037-440b-9b80-0997ab0c11dd">
<img width="397" alt="image"
src="https://github.com/user-attachments/assets/8f0856fa-1709-404a-ac34-7d8c661fa799">
---------
Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
This PR reverts a change we made for v4 that added borders to inputs by
default. It feels like we have to go further than this for this to
actually be useful to anyone, and since there were no borders in v3 it's
also a breaking change.
If we wanted to make form elements look more "normal" out of the box I
think we need to do something more like this:
https://play.tailwindcss.com/icCwFLVp4z?file=css
But it's a huge rabbit hole and there are so many stupid details to get
right that it feels like an insurmountable task, and if we can't go all
the way with it it's better to just maximize compatibility with v3.
---------
Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
This PR renames the existing `outline-none` utility to `outline-hidden`,
and adds a new simpler `outline-none` utility that just sets
`outline-style: none`.
The existing `outline-none` utility doesn't actually set `outline:
none`, and instead creates a 2px invisible outline:
```css
.outline-none {
outline: 2px solid transparent;
outline-offset: 2px;
}
```
We implemented it this way because people often use `outline: none` to
hide focus rings and replace them with custom shadow-based focus rings,
without realizing that that approach leads to no visible focus ring in
forced colors mode because box shadows aren't rendered in forced colors
mode.
While this is sort of helpful and clever, it can be a pain when you
really do need `outline: none`, and I think it feels surprising in
hindsight to hijack the name of an existing CSS property value and make
it mean something else.
The name `outline-hidden` feels better because it's a new keyword that
CSS doesn't use for outlines, and implies that perhaps there's a bit
more going on than just setting `outline-style: none`.
This PR includes a codemod to convert any existing use of `outline-none`
to `outline-hidden`, and we will be sure to explain what
`outline-hidden` does for you in the v4 documentation.
Manually tested this in the Vite playground to make sure it behaves as
expected 👍
---------
Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
This PR fixes an issue where our codemod migrations can convert
`bg-[theme(colors.white/15%)]` to `bg-[var(--color-white)]/15` where the
`15%` from within the `theme(…)` is converted to a candidate modifier
(at the end).
The idea was that if the `theme(…)` is used with a modifier, then it can
only be used with colors. If a candidate uses it, it also means that a
color was used and we can use `/15` instead.
However this is not true if it is used as part of a bigger value. E.g.:
`shadow-[shadow:inset_0_0_0_1px_theme(colors.white/15%)]` would be
converted to `shadow-[inset_0_0_0_1px_var(--color-white)]/15` which is
not correct because the value isn't a color, the color is _part_ of the
value.
In this case, we make sure that the `theme(…)` is the only AST node in
the value, and if it is we can safely do the conversion. If there are
other AST nodes we keep the `theme(…)` call.
---------
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
We noticed an issue that the `theme()` function wourld not properly
parse in CSS if you split the argument list over multiple lines. This is
fixed by treating `\n` and `\t` the same as space:
```css
.custom-font {
font-family: theme(
fontFamily.unknown,
Helvetica Neue,
Helvetica,
sans-serif
);
}
```
## Test plan
Added tests, but also tried it in the Vite example:
<img width="1995" alt="Screenshot 2024-11-08 at 13 46 09"
src="https://github.com/user-attachments/assets/f9bf94b0-3f9b-4334-8911-9190987e2df5">
This ensures our glob hoisting mechanism (see #14896) works on Windows
when performing an upgrade.
---------
Co-authored-by: Jordan Pittman <jordan@cryptica.me>
This PR adds migrations for the recent changes to the `--spacing` scale
done in #12263.
There are a few steps that we do to ensure we have the best upgrade
experience:
- If you are overwriting the `spacing` theme with custom values, we now
check if the new values are multiplies of the default spacing scale.
When they are, we can safely remove the overwrite.
- If you are extending the `spacing` theme, we will unset the default
`--spacing` scale and only use the values you provided.
- Any `theme()` function calls are replaced with `calc(var(--spacing) *
multiplier)` unless the values are extending the default scale.
One caveat here is for `theme()` key which can not be replaced with
`var()` (e.g. in `@media` attribute positions). These will not be able
to be replaced with `calc()` either so the following needs to stay
unmigrated:
```css
@media (max-width: theme(spacing.96)) {
.foo {
color: red;
}
}
```
## Test plan
We are mainly testing two scenarios: The JS config _extends_ the
`spacing` namespace and the JS config _overwrites_ the `spacing`
namespace. For both cases we have added an integration test each to
ensure this works as expected. The test contains a mixture of keys (some
of it matching the default multiples, some don't, some have different
scales, and some use non-numeric identifiers). In addition to asserting
on the created CSS `@theme`, we also ensure that `theme()` calls are
properly replaced.
---------
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
This PR updates all of the `--font-size-*` variables to `--text-*`
instead to closer match the utility names.
```diff
@theme {
- --font-size-xs: 0.75rem;
- --font-size-xs--line-height: 1rem;
- --font-size-sm: 0.875rem;
- --font-size-sm--line-height: 1.25rem;
- --font-size-base: 1rem;
- --font-size-base--line-height: 1.5rem;
- --font-size-lg: 1.125rem;
- --font-size-lg--line-height: 1.75rem;
- --font-size-xl: 1.25rem;
- --font-size-xl--line-height: 1.75rem;
/* ... */
+ --text-xs: 0.75rem;
+ --text-xs--line-height: 1rem;
+ --text-sm: 0.875rem;
+ --text-sm--line-height: 1.25rem;
+ --text-base: 1rem;
+ --text-base--line-height: 1.5rem;
+ --text-lg: 1.125rem;
+ --text-lg--line-height: 1.75rem;
+ --text-xl: 1.25rem;
+ --text-xl--line-height: 1.75rem;
/* ... */
}
```
This is part of a bigger set of changes where we're renaming other theme
variables as well with the same goals, since many existing theme
variables like `--shadow-*` and `--radius-*` are already not using the
explicit CSS property name.
---------
Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
Co-authored-by: Jordan Pittman <jordan@cryptica.me>
This PR fixes an issue where globs in you `content` configuration escape
the current "root" of the project.
This can happen if you have a folder, and you need to look up in the
tree (e.g.: when looking at another package in a monorepo, or in case of
a Laravel project where you want to look at mail templates).
This applies a similar strategy we already implement on the Rust side.
1. Expand braces in the globs
2. Move static parts of the `pattern` to the `base` of the glob entry
object
---
Given a project setup like this:
```
.
├── admin
│ ├── my-tailwind.config.ts
│ └── src
│ ├── abc.jpg
│ ├── index.html
│ ├── index.js
│ └── styles
│ └── input.css
├── dashboard
│ ├── src
│ │ ├── index.html
│ │ ├── index.js
│ │ ├── input.css
│ │ └── pickaday.css
│ └── tailwind.config.ts
├── package-lock.json
├── package.json
├── postcss.config.js
└── unrelated
└── index.html
7 directories, 14 files
```
If you then have this config:
```ts
// admin/my-tailwind.config.ts
export default {
content: {
relative: true,
files: ['./src/**/*.html', '../dashboard/src/**/*.html'],
// ^^ this is the important part, which escapes
// the current root of the project.
},
theme: {
extend: {
colors: {
primary: 'red',
},
},
},
}
```
Then before this change, running the command looks like this:
<img width="1760" alt="image"
src="https://github.com/user-attachments/assets/60e2dfc7-3751-4432-80e3-8b4b8f1083d4">
After this change, running the command looks like this:
<img width="1452" alt="image"
src="https://github.com/user-attachments/assets/5c47182c-119c-4732-a253-2dace7086049">
---------
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
During the migration process, a lot of changes to the CSS file happen.
Some parts are converted, some parts are deleted and some new CSS is
added.
To make sure we are generating a sensible and good looking CSS file, we
will sort the final CSS and pretty print it.
The order we came up with looks like this:
```css
/* Imports */
@import "tailwindcss";
@import "../other.css";
/* Configuration */
@config "../path/to/tailwindcss.config.js";
@plugin "my-plugin-1";
@plugin "my-plugin-2";
@source "./foo/**/*.ts";
@source "./bar/**/*.ts";
@variant foo {}
@variant bar {}
@theme {}
/* Border compatibility CSS */
@layer base {}
/* Utilities */
@utility foo {}
@utility bar {}
/* Rest of your own CSS if any */
```
---------
Co-authored-by: Philipp Spiess <hello@philippspiess.com>
This PR renames all of the `--width-*` variables to `--container-*` to
better communicate the purpose of these tokens as layout container
sizes. These are the values that were historically stored under
`maxWidth` in the v3 and earlier eras, and were also re-used by the
container queries plugin.
The name `--container-*` feels like a better match alongside the
`--breakpoint-*` namespace and since these both serve that same sort of
purpose it makes sense to me that the name should be optimized for
feeling "right" in that context.
I like that this also sort of advertises Tailwind's support for
container queries directly in the CSS variables themselves, and helps
people understand what these are really intended to be used for.
---------
Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
This PR adds a migration for migrating the changes we implemented in
https://github.com/tailwindlabs/tailwindcss/pull/14849
This is the migration we perform:
| Old | New |
| ----------------- | ------------------ |
| `shadow` | `shadow-sm` |
| `shadow-sm` | `shadow-xs` |
| `shadow-xs` | `shadow-2xs` |
| `inset-shadow` | `inset-shadow-sm` |
| `inset-shadow-sm` | `inset-shadow-xs` |
| `inset-shadow-xs` | `inset-shadow-2xs` |
| `drop-shadow` | `drop-shadow-sm` |
| `drop-shadow-sm` | `drop-shadow-xs` |
| `rounded` | `rounded-sm` |
| `rounded-sm` | `rounded-xs` |
| `blur` | `blur-sm` |
| `blur-sm` | `blur-xs` |
Also added an integration test to ensure that `shadow` is properly
migrated to `shadow-sm`, and doesn't get migrated to `shadow-xs`
(because `shadow-sm` is migrated to `shadow-xs`).
This PR removes all of the static `font-weight` utilities that were
previously hard-coded into the framework in favor of deriving those
utilities from the `--font-weight-*` theme values instead.
Biggest motivation for this is giving people a way to explicitly disable
font-weight utilities they don't want to use in their project, which
previously wasn't possible.
---------
Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
This PR replaces the default spacing scale (`--spacing-*`) with a
generative system based on a default spacing _unit_.
Instead of the default theme containing values like `--spacing-4`,
`--spacing-6`, `--spacing-8`, etc., instead we just define a single
`--spacing` value:
```css
@theme {
--spacing: 0.25rem;
}
```
Utilities like `px-4` are derived from this unit by multiplying it by
the value in the utility (4 in this case):
```css
.px-4 {
padding-inline: calc(var(--spacing) * 4);
}
```
The biggest consequence of this change is that every value is available
now, rather than just the explicitly configured values.
This means utilities like `px-42` will work now, whereas prior to this
PR only `px-40` and `px-44` were valid utilities. I personally found it
very difficult to know which values actually existed at the higher end
of the scale without IntelliSense, and in practice even when working
with a skilled designer like [Steve](https://x.com/steveschoger) who
helped design Tailwind's default spacing scale, I'd very often need to
break out of it to implement a design, and trying to round to a value
that was in the scale made the design worse, not better.
This PR allows you to use any whole number, as well as decimal numbers
that are multiples of `0.25` to ensure classes like `px-1.5` continue to
work. While this means you can now technically do things like
`pt-97.25`, I think the presence of the fractional value will be enough
of a signal to developers that they are doing something a little
unusual, and they can use their judgment as to whether they are making
the right decision or not.
I'll update this PR with a lot more detail when I have a chance, as
there are a few other things to explain like:
- Unifying all of the values for
width/min-width/max-width/height/min-height/max-height utilities
- Deriving numeric line-height values from the spacing multiplier
instead of a separate line-height scale
- Using `--spacing: initial` to disable the multiplier
- How you can still use an explicit spacing scale and ignore this change
- How we plan to use IntelliSense to surface a more curated set of
spacing values even if smaller increments work when you type them
explicitly
---------
Co-authored-by: Adam Wathan <4323180+adamwathan@users.noreply.github.com>
When migrating a project from Tailwind CSS v3 to Tailwind CSS v4, then
we started the migration process in the following order:
1. Migrate the JS/TS config file
2. Migrate the source files (found via the `content` option)
3. Migrate the CSS files
However, if you have a setup where you have multiple CSS root files
(e.g.: `frontend` and `admin` are separated), then that typically means
that you have an `@config` directive in your CSS files. These point to
the Tailwind CSS config file.
This PR changes the migration order to do the following:
1. Build a tree of all the CSS files
2. For each `@config` directive, migrate the JS/TS config file
3. For each JS/TS config file, migrate the source files
If a CSS file does not contain any `@config` directives, then we start
by filling in the `@config` directive with the default Tailwind CSS
config file (if found, or the one passed in). If no default config file
or passed in config file can be found, then we will error out (just like
we do now)
---------
Co-authored-by: Adam Wathan <adam.wathan@gmail.com>
