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:

{
  "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:

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

tailwindlabs / tailwindcss

Ensure clients pin the `tailwindcss` version #15011

Test plan