How to use TailwindCSS with a simple plain PHP project
Integrating TailwindCSS into a vanilla PHP application doesn't require a framework, but it does require bypassing the opinionated defaults usually provided by tools like Laravel Mix or Vite. The core challenge is managing the build process without Composer or a dedicated task runner that automatically compiles your CSS. When you look at official documentation, the examples often assume a Node.js ecosystem where scripts handle everything behind the scenes. In a plain PHP environment, you need to manually orchestrate the download of dependencies and the compilation steps.
The most robust approach for a standalone project is to use PostCSS directly. This method treats your CSS file as a static asset that gets processed through Tailwind's utility engine before being served to the browser. You do not need to install Tailwind via npm globally; instead, you initialize a local build pipeline that runs on demand or integrates with your existing deployment workflow.
First, navigate to your project root and create a tailwind.config.js file. This file is essential for defining your utility classes, though for a simple list display, the default configuration usually suffices. You must also install the necessary Node.js dependencies. Even in a PHP-only world, you will need a local instance of Node and npm to manage these tools. Run the following commands in your terminal:
npm init -y
npm install tailwindcss postcss autoprefixer
npm install -D postcss-cli
The postcss-cli package is your build runner here. It allows you to chain PostCSS plugins together without needing a complex configuration file initially, though adding one later is trivial. Once dependencies are installed, create a postcss.config.js in the same directory:
module.exports = {
plugins: {
tailwindcss: {},
autoprefixer: {},
},
}
This configuration tells PostCSS to process your CSS files using both Tailwind and Autoprefixer. Autoprefixer is critical because it adds vendor prefixes (like -webkit-) automatically, ensuring your styles work across different browsers without manual effort.
Now, update your src/css/style.css. Instead of writing raw utility classes directly in HTML, you compile them here. This keeps your markup clean and allows for centralized design management. Add the Tailwind directives at the top:
@tailwind base;
@tailwind components;
@tailwind utilities;
You can now populate this file with your custom styles or let it remain empty if you rely entirely on utility classes in your HTML. However, for a project fetching data from a database to print as a list, having a compiled stylesheet often improves performance by reducing the number of CSS requests compared to loading every utility inline.
To compile the CSS, run:
npx postcss src/css/style.css -o public/styles.css
You will need to create a public directory in your project root if it doesn't exist. This directory is standard for PHP projects and serves as the web root where assets are accessible via URL. The command above reads your source file, processes it through Tailwind, and outputs a single optimized CSS file to public.
In your index.php (or any included layout files like header.php), link the compiled stylesheet in the <head> section:
<link rel="stylesheet" href="/styles.css">
This setup decouples the build process from the PHP execution. You don't need to run a server-side script to compile CSS every time you refresh the page; you only run the postcss command when your design changes. This is often preferable in plain PHP environments where you want maximum control over when assets are updated, avoiding potential performance hits from re-compiling on every request.
If you prefer not to use a separate build step and want to keep everything strictly within the PHP file structure, you can consider using an CDN link for Tailwind. This approach bypasses the need for Node.js entirely but comes with significant trade-offs. You lose the ability to purge unused CSS, which can lead to larger file sizes as your page grows. Furthermore, you cannot customize configuration options like color palettes or font families without modifying the CDN URL parameters, which becomes unwieldy quickly. For a project that might evolve beyond a simple list display, compiling locally is the more scalable and maintainable solution.
Should you eventually decide to move towards a framework or want to automate the build process further, exploring solutions like LaravelCompany offers resources on how similar architectures handle asset compilation in larger ecosystems. However, for now, this manual PostCSS workflow provides a clean, dependency-managed integration that respects the simplicity of your current PHP structure.
