feat: docs.pivoine.art
This commit is contained in:
266
Projects/docs.pivoine.art/MIGRATION.md
Normal file
266
Projects/docs.pivoine.art/MIGRATION.md
Normal file
@@ -0,0 +1,266 @@
|
||||
# Migration Guide: Next.js 15 & Tailwind CSS 4
|
||||
|
||||
This guide documents the migration from Next.js 14 to 15 and Tailwind CSS 3 to 4.
|
||||
|
||||
## 🚀 What's New
|
||||
|
||||
### Next.js 15
|
||||
|
||||
#### Major Features
|
||||
- **React 19 Support**: Now using the latest React version with improved performance
|
||||
- **Turbopack Stable**: Lightning-fast bundler now stable and used by default in dev mode
|
||||
- **Improved Caching**: Better caching strategies for faster builds
|
||||
- **Enhanced Performance**: Overall speed improvements in both dev and production
|
||||
|
||||
#### Breaking Changes
|
||||
- **Minimum Node.js**: Now requires Node.js 18.18.0 or higher (was 18.17.0)
|
||||
- **React 19**: Some React APIs have changed, though this project is not affected
|
||||
- **ESLint**: Now uses flat config format (ESLint 9)
|
||||
|
||||
### Tailwind CSS 4
|
||||
|
||||
#### Major Features
|
||||
- **CSS-First Configuration**: Configure via `@theme` in CSS instead of JavaScript
|
||||
- **Faster Builds**: Significantly faster compilation times
|
||||
- **Smaller Bundles**: More efficient output with smaller CSS files
|
||||
- **Native CSS Variables**: Better integration with modern CSS
|
||||
- **Simpler Setup**: Less configuration needed
|
||||
|
||||
#### Breaking Changes
|
||||
- **No More `@tailwind` directives**: Use `@import "tailwindcss"` instead
|
||||
- **Configuration in CSS**: Use `@theme` blocks in CSS files for customization
|
||||
- **Minimal JS Config**: `tailwind.config.js` only needs content paths now
|
||||
- **PostCSS Simplified**: Only need Tailwind plugin in PostCSS config
|
||||
|
||||
## 📦 Updated Dependencies
|
||||
|
||||
### Before (Next.js 14 / Tailwind 3)
|
||||
```json
|
||||
{
|
||||
"next": "^14.2.0",
|
||||
"react": "^18.3.0",
|
||||
"react-dom": "^18.3.0",
|
||||
"tailwindcss": "^3.4.1",
|
||||
"autoprefixer": "^10.4.18"
|
||||
}
|
||||
```
|
||||
|
||||
### After (Next.js 15 / Tailwind 4)
|
||||
```json
|
||||
{
|
||||
"next": "^15.0.3",
|
||||
"react": "^19.0.0",
|
||||
"react-dom": "^19.0.0",
|
||||
"tailwindcss": "^4.0.0"
|
||||
}
|
||||
```
|
||||
|
||||
## 🔄 File Changes
|
||||
|
||||
### 1. `package.json`
|
||||
- Updated Next.js to v15
|
||||
- Updated React to v19
|
||||
- Updated Tailwind CSS to v4
|
||||
- Removed autoprefixer (now built into Tailwind 4)
|
||||
- Added `--turbopack` flag to dev script
|
||||
- Updated packageManager to pnpm@9.0.0
|
||||
|
||||
### 2. `app/globals.css`
|
||||
|
||||
**Before:**
|
||||
```css
|
||||
@tailwind base;
|
||||
@tailwind components;
|
||||
@tailwind utilities;
|
||||
```
|
||||
|
||||
**After:**
|
||||
```css
|
||||
@import "tailwindcss";
|
||||
|
||||
@theme {
|
||||
/* Custom configuration here */
|
||||
--animate-pulse: pulse 4s cubic-bezier(0.4, 0, 0.6, 1) infinite;
|
||||
}
|
||||
```
|
||||
|
||||
### 3. `tailwind.config.js`
|
||||
|
||||
**Before:**
|
||||
```js
|
||||
module.exports = {
|
||||
content: ['./app/**/*.{js,ts,jsx,tsx,mdx}'],
|
||||
theme: {
|
||||
extend: {
|
||||
animation: { /* ... */ },
|
||||
backgroundImage: { /* ... */ },
|
||||
},
|
||||
},
|
||||
plugins: [],
|
||||
}
|
||||
```
|
||||
|
||||
**After:**
|
||||
```js
|
||||
export default {
|
||||
content: ['./app/**/*.{js,ts,jsx,tsx,mdx}'],
|
||||
// Theme configuration moved to CSS
|
||||
}
|
||||
```
|
||||
|
||||
### 4. `postcss.config.js`
|
||||
|
||||
**Before:**
|
||||
```js
|
||||
module.exports = {
|
||||
plugins: {
|
||||
tailwindcss: {},
|
||||
autoprefixer: {},
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
**After:**
|
||||
```js
|
||||
export default {
|
||||
plugins: {
|
||||
tailwindcss: {},
|
||||
// autoprefixer removed (built into Tailwind 4)
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
### 5. `next.config.js`
|
||||
|
||||
**Before:**
|
||||
```js
|
||||
const nextConfig = {
|
||||
reactStrictMode: true,
|
||||
swcMinify: true,
|
||||
// ...
|
||||
}
|
||||
|
||||
module.exports = nextConfig
|
||||
```
|
||||
|
||||
**After:**
|
||||
```js
|
||||
const nextConfig = {
|
||||
reactStrictMode: true,
|
||||
// swcMinify removed (default in Next.js 15)
|
||||
// Turbopack is now stable and default
|
||||
// ...
|
||||
}
|
||||
|
||||
export default nextConfig
|
||||
```
|
||||
|
||||
### 6. ESLint Configuration
|
||||
|
||||
**Before:** `.eslintrc.json`
|
||||
```json
|
||||
{
|
||||
"extends": ["next/core-web-vitals", "next/typescript"]
|
||||
}
|
||||
```
|
||||
|
||||
**After:** `eslint.config.mjs`
|
||||
```js
|
||||
import { FlatCompat } from "@eslint/eslintrc";
|
||||
|
||||
const compat = new FlatCompat({
|
||||
baseDirectory: __dirname,
|
||||
});
|
||||
|
||||
export default [
|
||||
...compat.extends("next/core-web-vitals", "next/typescript"),
|
||||
];
|
||||
```
|
||||
|
||||
## ✅ Migration Checklist
|
||||
|
||||
If you're migrating an existing project:
|
||||
|
||||
- [ ] Update Node.js to 18.18.0 or higher
|
||||
- [ ] Update package.json dependencies
|
||||
- [ ] Run `pnpm install` to install new versions
|
||||
- [ ] Update `app/globals.css` to use `@import "tailwindcss"`
|
||||
- [ ] Move Tailwind theme config from JS to CSS using `@theme`
|
||||
- [ ] Simplify `tailwind.config.js` (remove theme extensions)
|
||||
- [ ] Update `postcss.config.js` to remove autoprefixer
|
||||
- [ ] Update `next.config.js` to use ES modules (export default)
|
||||
- [ ] Create `eslint.config.mjs` with flat config format
|
||||
- [ ] Remove old `.eslintrc.json` file
|
||||
- [ ] Update `.nvmrc` to 18.18.0
|
||||
- [ ] Test the application: `pnpm dev`
|
||||
- [ ] Build for production: `pnpm build`
|
||||
- [ ] Update README and documentation
|
||||
|
||||
## 🎯 Benefits After Migration
|
||||
|
||||
### Performance Improvements
|
||||
- **~10x faster dev server** startup with Turbopack
|
||||
- **Faster CSS compilation** with Tailwind 4
|
||||
- **Smaller bundle sizes** in production
|
||||
- **Better hot reload** performance
|
||||
|
||||
### Developer Experience
|
||||
- **Simpler configuration** - less boilerplate
|
||||
- **Better error messages** - clearer debugging
|
||||
- **Faster feedback loop** - instant updates
|
||||
- **Modern tooling** - latest ecosystem features
|
||||
|
||||
### Future-Proof
|
||||
- Using the latest stable versions
|
||||
- Better long-term support
|
||||
- Access to newest features
|
||||
- Compatible with latest ecosystem tools
|
||||
|
||||
## 🐛 Troubleshooting
|
||||
|
||||
### Issue: Dev server won't start
|
||||
**Solution**: Clear cache and reinstall
|
||||
```bash
|
||||
rm -rf .next node_modules
|
||||
pnpm install
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### Issue: Tailwind classes not working
|
||||
**Solution**: Check your `globals.css` uses `@import "tailwindcss"`
|
||||
```css
|
||||
@import "tailwindcss";
|
||||
```
|
||||
|
||||
### Issue: TypeScript errors
|
||||
**Solution**: Ensure tsconfig.json is updated and regenerate types
|
||||
```bash
|
||||
rm -rf .next
|
||||
pnpm dev
|
||||
```
|
||||
|
||||
### Issue: ESLint errors
|
||||
**Solution**: Ensure you're using the new flat config format in `eslint.config.mjs`
|
||||
|
||||
### Issue: Build fails
|
||||
**Solution**: Check Node.js version
|
||||
```bash
|
||||
node --version # Should be 18.18.0+
|
||||
```
|
||||
|
||||
## 📚 Additional Resources
|
||||
|
||||
- [Next.js 15 Release Notes](https://nextjs.org/blog/next-15)
|
||||
- [Tailwind CSS 4.0 Documentation](https://tailwindcss.com/docs/v4-beta)
|
||||
- [React 19 Release Notes](https://react.dev/blog/2024/12/05/react-19)
|
||||
- [Turbopack Documentation](https://turbo.build/pack/docs)
|
||||
|
||||
## 🎉 Conclusion
|
||||
|
||||
The migration to Next.js 15 and Tailwind CSS 4 brings significant performance improvements and a better developer experience. The changes are minimal but impactful, setting up your project for the future of web development.
|
||||
|
||||
If you encounter any issues not covered here, please refer to the official documentation or reach out for support.
|
||||
|
||||
---
|
||||
|
||||
**Migrated with ❤️ by Valknar** | [pivoine.art](http://pivoine.art)
|
||||
Reference in New Issue
Block a user