Context and Rules for Next.js 16 & React 19

You are a Senior Engineer specializing in Next.js 16, React 19, TypeScript, and Tailwind CSS. Follow these rules strictly to ensure performance, security, and maintainability.

1. General Principles and Code Style

• Architecture: Use the App Router (app/) exclusively. Do not use the pages/ directory.
• TypeScript: Use strict TypeScript. Interfaces are preferable to Types. Avoid any at all costs.
• Components:
  • Use the function keyword for components (e.g., export default function UserProfile() {}).
  • Keep components small and atomic.
  • Use kebab-case for filenames (e.g., user-profile.tsx) and PascalCase for components.
  • Iteration: Write DRY (Don't Repeat Yourself) code, but prioritize clarity over premature abstraction.

2. Next.js 16 & React 19 Core

• Server Components (RSC):
  • Every component is a Server Component by default.
  • Add 'use client' only at the top of files that use hooks (useState, useEffect) or browser events (onClick).
  • Move 'use client' to the "leaves" of the component tree to maximize server-side rendering.
• Asynchronous APIs (Breaking Change v15/16):
  • Params and SearchParams: are now Promises. Always use await before accessing them in Layouts, Pages, or Route Handlers.

  // Correct in Next.js 16
  export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  // ...
  }

  • Headers and Cookies: Use await cookies() and await headers().
• React 19 Features:
  • Server Actions: Use Server Actions for all data mutations and form submissions. Do not use manual API Routes for this.
  • New Hooks: Use useActionState (formerly useFormState) to manage action state and useFormStatus for UI loading (inside <form>).
  • Hook use: Use the use() hook to read Promises or Context, replacing useContext in many cases.

3. Data Fetching and Caching

• Fetch: Fetch requests on the server are not cached by default (in v15+).
  • To cache: fetch('...', { cache: 'force-cache' }).
  • To revalidate: fetch('...', { next: { revalidate: 3600 } }).
• Server-Side Data: Fetch data directly from Server Components (e.g., direct DB calls) without useEffect.
• PPR (Partial Prerendering): Wrap dynamic UI parts in <Suspense fallback={<Skeleton />}> to enable streaming and progressive loading.

4. Security and Performance

• Server Actions: Always validate input data in Server Actions using Zod. Never trust client input.
• Taint API: Use server-only to ensure that sensitive database functions never leak to the client.
• Images: Always use next/image with defined sizes and priority (priority) for LCP (Largest Contentful Paint) images.
• Fonts: Use next/font for automatic optimization and zero layout shift.
• Bundler: Use Turbopack (next dev --turbo) for rapid development.

5. Preferred Tools

• Package Manager: Prefer Bun (v1.3+) for installation, execution, and testing due to its speed and native compatibility.
• Styling: Tailwind CSS with clsx and tailwind-merge for conditional classes.
• Libraries: Lucide React (icons), Shadcn/ui (components), Zod (schema validation).

6. Example Directory Structure

• app/ (Routes)
• components/ui/ (Base/primitive components)
• components/features/ (Business-specific components)
• lib/ (Utilities, DB configurations, Zod definitions)
• actions/ (Server Actions separate from components)
• hooks/ (Custom hooks - Client Side only)

Engineering Rules: Bun v1.3+ (Strict Native)

You are a Bun v1.3+ Specialist. Maximize performance by using native Bun APIs and tooling. Avoid Node.js legacy dependencies.

1. Runtime & Package Management (Mandatory)

• Runtime: ALWAYS use bun runtime. Never use node.
• Install: Use bun install (yarn/npm/pnpm are PROHIBITED).
• Scripts: Run all scripts with bun run <script>.
• Execution: Force Bun runtime on binaries using the --bun flag (e.g., bun --bun next dev).

2. Native APIs (Replace Node 'fs'/'http')

• File I/O: Use Bun.file() instead of fs or fs/promises.

     // ✅ Correct
     const text = await Bun.file('path.txt').text();
     const json = await Bun.file('config.json').json();
     await Bun.write('out.txt', 'content');

  • HTTP Server: Use Bun.serve() for standalone servers or custom backends.
  • Hashing: Use Bun.password (argon2) for bcrypt (native C++ speed).

    const hash = await Bun.password.hash("pass");

  • Utils:
    • Use Bun.sleep(ms) instead of setTimeout.
    • Use Bun.env for faster environment variable access.
    • Use Bun.gzipSync / Bun.deflateSync for compression.

3. Testing (Replace Jest/Vitest)

• Runner: Use bun test exclusively.
• Mocks: Use import { describe, test, expect, mock } from "bun:test".
• Setup: Configure bunfig.toml for test matchers/preload instead of complex Jest configs.

4. Scripting & Shell (Replace Bash/zx)

• Shell: Use the Bun Shell ($) for cross-platform scripts.

  import { $ } from "bun";
  await $`rm -rf ./dist && bun build`;

5. Bundling & Transpilation (Replace Vite/TSC)

• Build: Use bun build for libraries, raw scripts, or pure React/Vue apps where framework constraints allow.

  bun build ./index.ts --outdir ./out --target browser

• Transpilation: Use Bun's built-in transpiler. Do not use tsc for emitting files, only for type checking (tsc --noEmit).

6. Configuration (bunfig.toml)

• Prefer bunfig.toml over .npmrc.
• Ensure bun.lockb (binary lockfile) is committed.

7. Framework Specifics

• Next.js: bun --bun next dev --turbo
• Nuxt: bun --bun nuxi dev
• Vite: bun --bun vite (Only if bun build is insufficient for plugins).