nextjs

Files (1)

• SKILL.md

SKILL.md (first lines)

# nextjs

Next.js 15 / React 19 state-of-the-art — App Router, async request APIs, `use cache` directive, Turbopack, Server Functions, Partial Prerendering, and production best practices.

> Targets **Next.js 15+** with **React 19**. Older patterns (Pages Router, synchronous request APIs) are not covered here.

## Instructions

### Tooling & Project Setup

- Use **Turbopack** for local development — it is stable since Next.js 15 and faster than Webpack in virtually all cases:
  ```bash
  next dev --turbo
  ```
- Use `next.config.ts` (TypeScript) instead of `next.config.js` — full type safety for all config options
- Use the codemod CLI to upgrade between versions:
  ```bash
  npx @next/codemod@canary upgrade latest
  ```
- Enable the **React Compiler** (experimental) to auto-memoize components without manual `useMemo`/`useCallback`:
  ```ts
  // next.config.ts
  const nextConfig = {
    experimental: { reactCompiler: true },
  };
  ```

### App Router Conventions

Use the **App Router** (`app/`) exclusively. Understand the file conventions:

| File | Purpose |
|------|---------|
| `layout.tsx` | Shared UI wrapper; persists across navigation |
| `page.tsx` | Route segment UI |
| `loading.tsx` | Suspense boundary fallback for the segment |
| `error.tsx` | Error boundary (must be a Client Component) |
| `not-found.tsx` | Rendered when `notFound()` is called |
| `route.ts` | API route handler |
| `middleware.ts` | Edge function; runs before every matched request |
| `instrumentation.ts` | Server lifecycle hooks (stable in Next.js 15) |

**Server vs. Client Components:**
- All components are **Server Components by default** — zero JS bundle cost, direct DB/API access, secrets never reach the browser
- Add `'use client'` only for: event handlers, browser APIs, `useState`/`useEffect`, third-party client-only libraries
- Push `'use client'` boundaries as **far down** the tree as possible to minimise bundle size

```tsx
// Server Component — async/await directly, no useEffect
export default async function UserProfile({ params }: { params: Promise<{ id: string }> }) {
  const { id } = await params; // params is async in Next.js 15+
  const user = await db.user.findUnique({ where: { id } });
  if (!user) notFound();
  return <ProfileCard user={user} />;
}
```

### ⚠️ Async Request APIs (Next.js 15 Breaking Change)

`cookies()`, `headers()`, `draftMode()`, `params`, and `searchParams` are **now async** and must be awaited:

```ts
// ✅ Next.js 15+
import { cookies, headers } from 'next/headers';

export default async function Page({ params, searchParams }: {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{ q: string }>;
}) {
  const { slug } = await params;
  const { q } = await searchParams;
  const cookieStore = await cookies();
  const token = cookieStore.get('token');
  // ...
}
```

Run the official codemod to migrate automatically:
```bash
npx @next/codemod@canary next-async-request-api .
```

### Caching — New Model (`use cache`)

Next.js 15 ships two caching models. Use the **new model** for all new projects:

**Enable Cache Components in `next.config.ts`:**
```ts
const nextConfig = { cacheComponents: true };
export default nextConfig;
```

**`use cache` directive** — replaces the old implicit `fetch` caching:

```ts
// Data-level cache — reuse across multiple components
async function getProducts() {
  'use cache';
  return db.product.findMany();
}

// UI-level cache — cache an entire component's render
async function FeaturedBanner() {
  'use cache';
  const promo = await fetchPromo();
  return <Banner data={promo} />;
}
```

**Rules for `use cache`:**
- Arguments and closed-over values automatically form the cache key
- Cannot call `cookies()` or `headers()` inside a `use cache` scope — read them outside and pass as arguments
- For serverless environments the default LRU cache does not persist across invocations; use `'use cache: remote'` (Redis/KV) for shared runtime caching
- Revalidate with `revalidateTag()` / `revalidatePath()` on demand, or set a TTL via `cacheLife`:
  ```ts
  import { unstable_cacheLife as cacheLife } from 'next/cache';

  async function getStats() {
    'use cache';

From Satcomx00-x00/skills-db, MIT.

More from Satcomx00-x00/skills-db