Skip to content

Conversation

RobinMalfait
Copy link
Member

@RobinMalfait RobinMalfait commented Aug 27, 2025

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
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant