# Upgrade Tailwind CSS v3 to v4

Yes. The agent runs the official upgrade tool, repairs what it gets wrong, updates the linters and helpers tied to version 3 and compares the built pages.

[Run this on Rush](https://cloud.getrush.ai/run/migrate-tailwind-v4/tailwind/). Opens the console with this prompt ready to send, in a Project that has your repository.

## What the agent does

The official tool does most of the rewriting, so the agent's job is everything around it: getting it to run, reading its diff, and fixing what it could not know. In a Vite app like alan2207/bulletproof-react (`apps/react-vite`), version 3 is spread over five places. `package.json` has `tailwindcss` `^3.4.3` with `autoprefixer`; `tailwind.config.cjs` holds the content globs, a centred `container`, an Inter font stack, colours mapped to `hsl(var(--...))` variables and two plugins, `tailwindcss-animate` and `@tailwindcss/typography`; `postcss.config.cjs` loads `tailwindcss`; `src/index.css` starts with the three `@tailwind` directives; and `.eslintrc.cjs` extends `plugin:tailwindcss/recommended`. The agent records the build, lint, type check and test results first and takes screenshots of the built pages in the sandbox's browser.

Then it runs `npx @tailwindcss/upgrade` on a clean working tree. With version 4.3.4 of the tool, current when this page was written, installing it compiles its `tree-sitter` dependency, and on a machine with no C++ compiler `npx` exits with status 1 and prints nothing; installing `g++` and `make` lets it run. On this app the tool deletes `tailwind.config.cjs`, moves its contents into `src/index.css` as `@import 'tailwindcss'`, two `@plugin` lines, an `@utility container` block and an `@theme` block, adds a base rule that keeps version 3's default border colour, replaces the PostCSS plugin with `@tailwindcss/postcss`, removes `autoprefixer`, and renames utilities in 17 component files: `outline-none` to `outline-hidden`, `shadow-sm` to `shadow-xs`, `shadow` to `shadow-sm`, `rounded` to `rounded-sm`.

Two things are broken afterwards, and neither is in the tool's output. The build fails in `tsc`: in `src/components/ui/table/pagination.tsx` the tool rewrites `variant: isActive ? 'outline' : 'ghost'` to `'outline-solid'`, taking a Button variant name for the `outline` utility that version 4 renamed. The agent restores that string and searches the diff for the same mistake in any other non-class string. And `yarn lint` stops before linting a file, with `ERR_PACKAGE_PATH_NOT_EXPORTED`: `eslint-plugin-tailwindcss` 3.15.1 declares `tailwindcss` `^3.4.0` as its peer and imports `tailwindcss/resolveConfig`, which version 4 does not export. The plugin's own version 4 supports Tailwind 4 but requires ESLint 9 or later, and this app is on ESLint 8 with an `.eslintrc.cjs`. So the agent removes the plugin from the config and reports the ESLint upgrade as the way to get it back.

The last pass is what no command reports. `src/utils/cn.ts` merges classes with `tailwind-merge` `^2.3.0`, which resolves conflicts between version 3 class names, so the agent moves it to the major that knows version 4's and checks the `cn` calls that override a shadow or an outline. It rebuilds, takes the same screenshots again and compares them. The 21 Vitest tests pass before and after, and that proves little: they run in jsdom, which applies no stylesheet, so a page with every colour missing would pass them too.

## Start it with one API call

`POST https://api.phoenix.so/o/{org}/sessions`

```json
{
  "agent": "claude",
  "input": "Upgrade this project from Tailwind CSS 3 to the current Tailwind CSS 4. Read package.json, the Tailwind and PostCSS configs, the main stylesheet, the ESLint and Prettier configs, the class-merging helper and the bundler config first. Install dependencies, create .env from .env.example, and record the build, lint, type check and test results before changing anything. Build the app, serve it and take screenshots of the main pages and, if there is a Storybook, of its stories; keep them as the baseline. Run the official upgrade tool, npx @tailwindcss/upgrade, on a clean working tree; if it fails to install or exits without output, find out why (it may need a C++ compiler) and fix that. Read the whole diff. Revert any change the tool made to a string that is not a class list, such as a component variant name. Then make build, lint, type check and tests pass again: update or remove lint plugins and helpers that only support version 3, including the class-merging library, and say what you did with each. Do not hand-edit class names beyond what the tool changed unless a screenshot shows a difference. Take the same screenshots again and compare them with the baseline; list every visible difference and fix those that come from changed defaults. Do not switch the build integration unless asked; note it as a follow-up. Open a pull request with the tool's summary, the manual fixes, the before and after screenshots and the output of every check.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
```

1. **Get an API key.** In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
2. **Send the request.** POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
3. **Read what came back.** Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

## What comes back

A pull request in two commits a reviewer can read apart: the upgrade tool's output untouched, then the agent's repairs. The description gives the tool's own summary, then a short list of manual changes with the reason for each: the variant name restored in `pagination.tsx`, the lint plugin removed, `tailwind-merge` moved to a version 4 aware major, and any class the screenshots showed drifting.

It carries the before and after screenshots side by side with the differences called out, and the output of `yarn build`, `yarn lint`, `yarn check-types` and the tests from both sides of the change. Where a difference was left in, such as a default ring width or border colour the team may prefer in its version 4 form, the description says so and shows the one-line compatibility rule that would restore the old look.

Before merging, a reviewer looks at three things: that the `@theme` block in the stylesheet matches the deleted config, key for key; that the browsers the product supports are ones version 4 targets, since it relies on modern CSS features and drops older Safari, Chrome and Firefox releases; and that nothing else in the organisation imports the deleted `tailwind.config.cjs`.

## Run it on every repository still on Tailwind CSS 3

This is a one-time job per repository, so the usual trigger is a script and not a schedule. For each repository that still depends on version 3, the script sends this body to `POST /o/{org}/sessions` with that repository in `resources` and a `request_id` that is a UUID v5 of the repository name, so running the script twice does not start a second upgrade. The runs are independent and a key starts as many at once as its `max_concurrent` allows; the rest are created queued and start as slots free.

If the key has a webhook, each finished run posts `run.completed` to it with the session URL, and the script's receiver can read each session for its pull request. A team that would sooner fold this into its regular dependency work can put the prompt in an automation with a weekly `schedule` trigger; once the repository is on version 4 the run finds nothing to do and ends with a short answer.

## Why run it on Rush?

A styling upgrade is judged by what the pages look like, and that needs a place to build the app and look at it. The sandbox has a browser beside the checkout, so the agent builds the site before and after, takes the same screenshots both times and attaches them. The commands it ran and their output, including a first start of the tool that fails, are kept in the transcript at `GET /o/{org}/sessions/{id}/messages`.

It is also an upgrade where the tool finishes in a minute and the tail takes the afternoon: a compiler to install, a lint plugin that no longer loads, a string renamed by mistake. A run works through that tail without holding a developer's machine or branch, and several repositories can be upgraded at once, each in its own sandbox.

## Frequently asked questions

### Should the app move from PostCSS to the Vite plugin?

Tailwind recommends `@tailwindcss/vite` for Vite projects, and the tool keeps PostCSS when it finds a PostCSS config, as it does here. Switching is a small change to `vite.config.ts` and the removal of `postcss.config.cjs`. The agent leaves it as a follow-up unless the prompt asks, so the upgrade and the integration change can be reviewed separately.

### What happens to tailwindcss-animate and the typography plugin?

The tool loads both from the stylesheet with `@plugin`, and the build passes with them. The agent checks the components that use their classes in the screenshots, since a plugin written for version 3 is the likeliest place for a silent difference.

### Can it keep the JavaScript config file?

Version 4 can still load one through an `@config` line in the stylesheet, and the tool falls back to that when a config is too dynamic to convert. Here it converts the file fully and deletes it. If other tooling reads your config, say so in the prompt and the agent keeps it and references it.

### Why do the tests not catch the broken variant?

They run through Vitest, which transpiles TypeScript without checking types, so `'outline-solid'` only fails in `tsc`. That is why the agent runs the build and the type check as well as the tests, and why the repository's CI workflow does the same.

## More Tailwind CSS jobs

- [Sort Tailwind CSS Classes with Prettier](https://getrush.ai/run/add-class-sorting/tailwind/)
- [Fix "It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin" after Tailwind CSS 4](https://getrush.ai/run/fix-tailwindcss-directly-as-postcss-plugin/tailwind/)

## The same job on other stacks

- [Upgrade a Next.js App to Tailwind CSS v4](https://getrush.ai/run/migrate-tailwind-v4/nextjs/)

## More jobs like this: Upgrade dependencies weekly

- [Migrate Tests From tape to the Node.js Test Runner (node:test)](https://getrush.ai/run/migrate-tape-to-node-test/tape/)
- [Migrate a Deno 1 App to Deno 2](https://getrush.ai/run/migrate-to-deno-2/deno/)
- [Migrate a React App to the Firebase Modular SDK](https://getrush.ai/run/migrate-to-firebase-modular-sdk/firebase/)

## Keep reading

- [How a Rush run works on your repository, from request to pull request](https://getrush.ai/cloud/)
- [Compare cloud agents, agent sandboxes and AI code review](https://getrush.ai/compare/)
- [Rush pricing: Free, Pro and Max](https://getrush.ai/pricing/)
