Skip to content

Navigation Menu

Sign in
Appearance settings

Search code, repositories, users, issues, pull requests...

Provide feedback

We read every piece of feedback, and take your input very seriously.

Saved searches

Use saved searches to filter your results more quickly

Sign up
Appearance settings

Improve error messages when migrating a JS config file goes wrong #18808

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
RobinMalfait wants to merge 5 commits into main
base: main
Choose a base branch
Loading
from fix/improve-error-handling-when-migrating-config-file

Conversation

Copy link
Member

@RobinMalfait RobinMalfait commented Aug 27, 2025
edited
Loading

This PR updates some error messages with more insights to know what went wrong or why we didn't migrate the JS config file when going from v3 to v4.

Let's say you have a crazy configuration file like this:

module.exports = {
 content: ['app/**/*.{ts,tsx}'],
 presets: [require('./preset.config')], // 1. Presets
 somethingHereThatDoesNotExist: { // 2. Unknown top-level key, but valid value
 darkMode: ['class'],
 },
 unknown: /as-a-regex/g, // 3. Unknown top-level key, and invalid value
 theme: {
 notSure: { // 4. Unknown theme key
 howToMigrate: 'this theme key',
 },
 aria: { // 5. Known theme key, but blocked
 busy: 'busy="true"',
 },
 extend: {
 foo: true, // 6. Unknown theme key, invalid value
 booleans: { // 7. Unknown theme key
 areCool: true,
 },
 notEven: { // 7. Unknown theme key
 regexes: /test/i,
 },
 screens: {
 complex: {
 raw: '(min-width: 500px) and (max-width: 700px)' // 8. Complex screen config
 }
 },
 },
 }
}

I know it's made up, but just trying to highlight the different kinds of issue we run into and decide not to migrate.

More than happy to adjust the messages. I also included a bunch of different types to check different categories of issues. But migrating a config like this, will result in:
image

Still a draft, because the category about data, aria and supports variants and also the category about complex screens is something I just want to solve properly.

RobinMalfait added a commit that referenced this pull request Aug 28, 2025
This PR migrates `aria` theme keys when migrating from Tailwind CSS v3
to v4.
While working on improving some of the error messages to get more
insights into why migrating the JS file changed
(#18808), I ran into an
issue where I couldn't think of a good comment to why `aria` theme keys
were not being migrated. (Internally we have `aria` "blocked").
So instead of figuring out a good error message..., I just went ahead
and added the migration for `aria` theme keys.
Let's imagine you have the following Tailwind CSS v3 configuration:
```ts
export default {
 content: ['./src/**/*.html'],
 theme: {
 extend: {
 aria: {
 // Built-in (not really, but visible because of intellisense)
 busy: 'busy="true"',
 // Automatically handled by bare values
 foo: 'foo="true"',
 // ^^^ ^^^ ← same names
 // Not automatically handled by bare values because names differ
 bar: 'baz="true"',
 // ^^^ ^^^ ← different names
 // Completely custom
 asc: 'sort="ascending"',
 desc: 'sort="descending"',
 },
 },
 },
}
```
Then we would generate the following Tailwind CSS v4 CSS:
```css
@custom-variant aria-bar (&[aria-baz="true"]);
@custom-variant aria-asc (&[aria-sort="ascending"]);
@custom-variant aria-desc (&[aria-sort="descending"]);
```
Notice how we didn't generate a custom variant for `aria-busy` or
`aria-foo` because those are automatically handled by bare values.
We could also emit a comment near the CSS to warn about the fact that
`@custom-variant` will always be sorted _after_ any other built-in
variants.
This could result in slightly different behavior, or different order of
classes when using `prettier-plugin-tailwindcss`.
I don't know how important this is, because before this PR we would just
use `@config './tailwind.config.js';`.
Edit: when using the `@config` we override `aria` and extend it, which
means that it would be in the expected order 🤔
---------
Co-authored-by: Jordan Pittman <thecrypticace@gmail.com>
RobinMalfait and others added 5 commits August 28, 2025 16:53
Nothing new here, but this improves the error messages a bit when using
`addComponents` or `matchComponents` because otherwise the error shows
`addUtilities` or `matchUtilities`.
These also add an additional note:
> Note: in Tailwind CSS v4, `matchComponents` is an alias for `matchUtilities`.
Otherwise `Reflect.ownKeys` would crash on non-object values.
Co-Authored-By: Jordan Pittman <thecrypticace@gmail.com>
Before this, we would just show "Cannot migrate"-like error messages.
But this will show a bit more detail about which theme keys are the
culprit.
Co-Authored-By: Jordan Pittman <thecrypticace@gmail.com>
Co-Authored-By: Jordan Pittman <thecrypticace@gmail.com>
When splitting `'foo\n\nbar'` by `\n`, you will get `['foo', '', 'bar']`.
The `''` value will result in `[]` after the word wrapping. This
information gets lost when we `flatMap`, so let's keep the newline using
`['']` as the fallback.
@RobinMalfait RobinMalfait force-pushed the fix/improve-error-handling-when-migrating-config-file branch from f463296 to 1d1535a Compare August 28, 2025 14:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

AltStyle によって変換されたページ (->オリジナル) /