orion/docs/development/migration/tailwind-migration-plan.md

Tailwind CSS Migration Plan: v1.4/v2.2 → v4.0 (Standalone CLI)

Created: December 2024 Completed: December 2024 Status: COMPLETE Goal: Eliminate Node.js dependency, use Tailwind Standalone CLI

Migration Complete! All frontends now use Tailwind CSS v4 with the standalone CLI. See Tailwind CSS Build Guide for current documentation.

---

Current State

Two Tailwind Setups (Before Migration)

Component	Version	Source	Purpose
Base styles	2.2.19	CDN + local fallback	Core Tailwind utilities for all frontends
Custom overrides	1.4.6	npm build	Windmill Dashboard theme (admin/store)

Current Files (Before Migration)

package.json                           # tailwindcss: 1.4.6 (TO BE REMOVED)
package-lock.json                      # (TO BE REMOVED)
node_modules/                          # (TO BE REMOVED)
tailwind.config.js                     # v1.4 format config (TO BE UPDATED)
postcss.config.js                      # (TO BE REMOVED)
static/shared/css/tailwind.min.css     # CDN fallback v2.2.19 (TO BE REMOVED)
static/admin/css/tailwind.output.css   # Built overrides (TO BE REBUILT)
static/store/css/tailwind.output.css  # Built overrides (TO BE REBUILT)

Current Plugins (TO BE REPLACED)

{
  "@tailwindcss/custom-forms": "0.2.1",    // DEPRECATED - replaced by @tailwindcss/forms
  "tailwindcss-multi-theme": "1.0.3"       // DEPRECATED - native darkMode in v3+
}

---

Migration Goals

1. ✅ Eliminate Node.js dependency entirely
2. ✅ Use Tailwind Standalone CLI (single binary, no npm)
3. ✅ Upgrade to Tailwind v4.0 (latest)
4. ✅ Remove CDN dependency (all CSS built locally)
5. ✅ Update config to v4 format
6. ✅ Replace deprecated plugins with native features
7. ✅ Consolidate to single Tailwind version
8. ✅ Verify all frontends work correctly

---

Step-by-Step Migration

Phase 1: Install Tailwind Standalone CLI

The standalone CLI bundles Tailwind + Node.js runtime into a single binary.

# Download latest standalone CLI for Linux x64
curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64
chmod +x tailwindcss-linux-x64
sudo mv tailwindcss-linux-x64 /usr/local/bin/tailwindcss

# Verify installation
tailwindcss --version

For other platforms:

• macOS (Intel): tailwindcss-macos-x64
• macOS (Apple Silicon): tailwindcss-macos-arm64
• Windows: tailwindcss-windows-x64.exe
• Linux ARM: tailwindcss-linux-arm64

Phase 2: Update tailwind.config.js

Replace the entire config file with v4-compatible format:

// tailwind.config.js - Tailwind CSS v4.0 (Standalone CLI)
/** @type {import('tailwindcss').Config} */
module.exports = {
  // v4: 'content' replaces 'purge'
  content: [
    'app/templates/**/*.html',
    'static/**/*.js',
  ],

  // v4: safelist for dynamic classes (Alpine.js)
  safelist: [
    'bg-orange-600',
    'bg-green-600',
    'bg-red-600',
    'bg-blue-600',
    'bg-purple-600',
    'hover:bg-orange-700',
    'hover:bg-green-700',
    'hover:bg-red-700',
    'hover:bg-blue-700',
    'hover:bg-purple-700',
    // Status colors
    'text-green-600',
    'text-red-600',
    'text-yellow-600',
    'text-blue-600',
    'bg-green-100',
    'bg-red-100',
    'bg-yellow-100',
    'bg-blue-100',
  ],

  // v4: darkMode replaces tailwindcss-multi-theme
  darkMode: 'class',

  theme: {
    extend: {
      // Custom colors from Windmill Dashboard
      colors: {
        gray: {
          50: '#f9fafb',
          100: '#f4f5f7',
          200: '#e5e7eb',
          300: '#d5d6d7',
          400: '#9e9e9e',
          500: '#707275',
          600: '#4c4f52',
          700: '#24262d',
          800: '#1a1c23',
          900: '#121317',
        },
        purple: {
          50: '#f6f5ff',
          100: '#edebfe',
          200: '#dcd7fe',
          300: '#cabffd',
          400: '#ac94fa',
          500: '#9061f9',
          600: '#7e3af2',
          700: '#6c2bd9',
          800: '#5521b5',
          900: '#4a1d96',
        },
      },
      fontFamily: {
        sans: ['Inter', 'system-ui', '-apple-system', 'sans-serif'],
      },
      maxHeight: {
        'xl': '36rem',
      },
    },
  },

  plugins: [
    // Note: Standalone CLI includes @tailwindcss/forms by default in v4
    // No external plugins needed
  ],
}

Phase 3: Update CSS Source Files

Update static/admin/css/tailwind.css:

/* Tailwind CSS v4 directives */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Custom component classes */
@layer components {
  .form-input {
    @apply block w-full rounded-md border-gray-300 shadow-sm
           focus:border-purple-500 focus:ring-purple-500;
  }

  .form-select {
    @apply block w-full rounded-md border-gray-300 shadow-sm
           focus:border-purple-500 focus:ring-purple-500;
  }

  .form-checkbox {
    @apply rounded border-gray-300 text-purple-600
           focus:ring-purple-500;
  }

  .form-textarea {
    @apply block w-full rounded-md border-gray-300 shadow-sm
           focus:border-purple-500 focus:ring-purple-500;
  }
}

/* Dark mode base overrides */
@layer base {
  .dark body {
    @apply bg-gray-900 text-gray-200;
  }
}

Phase 4: Add Makefile Targets

Add these targets to your Makefile (replaces npm scripts):

# =============================================================================
# Tailwind CSS (Standalone CLI - No Node.js Required)
# =============================================================================

.PHONY: tailwind-install tailwind-dev tailwind-build tailwind-watch

# Install Tailwind standalone CLI
tailwind-install:
	@echo "Installing Tailwind CSS standalone CLI..."
	curl -sLO https://github.com/tailwindlabs/tailwindcss/releases/latest/download/tailwindcss-linux-x64
	chmod +x tailwindcss-linux-x64
	sudo mv tailwindcss-linux-x64 /usr/local/bin/tailwindcss
	@echo "Tailwind CLI installed: $$(tailwindcss --version)"

# Development build (includes all classes, faster)
tailwind-dev:
	@echo "Building Tailwind CSS (development)..."
	tailwindcss -i static/admin/css/tailwind.css -o static/admin/css/tailwind.output.css
	tailwindcss -i static/admin/css/tailwind.css -o static/store/css/tailwind.output.css
	@echo "CSS built successfully"

# Production build (purged and minified)
tailwind-build:
	@echo "Building Tailwind CSS (production)..."
	tailwindcss -i static/admin/css/tailwind.css -o static/admin/css/tailwind.output.css --minify
	tailwindcss -i static/admin/css/tailwind.css -o static/store/css/tailwind.output.css --minify
	@echo "CSS built and minified successfully"

# Watch mode for development
tailwind-watch:
	@echo "Watching for CSS changes..."
	tailwindcss -i static/admin/css/tailwind.css -o static/admin/css/tailwind.output.css --watch

Phase 5: Update Dark Mode Implementation

Old approach (tailwindcss-multi-theme):

<body class="theme-dark">
  <div class="bg-white dark:bg-gray-800">

New approach (Tailwind v4 native):

<html class="dark">
  <body>
    <div class="bg-white dark:bg-gray-800">

Files to update:

1. app/templates/admin/base.html - Add dark class to <html> element
2. app/templates/store/base.html - Add dark class to <html> element
3. static/admin/js/init-alpine.js - Update dark mode toggle logic
4. static/store/js/init-alpine.js - Update dark mode toggle logic

JavaScript update:

// Old
document.body.classList.toggle('theme-dark');

// New
document.documentElement.classList.toggle('dark');

Phase 6: Update Base Templates

Remove CDN loading, use only local built CSS:

<!-- OLD: CDN with fallback (REMOVE THIS) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css"
      onerror="this.onerror=null; this.href='{{ url_for('static', path='shared/css/tailwind.min.css') }}';">
<link rel="stylesheet" href="{{ url_for('static', path='admin/css/tailwind.output.css') }}" />

<!-- NEW: Local only (v4) -->
<link rel="stylesheet" href="{{ url_for('static', path='admin/css/tailwind.output.css') }}" />

Phase 7: Build and Test

# Build CSS
make tailwind-build

# Start development server
make dev

# Test all frontends:
# - http://localhost:8000/admin/dashboard
# - http://localhost:8000/store/{code}/dashboard
# - http://localhost:8000/ (shop)

Phase 8: Remove Node.js Artifacts

After successful testing, remove all Node.js related files:

# Remove Node.js files
rm -rf node_modules/
rm package.json
rm package-lock.json
rm postcss.config.js

# Remove unused CDN fallback
rm static/shared/css/tailwind.min.css

---

Verification Checklist

• Tailwind CLI installed and working (tailwindcss --version)
• Admin dashboard loads correctly
• Store dashboard loads correctly
• Shop frontend loads correctly
• Platform pages load correctly
• Dark mode toggle works
• All buttons have correct colors
• Forms display correctly (inputs, selects, checkboxes)
• Responsive design works (mobile/tablet/desktop)
• No console errors
• Production build works (make tailwind-build)
• node_modules removed
• package.json removed
• Each frontend has its own CSS source file
• Store theming (CSS variables) still works

---

Breaking Changes Reference

Class Name Changes (v2 → v4)

v2.x	v4.x	Notes
overflow-ellipsis	text-ellipsis	Renamed
flex-grow-0	grow-0	Shortened
flex-shrink-0	shrink-0	Shortened
decoration-clone	box-decoration-clone	Renamed

Plugin Changes

Old Plugin	New Approach	Notes
@tailwindcss/custom-forms	Built-in form styles	Native in v4
tailwindcss-multi-theme	darkMode: 'class'	Native support

Config Changes

v1.x/v2.x	v4.x
purge: [...]	content: [...]
variants: {...}	Removed (JIT generates all)
mode: 'jit'	Default (not needed)

---

Rollback Plan

If issues arise, the old setup can be restored:

# Reinstall Node dependencies
npm install

# Rebuild with old config
npm run build

---

Benefits of This Migration

Aspect	Before	After
Node.js required	Yes	No
Dependencies	~200MB node_modules	~50MB single binary
Build speed	Slower (npm + PostCSS)	Faster (standalone)
Tailwind versions	2 (v1.4 + v2.2)	1 (v4.0)
CSS loading	CDN + local	Local only
Maintenance	npm updates, security patches	Single binary updates

---

Resources

• Tailwind CSS Standalone CLI
• Tailwind CSS v4 Documentation
• Dark Mode in Tailwind
• Standalone CLI Releases