@nx/next
Version:
846 lines (615 loc) • 18.1 kB
Markdown
These instructions guide you through migrating an Nx workspace containing Next.js projects from Next.js 15 to Next.js 16. Work systematically through each breaking change category.
1. **Identify all Next.js projects**:
```bash
nx show projects --with-target build | xargs -I {} nx show project {} --json | jq -r 'select(.targets.build.executor | contains("next")) | .name'
```
Or search for Next.js configuration files:
```bash
find . -name "next.config.*" -not -path "*/node_modules/*"
```
2. **Update packages**:
```bash
npm install next@latest react@latest react-dom@latest
npm install -D @types/react @types/react-dom
```
3. **Verify minimum requirements**:
- Node.js 20.9+ (Node.js 18 is no longer supported)
- TypeScript 5.1.0+
- Browser support: Chrome 111+, Edge 111+, Firefox 111+, Safari 16.4+
This is the most impactful change in Next.js 16. All dynamic request APIs are now asynchronous.
**Search Patterns**:
- `cookies()` usage in server components
- `headers()` usage in server components
- `draftMode()` usage
- `params` in page, layout, route handlers, and metadata files
- `searchParams` in page components
**Changes Required**:
```tsx
// BEFORE (Next.js 15)
export default function Page({ params }) {
const { slug } = params;
return <h1>{slug}</h1>;
}
// AFTER (Next.js 16)
export default async function Page(props) {
const { slug } = await props.params;
return <h1>{slug}</h1>;
}
```
**Action Items**:
- [ ] Make all page components that use `params` async
- [ ] Add `await` before accessing `props.params`
- [ ] Update TypeScript types if applicable
**Changes Required**:
```tsx
// BEFORE (Next.js 15)
export default function Page({ searchParams }) {
const query = searchParams.q;
return <Results query={query} />;
}
// AFTER (Next.js 16)
export default async function Page(props) {
const searchParams = await props.searchParams;
const query = searchParams.q;
return <Results query={query} />;
}
```
**Action Items**:
- [ ] Make all page components that use `searchParams` async
- [ ] Add `await` before accessing `props.searchParams`
**Changes Required**:
```tsx
// BEFORE (Next.js 15)
export default function Layout({ children, params }) {
const { locale } = params;
return <div data-locale={locale}>{children}</div>;
}
// AFTER (Next.js 16)
export default async function Layout(props) {
const { locale } = await props.params;
return <div data-locale={locale}>{props.children}</div>;
}
```
**Changes Required**:
```tsx
// BEFORE (Next.js 15)
export async function GET(request, { params }) {
const { id } = params;
return Response.json({ id });
}
// AFTER (Next.js 16)
export async function GET(request, props) {
const { id } = await props.params;
return Response.json({ id });
}
```
**Changes Required**:
```tsx
// BEFORE (Next.js 15)
import { cookies, headers } from 'next/headers';
export default function Page() {
const cookieStore = cookies();
const headersList = headers();
const theme = cookieStore.get('theme');
const userAgent = headersList.get('user-agent');
return <div>...</div>;
}
// AFTER (Next.js 16)
import { cookies, headers } from 'next/headers';
export default async function Page() {
const cookieStore = await cookies();
const headersList = await headers();
const theme = cookieStore.get('theme');
const userAgent = headersList.get('user-agent');
return <div>...</div>;
}
```
**Changes Required**:
```tsx
// BEFORE (Next.js 15)
import { draftMode } from 'next/headers';
export default function Page() {
const { isEnabled } = draftMode();
return <div>{isEnabled ? 'Draft' : 'Published'}</div>;
}
// AFTER (Next.js 16)
import { draftMode } from 'next/headers';
export default async function Page() {
const { isEnabled } = await draftMode();
return <div>{isEnabled ? 'Draft' : 'Published'}</div>;
}
```
**Changes Required**:
```tsx
// BEFORE (Next.js 15)
export async function generateMetadata({ params }) {
const { slug } = params;
return { title: slug };
}
// AFTER (Next.js 16)
export async function generateMetadata(props) {
const { slug } = await props.params;
return { title: slug };
}
```
Run the Next.js codemod for automated migration:
```bash
npx @next/codemod@canary upgrade latest
```
Generate type helpers for safer migrations (Next.js 15.5+):
```bash
npx next typegen
```
This generates `PageProps`, `LayoutProps`, and `RouteContext` helpers.
### 2. Image Generation Functions
**Search Pattern**: `generateImageMetadata`, `default function Image` in opengraph-image or twitter-image files
**Changes Required**:
```tsx
// BEFORE (Next.js 15)
export function generateImageMetadata({ params }) {
const { slug } = params;
return [{ id: '1' }];
}
export default function Image({ params, id }) {
const slug = params.slug;
return new ImageResponse(/* ... */);
}
// AFTER (Next.js 16)
export async function generateImageMetadata({ params }) {
const { slug } = await params;
return [{ id: '1' }];
}
export default async function Image({ params, id }) {
const { slug } = await params;
const imageId = await id;
return new ImageResponse(/* ... */);
}
```
**Action Items**:
- [ ] Make `generateImageMetadata` functions async
- [ ] Make Image components async
- [ ] Add `await` for both `params` and `id` access
**Search Pattern**: `sitemap` functions with `id` parameter
**Changes Required**:
```tsx
// BEFORE (Next.js 15)
export default async function sitemap({ id }) {
const start = id * 50000;
// ...
}
// AFTER (Next.js 16)
export default async function sitemap({ id }) {
const resolvedId = await id;
const start = resolvedId * 50000;
// ...
}
```
Turbopack is now the default bundler for development.
**Search Pattern**: `--turbo` or `--turbopack` flags in package.json scripts, `turbopack` in next.config
```json
// BEFORE (Next.js 15)
{
"scripts": {
"dev": "next dev --turbo"
}
}
// AFTER (Next.js 16) - Turbopack is default
{
"scripts": {
"dev": "next dev"
}
}
```
```json
{
"scripts": {
"build": "next build --webpack"
}
}
```
```ts
// BEFORE (Next.js 15)
const nextConfig = {
experimental: {
turbopack: {
/* options */
},
},
};
// AFTER (Next.js 16)
const nextConfig = {
turbopack: {
/* options */
},
};
```
```scss
/* BEFORE */
@import '~bootstrap/dist/css/bootstrap.min.css';
/* AFTER - Remove tilde prefix */
@import 'bootstrap/dist/css/bootstrap.min.css';
```
**Action Items**:
- [ ] Remove `--turbo` and `--turbopack` flags from scripts
- [ ] Move `turbopack` config from `experimental` to root level
- [ ] Remove tilde (`~`) prefix from Sass imports
- [ ] Add `--webpack` flag if Webpack is required
### 5. Middleware to Proxy Rename
**Search Pattern**: `middleware.ts` or `middleware.js` files
**Changes Required**:
```bash
# Rename the file
mv middleware.ts proxy.ts
```
```ts
// BEFORE (middleware.ts)
export function middleware(request) {
// ...
}
// AFTER (proxy.ts)
export function proxy(request) {
// ...
}
```
**Config Updates**:
```js
// BEFORE
{
skipMiddlewareUrlNormalize: true;
}
// AFTER
{
skipProxyUrlNormalize: true;
}
```
**Important**: The Edge runtime is no longer supported in `proxy`. It now uses Node.js runtime.
**Action Items**:
- [ ] Rename `middleware.ts/js` to `proxy.ts/js`
- [ ] Rename exported function from `middleware` to `proxy`
- [ ] Update config option names
- [ ] Remove Edge runtime usage from proxy files
**Search Pattern**: Directories starting with `@` in the app folder (parallel route slots)
All parallel route slots now require an explicit `default.js` file.
**Changes Required**:
```tsx
// Create app/@modal/default.tsx for each parallel route slot
import { notFound } from 'next/navigation';
export default function Default() {
notFound(); // or return null
}
```
**Action Items**:
- [ ] Find all parallel route slots (`app/@*/`)
- [ ] Create `default.tsx` in each slot that doesn't have one
### 7. Image Optimization Changes
#### 7.1 Local Images with Query Strings
```tsx
// Now requires explicit configuration
<Image src="/assets/photo?v=1" alt="Photo" width="100" height="100" />
```
```js
// next.config.js
module.exports = {
images: {
localPatterns: [
{
pathname: '/assets/**',
search: '?v=1',
},
],
},
};
```
Add these to `next.config.js` if you need the old defaults:
```js
module.exports = {
images: {
// minimumCacheTTL changed from 60 to 14400 seconds
minimumCacheTTL: 60,
// Value 16 removed from default imageSizes
imageSizes: [16, 32, 48, 64, 96, 128, 256, 384],
// qualities now defaults to [75] only
qualities: [50, 75, 100],
// Local IP now blocked by default
dangerouslyAllowLocalIP: true, // only for private networks
// Maximum redirects changed from unlimited to 3
maximumRedirects: 5,
},
};
```
```js
// BEFORE - Remove this
module.exports = {
images: {
domains: ['example.com'],
},
};
// AFTER - Use remotePatterns instead
module.exports = {
images: {
remotePatterns: [
{
protocol: 'https',
hostname: 'example.com',
},
],
},
};
```
**Action Items**:
- [ ] Add `localPatterns` for images with query strings
- [ ] Migrate `images.domains` to `images.remotePatterns`
- [ ] Review and update default values if needed
```ts
// BEFORE (Next.js 15)
import {
unstable_cacheLife as cacheLife,
unstable_cacheTag as cacheTag,
} from 'next/cache';
// AFTER (Next.js 16)
import { cacheLife, cacheTag } from 'next/cache';
```
**revalidateTag with cacheLife profile**:
```ts
'use server';
import { revalidateTag } from 'next/cache';
export async function updateArticle(articleId: string) {
revalidateTag(`article-${articleId}`, 'max');
}
```
**updateTag (new)**:
```ts
'use server';
import { updateTag } from 'next/cache';
export async function updateUserProfile(userId: string, profile: Profile) {
await db.users.update(userId, profile);
updateTag(`user-${userId}`);
}
```
**refresh (new)**:
```ts
'use server';
import { refresh } from 'next/cache';
export async function markNotificationAsRead(notificationId: string) {
await db.notifications.markAsRead(notificationId);
refresh();
}
```
**Action Items**:
- [ ] Remove `unstable_` prefix from `cacheLife` and `cacheTag` imports
- [ ] Consider using new `updateTag` and `refresh` functions
React Compiler is now stable and supported:
```ts
// next.config.ts
const nextConfig = {
reactCompiler: true,
};
export default nextConfig;
```
Install the plugin:
```bash
npm install -D babel-plugin-react-compiler
```
**Note**: Expect higher compile times with React Compiler enabled.
Next.js no longer overrides `scroll-behavior: smooth` during navigation.
To restore previous behavior:
```tsx
// app/layout.tsx
export default function RootLayout({ children }) {
return (
<html lang="en" data-scroll-behavior="smooth">
<body>{children}</body>
</html>
);
}
```
The `next lint` command has been removed. Migrate to ESLint CLI directly.
```bash
npx @next/codemod@canary next-lint-to-eslint-cli .
```
Remove from `next.config.js`:
```js
// Remove this
{
eslint: {
}
}
```
**Action Items**:
- [ ] Run the ESLint migration codemod
- [ ] Remove `eslint` config from `next.config.js`
- [ ] Update CI scripts to use `eslint` directly instead of `next lint`
- All AMP APIs have been deleted
- Remove `useAmp` hook usage
- Remove `amp` config option
- Delete AMP-specific pages
```js
// BEFORE - Remove these
module.exports = {
serverRuntimeConfig: { dbUrl: process.env.DATABASE_URL },
publicRuntimeConfig: { apiUrl: '/api' },
};
```
**Migration for server-side config**:
```tsx
// Use environment variables directly
async function fetchData() {
const dbUrl = process.env.DATABASE_URL;
return await db.query(dbUrl, 'SELECT * FROM users');
}
```
**Migration for client-side config**:
```bash
NEXT_PUBLIC_API_URL="/api"
```
```tsx
'use client';
export default function Component() {
const apiUrl = process.env.NEXT_PUBLIC_API_URL;
// ...
}
```
Remove these from `next.config.js`:
- `appIsrStatus`
- `buildActivity`
- `buildActivityPosition`
```js
// BEFORE
{
experimental: {
dynamicIO: true;
}
}
// AFTER
{
cacheComponents: true;
}
```
This API is removed. Await alternative API in a future minor release.
**Action Items**:
- [ ] Remove all AMP-related code
- [ ] Migrate runtime configuration to environment variables
- [ ] Remove deprecated devIndicators options
- [ ] Rename `dynamicIO` to `cacheComponents`
Development now outputs to `.next/dev` (separate from build).
**Update Turbopack tracing command**:
```bash
npx next internal trace .next/dev/trace-turbopack
```
```bash
nx run PROJECT_NAME:build
```
```bash
nx run PROJECT_NAME:serve
```
```bash
nx affected -t build
```
```bash
nx prepush
```
- [ ] All async request APIs updated
- [ ] All page/layout components using params are async
- [ ] Turbopack configuration updated
- [ ] Middleware renamed to proxy
- [ ] Parallel routes have default.js files
- [ ] Image configuration updated
- [ ] Cache imports updated (removed unstable\_ prefix)
- [ ] AMP code removed
- [ ] Runtime config migrated to env vars
- [ ] ESLint configuration migrated
- [ ] All projects build successfully
- [ ] Development servers start correctly
## Common Issues and Solutions
### Issue: "cookies() expects to be called in a synchronous context"
**Solution**: Make the function async and await `cookies()`
### Issue: "params should be awaited before accessing properties"
**Solution**: Add `await` before accessing `props.params`
### Issue: Build fails with Turbopack
**Solution**: Add `--webpack` flag to build script, then gradually address Turbopack compatibility
### Issue: Middleware not working after rename
**Solution**: Ensure both file and function are renamed from `middleware` to `proxy`
### Issue: Parallel route not rendering
**Solution**: Add `default.tsx` file to the parallel route slot
### Issue: Images with query strings not loading
**Solution**: Add `localPatterns` configuration for those images
### Issue: TypeScript errors with params types
**Solution**: Run `npx next typegen` to generate type helpers, then use `PageProps`, `LayoutProps` types
## Files to Review
Create a checklist of all files that need review:
```bash
# Find all pages with potential params usage
find . -path "*/app/*" -name "page.tsx" -o -name "page.ts" | xargs grep -l "params\|searchParams"
# Find all layouts
find . -path "*/app/*" -name "layout.tsx" -o -name "layout.ts"
# Find all route handlers
find . -path "*/app/*" -name "route.ts" -o -name "route.tsx"
# Find middleware files
find . -name "middleware.ts" -o -name "middleware.js"
# Find files using cookies/headers
rg "from 'next/headers'" --type ts --type tsx
# Find next.config files
find . -name "next.config.*" -not -path "*/node_modules/*"
# Find parallel routes
find . -path "*/app/@*" -type d
```
## Migration Strategy for Large Workspaces
1. **Migrate in phases**: Start with a small project, validate, then expand
2. **Use the codemod**: Run `npx @next/codemod@canary upgrade latest` for automated fixes
3. **Generate types**: Run `npx next typegen` for type-safe migrations
4. **Run tests frequently**: After each configuration change, run affected tests
5. **Document issues**: Keep track of project-specific issues and solutions
## Useful Commands During Migration
```bash
# Find all Next.js projects
nx show projects --with-target build
# Build specific project
nx build PROJECT_NAME
# Serve specific project
nx serve PROJECT_NAME
# Build all affected
nx affected -t build
# View project details
nx show project PROJECT_NAME --web
# Clear Nx cache if needed
nx reset
```
---
## Notes for LLM Execution
When executing this migration:
1. **Work systematically**: Complete one category before moving to the next
2. **Test after each change**: Don't batch all changes without validation
3. **Keep user informed**: Report progress through each section
4. **Handle errors promptly**: If builds fail, fix immediately before proceeding
5. **Use the codemod first**: Let `@next/codemod` handle repetitive async/await changes
6. **Prioritize breaking changes**: Focus on async APIs first as they're most impactful
7. **Create meaningful commits**: Group related changes together with clear messages
8. **Use TodoWrite tool**: Track migration progress for visibility