Setting Up Tailwind CSS with CLI in a React Project: A Step-by-Step Guide

on
Tailwind CSS is a utility-first CSS framework that allows you to rapidly build modern websites without ever leaving your HTML or JSX. However, with the release of Tailwind CSS v4 and beyond, there have been some important changes—particularly the separation of the CLI into a standalone package. This guide will walk you through setting up Tailwind CSS in a new project using the official CLI, while solving common issues like the infamous "could not determine executable to run" error.

Let’s dive in!

Step 1: Initialize a New Project

Before we begin installing Tailwind CSS, make sure you have Node.js and npm installed. You can check this using:

node -v
npm -v

Once confirmed, initialize a new project:

npm init -y

This creates a package.json file, which is required to manage your project’s dependencies.

Step 2: Install Tailwind CSS and Dependencies

With Tailwind CSS v4+, the CLI is no longer bundled within the core Tailwind package. To set things up, install the necessary packages using the command below:

npm install -D tailwindcss@latest postcss autoprefixer
npm install -D tailwindcss-cli

Here’s what each package does:

  • tailwindcss: The core Tailwind engine.

  • postcss & autoprefixer: Required for processing your CSS.

  • tailwindcss-cli: The official CLI tool for running Tailwind commands.

Step 3: Generate Config Files

After installing the packages, you'll need to initialize Tailwind and PostCSS configuration files. If you try running the usual command:

npx tailwindcss init -p

You might encounter the following error:

npm ERR! could not determine executable to run

This is because tailwindcss CLI is no longer accessible directly via npx in v4+. Instead, use:

npx tailwindcss-cli init -p

This will generate two files in your root directory:

  • tailwind.config.js

  • postcss.config.js

These are essential for customizing Tailwind and integrating it with your build tools.

Step 4: Create Your Project Structure

Assuming you are building a React app, create the following basic file structure:

navbar-theme-toggle/
├── public/
├── src/
│   ├── index.css
│   └── App.jsx
├── tailwind.config.js
├── postcss.config.js
└── package.json

Inside index.css, include the Tailwind directives:

@tailwind base;
@tailwind components;
@tailwind utilities;

Step 5: Configure Tailwind to Scan Your Files

Open your tailwind.config.js and configure the content array so Tailwind knows which files to scan for class names. For a React app, it might look like this:

/** @type {import('tailwindcss').Config} */
module.exports = {
  content: [
    "./src/**/*.{js,jsx,ts,tsx}"
  ],
  theme: {
    extend: {},
  },
  plugins: [],
}

This ensures Tailwind scans your React components inside the src directory.

Step 6: Add a Build Script

To compile your Tailwind CSS using the CLI, add a build script to your package.json:

"scripts": {
  "build:css": "tailwindcss-cli -i ./src/index.css -o ./public/output.css --watch"
}

Run it with:

npm run build:css

This tells Tailwind to take your input CSS file and output a compiled CSS file that includes all necessary utility classes.

Step 7: Link the Compiled CSS in HTML or React

If you're working with plain HTML:

<link rel="stylesheet" href="./public/output.css">

If you’re using React, import the compiled CSS in your index.js or App.jsx:

import '../public/output.css';

Troubleshooting Common Errors

❌ npx tailwindcss init -p doesn’t work

This happens in Tailwind v4+ because the CLI binary is no longer included. Fix it by:

npm install -D tailwindcss-cli
npx tailwindcss-cli init -p

❌ Cannot find module errors

Make sure you’ve installed everything with npm install and deleted node_modules and package-lock.json if anything’s corrupt.

rm -rf node_modules package-lock.json
npm install

Final Thoughts

Tailwind CSS continues to evolve and modernize front-end development, but keeping up with changes like the CLI separation in v4 can trip up even experienced developers. By explicitly installing the tailwindcss-cli, you’ll ensure your setup is compatible and ready for production.

Now you have a clean, modular setup for Tailwind CSS with PostCSS in a React environment — fully compatible with the latest versions and scalable for larger projects.

Happy coding!

Comments

Post a Comment