Tailwind CSS v4 in a WordPress Plugin: The Standalone CLI Guide

Tailwind CSS v4 introduces significant changes, notably removing the Command Line Interface (CLI) binary from its main npm package. While this streamlines integration with bundlers like Vite, it breaks the classic npx tailwindcss init setup essential for WordPress theme and plugin development.

This guide provides the robust, step-by-step method for installing and running Tailwind CSS v4 inside your WordPress plugin directory on a Linux environment, solving the common issues of the missing CLI and the “unknown utility class” error.

---

Phase 1: Environment Setup and CLI Acquisition

Since the standard npm install tailwindcss no longer provides the executable, we must download the official Standalone CLI binary.

Step 1: Initialize NPM and Install Dependencies

Navigate to your plugin’s root directory (where your main PHP file resides) and set up the Node environment.

# Navigate to your plugin root
cd /path/to/wp-content/plugins/your-plugin-name

# Initialize project
npm init -y

# Install PostCSS and Autoprefixer (still required)
npm install -D tailwindcss@4 postcss autoprefixer

Step 2: Acquire the Standalone CLI Binary

1. Create a local directory for the binary:

mkdir -p tailwind-cli
cd tailwind-cli

2. Download the Linux x64 Executable: (Verify the URL for the exact version if needed.)

curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/download/v4.1.16/tailwindcss-linux-x64

3. Rename and Grant Execute Permissions (Critical): This step prevents the Exec format error.

mv tailwindcss-linux-x64 tailwindcss
chmod +x tailwindcss
cd .. # Return to plugin root

Step 3: Create Core Directories

mkdir -p src dist

Phase 2: Configuration and Scripts

Since the init command is removed in v4, we manually create all necessary files.

Step 4: Configure package.json Build Scripts

Modify your package.json to include the build scripts, directing them to the local standalone binary.

package.json (Scripts Section):

"scripts": {
    "build:css": "./tailwind-cli/tailwindcss -i ./src/input.css -o ./dist/output.min.css --minify",
    "watch:css": "./tailwind-cli/tailwindcss -i ./src/input.css -o ./dist/output.min.css --watch"
  },

Step 5: Create Tailwind Config with Custom Colors

This configuration ensures your custom colors are defined and that Tailwind scans all necessary WordPress files for utility classes.

tailwind.config.js Content:

/** @type {import('tailwindcss').Config} */
module.exports = {
  // CRITICAL: Scans all PHP and JS files recursively from the plugin root
  content: [
    "./**/*.php",
    "./assets/js/**/*.js"
  ],
  darkMode: 'class',
  theme: {
    extend: {
      colors: {
        // Custom colors definition (e.g., bg-primary-light, text-primary-dark)
        primary: { light: '#4F46E5', dark: '#6366F1' }, 
        secondary: { light: '#14B8A6', dark: '#2DD4BF' },
        accent: { light: '#FBBF24', dark: '#F59E0B' }
      }
    }
  },
  plugins: [],
}

Step 6: Create Input CSS File

src/input.css Content:

@import 'tailwindcss';

/* Add any global or utility overrides here */

Phase 4: Execution and Deployment

Step 7: Start the Watcher

Execute the command from your plugin’s root directory:

npm run watch:css

(You may see the non-fatal watchman: not found warning, which can be safely ignored as the watcher uses a fallback mechanism.)

Step 8: Enqueue CSS in WordPress

In your plugin’s main PHP file, enqueue the generated, compiled CSS file:

function your_plugin_enqueue_styles() {
    // Path relative to your plugin root
    wp_enqueue_style( 
        'tailwind-styles', 
        plugin_dir_url( __FILE__ ) . 'dist/output.min.css', 
        array(), 
        '1.0.0' 
    );
}
add_action( 'wp_enqueue_scripts', 'your_plugin_enqueue_styles' );

Step 9: Final Production Build

Always run this command before deploying your plugin:

npm run build:css

The resulting dist/output.min.css file is the only asset your live server needs, ensuring a high-performance, zero-dependency Tailwind CSS v4 integration.