Next.js App Router

File conventions

Route groups (optional)

app/
  (marketing)/
    layout.tsx    → light marketing chrome
    page.tsx
  (app)/
    layout.tsx    → app shell / auth gate
    dashboard/page.tsx

Groups don't affect URL path.

Metadata on client pages

Client page.tsx cannot export metadata — use sibling layout.tsx:

// app/dashboard/layout.tsx
import type { Metadata } from "next";
export const metadata: Metadata = { title: "Dashboard", robots: { index: false } };
export default function Layout({ children }: { children: React.ReactNode }) {
  return children;
}

Server Component data

// Server Component — no "use client"
export default async function Page() {
  const data = await fetchData(); // or direct DB
  return <ClientView initial={data} />;
}

Pass serializable props only to client children.

Navigation

import Link from "next/link";
import { useRouter, usePathname, useSearchParams } from "next/navigation";

Prefer Link for internal routes; router.replace for redirects after guard checks.

Env helpers (lib/env.ts)

Centralize reads — never scatter process.env in components:

export function getSiteUrl(): string {
  return process.env.NEXT_PUBLIC_SITE_URL ?? "http://localhost:3000";
}

Document every var in .env.example; upsert .env when adding new vars.

Root layout checklist

- [ ] lang on <html>
- [ ] fonts via next/font
- [ ] global providers (theme, tooltip, analytics)
- [ ] SkipToMain link
- [ ] metadataBase for production URLs

Anti-patterns

• Fetching in client what server could fetch once
• Importing server-only modules into client components
• Multiple nested "use client" boundaries without reason
• Hardcoding URLs instead of env-based getSiteUrl()

Pair with: nextjs-ui-foundation, nextjs-seo-metadata, nextjs-api-routes.