Samir Boulahtit
da3d33a69c
- Add package.json with Tailwind dependencies - Add tailwind.config.js and postcss.config.js - Add source tailwind.css file - Generate tailwind.output.css for admin and vendor - Add Tailwind CSS documentation 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <noreply@anthropic.com>
362 lines
9.0 KiB
Markdown
362 lines
9.0 KiB
Markdown
# Tailwind CSS Migration Plan: v1.4/v2.2 → v3.4
|
|
|
|
**Created:** December 2024
|
|
**Status:** Planned
|
|
**Estimated Time:** 2-3 hours
|
|
|
|
---
|
|
|
|
## Current State
|
|
|
|
### Two Tailwind Setups
|
|
|
|
| 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/vendor) |
|
|
|
|
### Current Files
|
|
|
|
```
|
|
package.json # tailwindcss: 1.4.6
|
|
tailwind.config.js # v1.4 format config
|
|
static/shared/css/tailwind.min.css # CDN fallback (v2.2.19)
|
|
static/admin/css/tailwind.output.css # Built overrides
|
|
static/vendor/css/tailwind.output.css # Built overrides
|
|
```
|
|
|
|
### Current Plugins
|
|
|
|
```json
|
|
{
|
|
"@tailwindcss/custom-forms": "0.2.1", // DEPRECATED in v3
|
|
"tailwindcss-multi-theme": "1.0.3" // May not work with v3
|
|
}
|
|
```
|
|
|
|
---
|
|
|
|
## Migration Goals
|
|
|
|
1. Upgrade npm Tailwind to v3.4.x (latest stable)
|
|
2. Upgrade CDN Tailwind to v3.4.x
|
|
3. Update local fallback file
|
|
4. Replace deprecated plugins
|
|
5. Update config to v3 format
|
|
6. Verify all frontends work correctly
|
|
|
|
---
|
|
|
|
## Step-by-Step Migration
|
|
|
|
### Phase 1: Backup Current State
|
|
|
|
```bash
|
|
# Create backup branch
|
|
git checkout -b backup/tailwind-v1.4
|
|
git add -A
|
|
git commit -m "Backup before Tailwind v3 migration"
|
|
git checkout master
|
|
|
|
# Create migration branch
|
|
git checkout -b feat/tailwind-v3-upgrade
|
|
```
|
|
|
|
### Phase 2: Update npm Dependencies
|
|
|
|
```bash
|
|
# Remove old packages
|
|
npm uninstall tailwindcss tailwindcss-multi-theme @tailwindcss/custom-forms
|
|
|
|
# Install new packages
|
|
npm install -D tailwindcss@latest postcss@latest autoprefixer@latest
|
|
npm install -D @tailwindcss/forms @tailwindcss/typography
|
|
|
|
# Verify versions
|
|
npm list tailwindcss
|
|
```
|
|
|
|
**Expected versions:**
|
|
- tailwindcss: ^3.4.x
|
|
- postcss: ^8.4.x
|
|
- autoprefixer: ^10.4.x
|
|
|
|
### Phase 3: Update tailwind.config.js
|
|
|
|
Replace the entire config file:
|
|
|
|
```javascript
|
|
// tailwind.config.js - Tailwind CSS v3.4
|
|
/** @type {import('tailwindcss').Config} */
|
|
module.exports = {
|
|
// v3: 'content' replaces 'purge'
|
|
content: [
|
|
'app/templates/**/*.html',
|
|
'static/**/*.js',
|
|
],
|
|
|
|
// v3: safelist for dynamic classes
|
|
safelist: [
|
|
'bg-orange-600',
|
|
'bg-green-600',
|
|
'bg-red-600',
|
|
'hover:bg-orange-700',
|
|
'hover:bg-green-700',
|
|
'hover:bg-red-700',
|
|
// Add any other dynamic classes used in Alpine.js
|
|
],
|
|
|
|
// v3: darkMode replaces tailwindcss-multi-theme
|
|
darkMode: 'class', // or 'media' for OS preference
|
|
|
|
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',
|
|
},
|
|
// Add other custom colors as needed
|
|
},
|
|
fontFamily: {
|
|
sans: ['Inter', 'system-ui', '-apple-system', 'sans-serif'],
|
|
},
|
|
maxHeight: {
|
|
'xl': '36rem',
|
|
},
|
|
},
|
|
},
|
|
|
|
plugins: [
|
|
require('@tailwindcss/forms'), // Replaces @tailwindcss/custom-forms
|
|
require('@tailwindcss/typography'), // Optional: for prose content
|
|
],
|
|
}
|
|
```
|
|
|
|
### Phase 4: Update CSS Source File
|
|
|
|
Update `static/admin/css/tailwind.css`:
|
|
|
|
```css
|
|
/* Tailwind CSS v3 directives */
|
|
@tailwind base;
|
|
@tailwind components;
|
|
@tailwind utilities;
|
|
|
|
/* Custom component classes if needed */
|
|
@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;
|
|
}
|
|
}
|
|
```
|
|
|
|
### Phase 5: Update postcss.config.js
|
|
|
|
```javascript
|
|
// postcss.config.js
|
|
module.exports = {
|
|
plugins: {
|
|
tailwindcss: {},
|
|
autoprefixer: {},
|
|
...(process.env.NODE_ENV === 'production' ? { cssnano: {} } : {})
|
|
}
|
|
}
|
|
```
|
|
|
|
### Phase 6: Update package.json Scripts
|
|
|
|
```json
|
|
{
|
|
"scripts": {
|
|
"tailwind:admin": "npx tailwindcss -i static/admin/css/tailwind.css -o static/admin/css/tailwind.output.css",
|
|
"tailwind:vendor": "npx tailwindcss -i static/admin/css/tailwind.css -o static/vendor/css/tailwind.output.css",
|
|
"tailwind:watch": "npx tailwindcss -i static/admin/css/tailwind.css -o static/admin/css/tailwind.output.css --watch",
|
|
"build:admin": "npx tailwindcss -i static/admin/css/tailwind.css -o static/admin/css/tailwind.output.css --minify",
|
|
"build:vendor": "npx tailwindcss -i static/admin/css/tailwind.css -o static/vendor/css/tailwind.output.css --minify",
|
|
"build": "npm run build:admin && npm run build:vendor"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Phase 7: Update Dark Mode Implementation
|
|
|
|
**Old approach (tailwindcss-multi-theme):**
|
|
```html
|
|
<body class="theme-dark">
|
|
<div class="bg-white dark:bg-gray-800">
|
|
```
|
|
|
|
**New approach (Tailwind v3 native):**
|
|
```html
|
|
<body class="dark">
|
|
<div class="bg-white dark:bg-gray-800">
|
|
```
|
|
|
|
**Files to update:**
|
|
1. `app/templates/admin/base.html` - Change `theme-dark` to `dark`
|
|
2. `app/templates/vendor/base.html` - Change `theme-dark` to `dark`
|
|
3. `static/admin/js/init-alpine.js` - Update dark mode toggle logic
|
|
4. `static/vendor/js/init-alpine.js` - Update dark mode toggle logic
|
|
|
|
**JavaScript update example:**
|
|
```javascript
|
|
// Old
|
|
document.body.classList.toggle('theme-dark');
|
|
|
|
// New
|
|
document.documentElement.classList.toggle('dark');
|
|
```
|
|
|
|
### Phase 8: Update CDN and Local Fallback
|
|
|
|
**Option A: Use Tailwind Play CDN (development only)**
|
|
```html
|
|
<script src="https://cdn.tailwindcss.com"></script>
|
|
```
|
|
|
|
**Option B: Build and serve locally (recommended for production)**
|
|
|
|
Since Tailwind v3 doesn't have a pre-built CDN CSS file (it's JIT-only), the recommended approach is:
|
|
|
|
1. Remove CDN loading from templates
|
|
2. Load only the built `tailwind.output.css`
|
|
3. Include all needed utilities in your build
|
|
|
|
**Update base templates:**
|
|
```html
|
|
<!-- OLD: CDN with fallback -->
|
|
<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 (v3) -->
|
|
<link rel="stylesheet" href="{{ url_for('static', path='admin/css/tailwind.output.css') }}" />
|
|
```
|
|
|
|
### Phase 9: Build and Test
|
|
|
|
```bash
|
|
# Install dependencies
|
|
npm install
|
|
|
|
# Build CSS
|
|
npm run tailwind:admin
|
|
npm run tailwind:vendor
|
|
|
|
# Start development server
|
|
make dev
|
|
|
|
# Test all frontends:
|
|
# - http://localhost:8000/admin/dashboard
|
|
# - http://localhost:8000/vendor/{code}/dashboard
|
|
# - http://localhost:8000/ (shop)
|
|
```
|
|
|
|
### Phase 10: Verify Checklist
|
|
|
|
- [ ] Admin dashboard loads correctly
|
|
- [ ] Vendor dashboard loads correctly
|
|
- [ ] Shop frontend loads 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 (`npm run build`)
|
|
|
|
---
|
|
|
|
## Breaking Changes Reference
|
|
|
|
### Class Name Changes (v2 → v3)
|
|
|
|
| v2.x | v3.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 Plugin | Notes |
|
|
|------------|------------|-------|
|
|
| `@tailwindcss/custom-forms` | `@tailwindcss/forms` | Complete rewrite |
|
|
| `tailwindcss-multi-theme` | Built-in `darkMode: 'class'` | Native support |
|
|
|
|
### Config Changes
|
|
|
|
| v1.x/v2.x | v3.x |
|
|
|-----------|------|
|
|
| `purge: [...]` | `content: [...]` |
|
|
| `variants: {...}` | Removed (JIT generates all) |
|
|
| `mode: 'jit'` | Default (not needed) |
|
|
|
|
---
|
|
|
|
## Rollback Plan
|
|
|
|
If issues arise:
|
|
|
|
```bash
|
|
# Switch back to backup branch
|
|
git checkout backup/tailwind-v1.4
|
|
|
|
# Or reset changes
|
|
git checkout master
|
|
git reset --hard HEAD~1
|
|
```
|
|
|
|
---
|
|
|
|
## Post-Migration Tasks
|
|
|
|
1. Update `docs/frontend/tailwind-css.md` with v3 information
|
|
2. Update `docs/frontend/cdn-fallback-strategy.md` (or remove CDN references)
|
|
3. Remove `static/shared/css/tailwind.min.css` if no longer needed
|
|
4. Update any documentation referencing old class names
|
|
5. Consider adding Tailwind IntelliSense VS Code extension config
|
|
|
|
---
|
|
|
|
## Resources
|
|
|
|
- [Tailwind CSS v3 Upgrade Guide](https://tailwindcss.com/docs/upgrade-guide)
|
|
- [Tailwind CSS v3 Documentation](https://tailwindcss.com/docs)
|
|
- [@tailwindcss/forms Plugin](https://github.com/tailwindlabs/tailwindcss-forms)
|
|
- [Dark Mode in Tailwind v3](https://tailwindcss.com/docs/dark-mode)
|