All jobs

Fix "It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin" after Tailwind CSS 4

Yes. An agent moves the PostCSS setup to @tailwindcss/postcss and the v4 import, rebuilds the stylesheet, and checks every class the templates use survived first.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

Tailwind CSS 4 split its PostCSS plugin out of the main package. A postcss.config.js that still lists tailwindcss as a plugin stops at the first build with Error: It looks like you're trying to use tailwindcssdirectly as a PostCSS plugin. The PostCSS plugin has moved to a separate package, so to continue using Tailwind CSS with PostCSS you'll need to install@tailwindcss/postcss and update your PostCSS configuration. The message is clear about the first step and silent about the rest: the @tailwind base; @tailwind components; @tailwind utilities; directives became one @import "tailwindcss";, the tailwindcss CLI moved to @tailwindcss/cli, autoprefixer is built in, and content is detected automatically instead of through a purge or content list. A ^2.2 or ^3.x range never pulls 4 by itself; the break arrives with a deliberate bump or a dependency update tool that opens one.

jorgelbg/dissect-tester, a Go service with a small UI for testing Filebeat dissect patterns, keeps its styling in exactly that shape. package.json has only devDependencies: tailwindcss ^2.2, postcss 8.2, postcss-cli ^8.2 and a file watcher, with the script build:tailwind running postcss ./static/css/master.css -o ./static/dist/tailwind.css. postcss.config.js requires tailwindcss and autoprefixer as plugins, though autoprefixer is not a declared dependency and only resolves because Tailwind 2 pulled it in; package-lock.json holds tailwindcss 2.2.16, postcss 8.2.15 and autoprefixer 10.3.7. static/css/master.css is the three @tailwind directives, there is no tailwind.config.js, and the committed static/dist/tailwind.css is a 4,005,585-byte full build because Tailwind 2 with no config purges nothing. The one template, templates/index.html, links that file and uses classes such as bg-gradient-to-r from-green-400 to-blue-500 hover:from-pink-500, animate-pulse and container mx-auto. The Dockerfile and Makefile build the Go binary and copy static/ as it is; nothing runs npm in CI.

The agent reproduces the error on the current release by bumping tailwindcss in a clean install and running the project's own build:tailwind script, which exits 1 with the message above. Then it makes the four changes the message does not spell out: it adds @tailwindcss/postcss, rewrites postcss.config.js to that single plugin, replaces the three directives in master.css with @import "tailwindcss";, and drops autoprefixer from the config, since v4 handles prefixes itself and the package was never declared. It runs the build again, now successfully, and reads the output.

The size of that output is where it checks its work. With v4's automatic content detection the stylesheet shrinks from four megabytes to a few kilobytes, so a class that detection missed would simply vanish from the page without any error. The agent extracts every class name from templates/index.html, greps the new static/dist/tailwind.css for each, and reports any that are absent along with the v4 rename that covers them; in this repository .bg-gradient-to-r, .from-green-400, .animate-pulse and .container are all present in the rebuilt file. It regenerates package-lock.json, commits the rebuilt stylesheet as the repository does, and leaves the Go build, the Dockerfile and the template untouched.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Our CSS build fails with Error: It looks like you're trying to use `tailwindcss` directly as a PostCSS plugin after a Tailwind CSS upgrade. Read package.json, the lockfile, the PostCSS configuration, any tailwind.config file and the CSS entry file, and report the Tailwind, PostCSS and autoprefixer versions before the upgrade and the one a clean install resolves to now. Reproduce the failure by running the project's own CSS build script and keep its output. Then complete the move to Tailwind CSS 4: install @tailwindcss/postcss and make it the PostCSS plugin, replace the @tailwind directives in the entry file with the v4 import, remove autoprefixer from the configuration since v4 includes it, and translate any theme or content settings from a tailwind.config file into the v4 CSS form, reporting each one. Run the build again and include the output. Then prove nothing was lost: extract every class name from the templates or components the stylesheet serves, check each against the rebuilt CSS, and list any class that is missing together with the v4 rename or the explicit @source directive that restores it. Regenerate the lockfile with the same package manager the repository uses. If the compiled stylesheet is committed, rebuild and commit it. Do not change templates, markup or the application's own build. Open a pull request that lists each changed file, the versions before and after, the size of the stylesheet before and after, and what could not be verified without a browser.",
  "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 that touches package.json, the lockfile, postcss.config.js, the CSS entry file and, where the repository commits it, the compiled stylesheet. The description opens with the failing build output from the project's own script, then the version table before and after, and then the second build output and the stylesheet size on each side, which for a project that never purged is the difference between megabytes and kilobytes.

Below that is the class check: every class name found in the templates, each marked present in the rebuilt CSS or missing with the change that restores it. That table is what a reviewer reads, because a build that exits 0 says nothing about a utility that automatic detection skipped. The diff itself is four short files plus the rebuilt stylesheet.

What the run cannot prove is listed last. No browser rendered the page, so a visual pass over the UI, and in particular any gradient, animation or responsive class whose v4 output differs from v2 or v3, is for the reviewer before merging.

Run it on every dependency update pull request

A major Tailwind bump arrives as a dependency update pull request that fails the CSS build, or, in a repository with no CI for npm like the example, as a broken stylesheet after someone runs the build locally. Create an automation on the repository's Project with the prompt above and a github trigger on pull_request.opened and pull_request.synchronize, with a prompt that tells the agent to stop with a one-line answer when the pull request does not touch package.json. The pull request's title and description follow the prompt as event text, so the agent sees which package moved before it clones. A pull request a bot opens fires no github trigger, so a Dependabot or Renovate bump is caught by the schedule trigger below instead.

For a repository where nothing builds the CSS in CI, a schedule trigger with a monthly cron does the job a pipeline would: the agent installs, runs the build script and the class check, and opens a pull request only when the build fails or a class is missing.

The use case this job follows, with its automation and trigger: Fix a bug from an alert.

Why run it on Rush?

The error names one package and the migration needs four changes and a check nobody does by hand: that every class in the markup still has a rule in the new, much smaller stylesheet. The agent runs the real build script before and after in a sandbox, keeps both outputs, and greps the rebuilt CSS for every class it finds in the templates, so the pull request shows the build passing and the class table instead of a developer's recollection that the page still looked right.

It also keeps a lockfile and a committed build artifact honest. Regenerating package-lock.json and the compiled stylesheet in a clean environment means the pull request carries exactly what a fresh checkout produces, and the size line in the description makes the effect of automatic content detection visible to a reviewer who never ran Tailwind 4.

Frequently asked questions

Can I stay on Tailwind 3 instead?

Yes, by keeping the range below 4; a ^2.2 or ^3.x range never resolves to 4 on its own. The run shows the error only after a deliberate bump. Staying means handling the same move later, when a dependency update tool opens it again.

Why is the new stylesheet so much smaller?

Tailwind 4 detects content automatically and emits only the utilities it finds in your files, where a Tailwind 2 project with no config purged nothing and shipped every utility. The agent treats the size drop as a reason to check every class in the markup against the new CSS, and lists the result.

What if a class is missing from the rebuilt CSS?

The pull request names it with the fix: a v4 rename for utilities whose name changed, or an explicit @source directive in the entry file for templates that automatic detection did not scan. In the example repository every class in the template was present.

Do I still need autoprefixer?

No. Tailwind 4 adds vendor prefixes itself, so the agent removes it from the PostCSS configuration. In the example it was never a declared dependency and only resolved as a leftover of Tailwind 2, which the pull request points out.

Where did the tailwindcss command go?

The CLI moved to the @tailwindcss/cli package in v4, which is why npx tailwindcss prints that npm could not determine an executable. A project that builds through PostCSS, like the example, does not need it; one that calls the CLI directly adds that package instead.

More Tailwind CSS jobs

More jobs like this: Fix a bug from an alert

Keep reading