517 lines
7.7 KiB
Markdown
517 lines
7.7 KiB
Markdown
# Complete Breaking Changes List
|
|
|
|
## Configuration System
|
|
|
|
### JavaScript → CSS Configuration
|
|
|
|
**Breaking:** No more `tailwind.config.js` file.
|
|
|
|
**v3:**
|
|
|
|
```javascript
|
|
module.exports = {
|
|
theme: {
|
|
extend: {
|
|
colors: { brand: '#3b82f6' },
|
|
},
|
|
},
|
|
};
|
|
```
|
|
|
|
**v4:**
|
|
|
|
```css
|
|
@theme {
|
|
--color-brand: oklch(0.65 0.25 270);
|
|
}
|
|
```
|
|
|
|
**Impact:** All theme customization moves to CSS.
|
|
|
|
### Content Detection
|
|
|
|
**Breaking:** No manual content array needed.
|
|
|
|
**v3:**
|
|
|
|
```javascript
|
|
content: ['./src/**/*.{html,js}']
|
|
```
|
|
|
|
**v4:**
|
|
|
|
Automatic detection. Manual control via `@source` if needed.
|
|
|
|
**Impact:** Simplified setup, but less explicit control.
|
|
|
|
## Import Directives
|
|
|
|
### @tailwind → @import
|
|
|
|
**Breaking:** Different import syntax.
|
|
|
|
**v3:**
|
|
|
|
```css
|
|
@tailwind base;
|
|
@tailwind components;
|
|
@tailwind utilities;
|
|
```
|
|
|
|
**v4:**
|
|
|
|
```css
|
|
@import 'tailwindcss';
|
|
```
|
|
|
|
**Impact:** All templates need updating.
|
|
|
|
## Utility Class Changes
|
|
|
|
### Opacity Modifiers Removed
|
|
|
|
**Breaking:** Separate opacity utilities removed.
|
|
|
|
**v3:**
|
|
|
|
```html
|
|
<div class="bg-black bg-opacity-50"></div>
|
|
<div class="text-gray-900 text-opacity-75"></div>
|
|
<div class="border-blue-500 border-opacity-60"></div>
|
|
<div class="ring-blue-500 ring-opacity-30"></div>
|
|
```
|
|
|
|
**v4:**
|
|
|
|
```html
|
|
<div class="bg-black/50"></div>
|
|
<div class="text-gray-900/75"></div>
|
|
<div class="border-blue-500/60"></div>
|
|
<div class="ring-blue-500/30"></div>
|
|
```
|
|
|
|
**Impact:** Search and replace needed across entire codebase.
|
|
|
|
**Automated fix:**
|
|
|
|
```bash
|
|
find . -name "*.html" -o -name "*.jsx" -o -name "*.tsx" | xargs sed -i '' 's/bg-\([a-z-]*\) bg-opacity-\([0-9]*\)/bg-\1\/\2/g'
|
|
```
|
|
|
|
### Flex Utility Renames
|
|
|
|
**Breaking:** Utility names changed.
|
|
|
|
**v3:**
|
|
|
|
```html
|
|
<div class="flex-shrink-0"></div>
|
|
<div class="flex-shrink"></div>
|
|
<div class="flex-grow-0"></div>
|
|
<div class="flex-grow"></div>
|
|
```
|
|
|
|
**v4:**
|
|
|
|
```html
|
|
<div class="shrink-0"></div>
|
|
<div class="shrink"></div>
|
|
<div class="grow-0"></div>
|
|
<div class="grow"></div>
|
|
```
|
|
|
|
**Impact:** All flex utilities need renaming.
|
|
|
|
### Shadow Utility Rename
|
|
|
|
**Breaking:** Smallest shadow renamed.
|
|
|
|
**v3:**
|
|
|
|
```html
|
|
<div class="shadow-sm"></div>
|
|
```
|
|
|
|
**v4:**
|
|
|
|
```html
|
|
<div class="shadow-xs"></div>
|
|
```
|
|
|
|
**Impact:** Update all uses of `shadow-sm`.
|
|
|
|
### Ring Default Width
|
|
|
|
**Breaking:** Default ring width changed.
|
|
|
|
**v3:**
|
|
|
|
```html
|
|
<input class="ring" />
|
|
```
|
|
|
|
Ring width: 3px
|
|
|
|
**v4:**
|
|
|
|
```html
|
|
<input class="ring" />
|
|
```
|
|
|
|
Ring width: 1px
|
|
|
|
**Fix for v3 behavior:**
|
|
|
|
```html
|
|
<input class="ring-3" />
|
|
```
|
|
|
|
**Impact:** All bare `ring` utilities render thinner.
|
|
|
|
## Color System
|
|
|
|
### Default Border Color
|
|
|
|
**Breaking:** Border color changed from gray to currentColor.
|
|
|
|
**v3:**
|
|
|
|
```html
|
|
<div class="border"></div>
|
|
```
|
|
|
|
Border color: gray-200
|
|
|
|
**v4:**
|
|
|
|
```html
|
|
<div class="border"></div>
|
|
```
|
|
|
|
Border color: currentColor (inherits text color)
|
|
|
|
**Fix for v3 behavior:**
|
|
|
|
```html
|
|
<div class="border border-gray-200"></div>
|
|
```
|
|
|
|
**Impact:** Borders may appear different colors.
|
|
|
|
### Default Ring Color
|
|
|
|
**Breaking:** Ring color changed from blue to currentColor.
|
|
|
|
**v3:**
|
|
|
|
```html
|
|
<input class="ring" />
|
|
```
|
|
|
|
Ring color: blue-500
|
|
|
|
**v4:**
|
|
|
|
```html
|
|
<input class="ring" />
|
|
```
|
|
|
|
Ring color: currentColor
|
|
|
|
**Fix for v3 behavior:**
|
|
|
|
```html
|
|
<input class="ring ring-blue-500" />
|
|
```
|
|
|
|
**Impact:** Rings inherit text color.
|
|
|
|
### OkLCh Color Space
|
|
|
|
**Breaking:** Color values use OkLCh instead of RGB.
|
|
|
|
**v3:**
|
|
|
|
```javascript
|
|
colors: {
|
|
brand: '#3b82f6',
|
|
}
|
|
```
|
|
|
|
**v4:**
|
|
|
|
```css
|
|
@theme {
|
|
--color-brand: oklch(0.65 0.25 270);
|
|
}
|
|
```
|
|
|
|
**Impact:** Custom colors need conversion. Colors may look slightly different (more vivid on modern displays).
|
|
|
|
## PostCSS Changes
|
|
|
|
### Plugin Name
|
|
|
|
**Breaking:** Different PostCSS plugin.
|
|
|
|
**v3:**
|
|
|
|
```javascript
|
|
plugins: {
|
|
'tailwindcss': {},
|
|
'autoprefixer': {},
|
|
}
|
|
```
|
|
|
|
**v4:**
|
|
|
|
```javascript
|
|
plugins: {
|
|
'@tailwindcss/postcss': {},
|
|
}
|
|
```
|
|
|
|
**Impact:** PostCSS config needs updating. Remove `autoprefixer` and `postcss-import` (no longer needed).
|
|
|
|
## Preflight Changes
|
|
|
|
### Placeholder Color
|
|
|
|
**Breaking:** Placeholder text color changed.
|
|
|
|
**v3:**
|
|
|
|
```css
|
|
::placeholder {
|
|
color: theme('colors.gray.400');
|
|
}
|
|
```
|
|
|
|
**v4:**
|
|
|
|
```css
|
|
::placeholder {
|
|
color: currentColor;
|
|
opacity: 0.5;
|
|
}
|
|
```
|
|
|
|
**Impact:** Placeholders inherit text color at 50% opacity.
|
|
|
|
**Fix for v3 behavior:**
|
|
|
|
```css
|
|
@layer base {
|
|
::placeholder {
|
|
color: theme('colors.gray.400');
|
|
opacity: 1;
|
|
}
|
|
}
|
|
```
|
|
|
|
### Button Cursor
|
|
|
|
**Breaking:** Button cursor changed.
|
|
|
|
**v3:**
|
|
|
|
```css
|
|
button {
|
|
cursor: pointer;
|
|
}
|
|
```
|
|
|
|
**v4:**
|
|
|
|
```css
|
|
button {
|
|
cursor: default;
|
|
}
|
|
```
|
|
|
|
**Impact:** Buttons no longer show pointer cursor by default.
|
|
|
|
**Fix for v3 behavior:**
|
|
|
|
```css
|
|
@layer base {
|
|
button {
|
|
cursor: pointer;
|
|
}
|
|
}
|
|
```
|
|
|
|
Or add explicit classes:
|
|
|
|
```html
|
|
<button class="cursor-pointer">Click me</button>
|
|
```
|
|
|
|
## Arbitrary Values
|
|
|
|
### Space Handling
|
|
|
|
**Breaking:** Spaces in arbitrary values use underscores.
|
|
|
|
**v3:**
|
|
|
|
```html
|
|
<div class="grid-cols-[1fr,500px,2fr]"></div>
|
|
```
|
|
|
|
**v4:**
|
|
|
|
```html
|
|
<div class="grid-cols-[1fr_500px_2fr]"></div>
|
|
```
|
|
|
|
**Impact:** All arbitrary values with commas need updating.
|
|
|
|
## Browser Support
|
|
|
|
### Minimum Versions
|
|
|
|
**Breaking:** Dropped support for older browsers.
|
|
|
|
**v3:**
|
|
|
|
- IE 11+
|
|
- Safari 10+
|
|
- Chrome 60+
|
|
|
|
**v4:**
|
|
|
|
- Safari 16.4+
|
|
- Chrome 111+
|
|
- Firefox 128+
|
|
|
|
**Impact:** Projects requiring older browser support cannot upgrade.
|
|
|
|
## CSS Preprocessors
|
|
|
|
### No Sass/Less/Stylus Support
|
|
|
|
**Breaking:** Incompatible with CSS preprocessors.
|
|
|
|
**v3:**
|
|
|
|
Can use with Sass, Less, Stylus
|
|
|
|
**v4:**
|
|
|
|
Cannot use CSS preprocessors (Tailwind functions as preprocessing layer)
|
|
|
|
**Impact:** Remove CSS preprocessors from build pipeline.
|
|
|
|
## Plugin System
|
|
|
|
### Plugin API Changes
|
|
|
|
**Breaking:** Plugin API completely rewritten.
|
|
|
|
**v3 plugin:**
|
|
|
|
```javascript
|
|
const plugin = require('tailwindcss/plugin');
|
|
|
|
module.exports = plugin(function ({ addUtilities, theme }) {
|
|
addUtilities({
|
|
'.content-auto': {
|
|
'content-visibility': 'auto',
|
|
},
|
|
});
|
|
});
|
|
```
|
|
|
|
**v4 equivalent:**
|
|
|
|
```css
|
|
@utility content-auto {
|
|
content-visibility: auto;
|
|
}
|
|
```
|
|
|
|
**Impact:** All custom plugins need manual rewrite.
|
|
|
|
## @apply Restrictions
|
|
|
|
### Limited @apply Support
|
|
|
|
**Breaking:** @apply only works for small subset of utilities.
|
|
|
|
**v3:**
|
|
|
|
```css
|
|
.btn {
|
|
@apply px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700;
|
|
}
|
|
```
|
|
|
|
**v4:**
|
|
|
|
@apply has limited support. Use @utility instead:
|
|
|
|
```css
|
|
@utility btn {
|
|
padding: var(--spacing-2) var(--spacing-4);
|
|
background: var(--color-blue-600);
|
|
color: var(--color-white);
|
|
border-radius: var(--radius-md);
|
|
}
|
|
```
|
|
|
|
**Impact:** Many @apply patterns need refactoring.
|
|
|
|
## Mobile Hover Behavior
|
|
|
|
### Hover on Touch Devices
|
|
|
|
**Breaking:** Hover styles don't apply on touch devices.
|
|
|
|
**v3:**
|
|
|
|
Hover styles triggered on tap
|
|
|
|
**v4:**
|
|
|
|
Hover styles only on devices supporting hover
|
|
|
|
**Impact:** Touch devices won't show hover states (improves UX).
|
|
|
|
## Container Plugin
|
|
|
|
### Built-in Container Queries
|
|
|
|
**Breaking:** Container queries plugin no longer needed.
|
|
|
|
**v3:**
|
|
|
|
```javascript
|
|
plugins: [require('@tailwindcss/container-queries')]
|
|
```
|
|
|
|
**v4:**
|
|
|
|
Built-in. No plugin needed.
|
|
|
|
**Impact:** Remove plugin dependency. Syntax remains same.
|
|
|
|
## Summary Table
|
|
|
|
| Change | v3 | v4 | Impact |
|
|
|--------|----|----|--------|
|
|
| Config | tailwind.config.js | @theme | High |
|
|
| Import | @tailwind | @import | High |
|
|
| Opacity | bg-opacity-50 | bg-{color}/50 | High |
|
|
| Flex | flex-shrink | shrink | Medium |
|
|
| Shadow | shadow-sm | shadow-xs | Low |
|
|
| Ring width | 3px | 1px | Medium |
|
|
| Border color | gray-200 | currentColor | Medium |
|
|
| Color space | RGB | OkLCh | Medium |
|
|
| PostCSS | tailwindcss | @tailwindcss/postcss | High |
|
|
| Placeholder | gray-400 | currentColor/50 | Low |
|
|
| Button cursor | pointer | default | Low |
|
|
| Browsers | IE 11+ | Safari 16.4+ | High |
|
|
| Preprocessors | Supported | Not supported | High |
|
|
| Plugins | JS API | CSS @utility | High |
|