The Build Process: npm, Tailwind CSS v4's CSS-First Approach, the Watcher, and the Correct Deploy Sequence
The Build Process: npm, Tailwind CSS v4's CSS-First Approach, the Watcher, and the Correct Deploy Sequence
~9 Min. Lesezeit Zuletzt aktualisiert am August 9, 2026
For Tailwind classes in a template to turn into actual, visible CSS, Tailwind has to run once (or repeatedly during development) and produce a styles.css. This chapter covers the full build process - from local development with a watcher to the production deploy sequence that applies to every change in this project.
npm through the wrapper
Just like Composer, npm in the mironsoft project never runs directly - it always goes through bin/npm, which guarantees the Node version from the Docker container is used, not a possibly different local install.
bin/npm --prefix app/design/frontend/Mironsoft/default/web/tailwind installTailwind CSS v4: CSS-first instead of tailwind.config.js
One important difference from older Tailwind versions: starting with Tailwind CSS v4, configuration is no longer done primarily in a tailwind.config.js, but directly in CSS, via the @theme directive. This project consistently uses that CSS-first approach.
@import 'tailwindcss';
@theme {
--color-brand-dark: #1a2332;
--color-brand-slate: #475569;
--color-brand-accent: #0ea5e9;
--font-sans: 'Inter', sans-serif;
}These values are then available as regular utility classes, for example text-brand-dark or bg-brand-accent. Chapters 11 and 12 go into detail on your own design tokens - for now, it's enough to know that configuration lives in the CSS itself, not in a separate JavaScript file.
The watcher for development
During local development, CSS should rebuild automatically on every template or CSS change, without manually running a command. That's what the Tailwind watcher is for - in the mironsoft project it already runs automatically alongside bin/start:
bin/npm --prefix app/design/frontend/Mironsoft/default/web/tailwind run watchTipp: If CSS changes simply refuse to show up in the browser, the watcher is often the first suspect: check with bin/cli ps aux | grep tailwind whether the watcher process is even still running, and restart with bin/restart if needed.
The production build
For a deployment (or to test the real production CSS locally), a one-off, minified build runs instead of the watcher:
bin/npm --prefix app/design/frontend/Mironsoft/default/web/tailwind run buildThe correct deploy sequence
This is exactly where the most common beginner mistake happens: running only the Tailwind build isn't enough if Magento has already cached old static files. For this project, this order always applies, in exactly this order:
- Rebuild CSS -
bin/npm --prefix app/design/frontend/[Vendor]/[theme]/web/tailwind run build - Delete static files (IMPORTANT: always first, before deploying!) -
cd src && rm -rf var/view_preprocessed/* pub/static/frontend/* - Deploy static content -
bin/magento setup:static-content:deploy de_DE -t [Vendor]/[theme] -f - Flush cache -
bin/magento cache:flush
# 1. Rebuild CSS
bin/npm --prefix app/design/frontend/Mironsoft/default/web/tailwind run build
# 2. Delete static files (IMPORTANT: always first!)
cd src && rm -rf var/view_preprocessed/* pub/static/frontend/*
# 3. Deploy static content
bin/magento setup:static-content:deploy de_DE -t Mironsoft/default -f
# 4. Flush cache
bin/magento cache:flushAchtung: The order isn't a style preference, it's mandatory: if step 2 (deleting) is skipped, or run after step 3, Magento may deploy from the view_preprocessed cache and the old CSS classes stay active - even though the build itself looked fresh. This is the single most common cause of "my CSS change just isn't showing up".
Day-to-day development workflow
In daily work (with the watcher running locally), a simple bin/cache-clean is usually enough to make template or Layout XML changes visible - the full deploy sequence with a production build is typically only needed before a live deployment. Chapter 27 revisits this sequence in detail, including typical failure patterns.