1. Architecture and Folder Structure

• Use Next.js 16 App Router only (app/ or src/app/); never use pages/.
  • If src/app/ exists, treat it as the routing root.
  • If only app/ exists, treat app/ as the routing root.
• Recommended structure (root = app/ or src/app/):
  • root/ – routes, layouts, route handlers (API).
  • components/ui/ – base/atomic UI components.
  • components/features/ – feature/domain-specific components.
  • lib/ – utilities, API/DB clients, validation (Zod), configs.
  • actions/ – Server Actions decoupled from components.
  • hooks/ – React hooks (client-side only).
  • types/ – shared TypeScript types.
  • public/ – static assets.

2. Components, Naming and Style

• Every component is a Server Component by default; add 'use client' only where there are hooks or browser APIs.
• Use PascalCase for components and camelCase for variables, functions and hooks (useSomething).
• Use TypeScript types for props and object shapes; avoid any and keep strict TypeScript.
• Prefer named exports for components and utilities; use export default only for app/**/page.tsx.
• File organization:
  • Route/layout files follow Next conventions (page.tsx, layout.tsx, loading.tsx, error.tsx, not-found.tsx).
  • Components in PascalCase.tsx or kebab-case.tsx according to your chosen standard, but keep it consistent across the project.

3. Imports, Shared Code and Fetch

• Use absolute imports with @/ configured in tsconfig.json; avoid deep relative paths (../../..).
• Centralize HTTP/REST calls in lib/ modules (for example, lib/api.ts); avoid raw fetch spread across components.
• In Server Components, do data fetching with async/await following Next 16 conventions (async params and searchParams).
• For caching:
  • Default: no cache for server fetch in recent versions.
  • Explicit cache: fetch(url, { cache: 'force-cache' }).
  • Revalidation: fetch(url, { next: { revalidate: 3600 } }).

4. Next.js 16: Async APIs and Layouts

• params and searchParams in pages, layouts and route handlers are Promises:
  • Always use const { slug } = await params; before accessing.
• headers() and cookies() are async as well:
  • Use const cookieStore = await cookies();.
• Use route groups and nested layouts to organize sections:
  • Examples: app/(marketing)/, app/(app)/dashboard/.

5. React 19: Server Components and New Features

• Use React Server Components by default; push 'use client' to leaf components that are truly interactive.
• Use Server Actions for mutations and form submission whenever possible, avoiding manual API Routes for simple CRUD.
• Use the new hooks:
  • useActionState to manage form action state.
  • useFormStatus for loading and feedback inside <form>.
  • use() to read Promises or Contexts where appropriate.

6. API Routes, Server Actions and Security

• API Routes (when really needed) live in app/api/**/route.ts.
  • Export HTTP methods (GET, POST, etc.) as async functions using NextResponse.
  • Validate payload and query with Zod or an equivalent schema before using.
• Server Actions:
  • Always validate input with Zod.
  • Keep sensitive logic on the server, without leaking details to the client.
• Use server-only (Taint API) to guarantee that sensitive functions (like DB access) are never imported in client-side code.

7. UI, Performance and Accessibility

• Use Tailwind CSS as the styling foundation; keep globals.css lean (reset, fonts, global tokens).
• Combine Tailwind with clsx and tailwind-merge for conditional classes and to avoid conflicts.
• Images:
  • Always use next/image with width, height or fill, and priority for LCP when needed.
• Fonts:
  • Use next/font for automatic optimization and to avoid layout shift.
• Use Suspense, streaming and Partial Prerendering (PPR):
  • Wrap dynamic sections in Suspense boundaries to enable streaming and progressive loading.

7.1 shadcn/ui Rules

• Install and configure shadcn/ui using the official Next.js guide, ensuring App Router + Tailwind setup is complete before running the CLI.
• Use the latest React 19–compatible preset or configuration when initializing shadcn/ui, following the React 19 notes from the official docs.
• Co-locate shadcn components under components/ui/, keeping them as Server Components by default, and add 'use client' only when using client-only hooks or animations.
• Do not edit the core logic of generated shadcn components; extend them via wrappers/composition when customization is needed to simplify future updates.
• Always keep accessibility props (labels, roles, aria-attributes) provided by shadcn primitives and do not strip them when styling.

7.2 Framer Motion Rules

• Use Framer Motion only in Client Components with 'use client', importing from framer-motion and wrapping animated elements with motion.*.
• Prefer variants and transition objects defined outside JSX for reuse and to keep components readable.
• Use AnimatePresence only when components are conditionally mounted/unmounted and need exit animations, and avoid nesting multiple AnimatePresence unnecessarily.
• Keep animation values GPU-friendly (translate, scale, opacity, rotate) and avoid animating expensive properties like box-shadow and layout-heavy CSS whenever possible.
• Combine Framer Motion with shadcn/ui by wrapping shadcn components in motion() (for example, const MotionButton = motion(Button)), ensuring focus states, aria attributes and keyboard navigation remain intact.

8. Package Manager, Bundler, Test Runner and Runtime (Bun + Next)

• Runtime and package manager:
  • Use Bun v1.3+ as the default runtime: bun instead of node.
  • Install: bun install (do not use npm/yarn/pnpm).
  • Scripts: bun run <script>.
• Dev server and frameworks:
  • Next: bun --bun next dev.

9. Native Bun APIs (When Writing Scripts/Services)

• Files:
  • Use Bun.file() and Bun.write() instead of fs/fs.promises.
• Custom HTTP server:
  • Prefer Bun.serve() for auxiliary services independent from Next.
• Utilities:
  • Bun.password (argon2) for hashing.
  • Bun.sleep(ms) instead of setTimeout in scripts.
  • Bun.env for environment variables.
  • Bun.gzipSync / Bun.deflateSync for compression.
• Tests:
  • Use bun test with bun:test (describe, test, expect, mock).

10. Code Quality and Lint

• Follow the existing ESLint/Prettier configuration of the project strictly.
• Do not introduce new dependencies or architectural patterns without explicit instruction.
• Keep components small, cohesive and reusable, prioritizing clarity over premature abstraction.