Next.js interview questions and answers

Core Definition and Purpose

Next.js simplifies production React development by handling configuration, bundling, and server infrastructure automatically. It allows components to render on the server, significantly improving initial load performance and SEO compared to pure client-side rendering. The framework provides a file-system-based router where files in the app directory define routes, layouts, and UI segments. It also includes built-in support for TypeScript, image optimization via the next/image component, font optimization, and script loading strategies. These tools reduce the need for third-party libraries and ensure best practices are enforced by default.

Rendering Strategies

The framework supports multiple rendering modes tailored to different content needs, determining when HTML is generated and how it is cached. - Static Rendering: Pages are pre-built at build time. This is the default in the App Router for pages without dynamic data dependencies, resulting in the fastest load times and lowest server load. - Server-Side Rendering (SSR): Pages are rendered on each request. This is triggered by using dynamic functions or uncached data fetching (cache: 'no-store'), ensuring data is always fresh. - Incremental Static Regeneration (ISR): Static pages can be revalidated after a specified time using the revalidate option in fetch or layout metadata, balancing speed and freshness without rebuilding the whole site. - Streaming: UI is sent in chunks using React Suspense, allowing slower data queries to resolve without blocking the entire page shell, improving perceived performance.

App Router and Component Types

The App Router introduces a nested layout model and strictly distinguishes between server and client components to optimize bundle size. - Server Components: Default in app/. They access backend resources directly and cannot use hooks, event listeners, or browser APIs. - Client Components: Marked with 'use client' at the top of the file. They handle interactivity, state, and effects using React hooks like useState or useEffect. - Layouts: Persistent UI elements defined in layout.tsx that preserve state and avoid re-rendering during navigation between sibling pages.

Data Fetching and Mutations

Data handling is integrated directly into components rather than relying solely on separate API endpoints, reducing network waterfalls. - Fetching: Use the native fetch API within server components. Results are automatically cached and deduplicated based on request options and URL stability. - Route Handlers: Define API endpoints in app/api/<segment>/route.ts using standard Web Request/Response objects for external integrations. - Server Actions: Functions marked with 'use server' allow form submissions and mutations directly from server or client components without manual API route setup.

Best Practices

To maximize performance and maintainability, follow these guidelines during development. - Keep data fetching in server components whenever possible to reduce client bundle size and avoid exposing API keys. - Use explicit caching options (cache, no-store) on fetch requests to control rendering behavior precisely. - Minimize client component usage by passing data as props from server components to interactive children. - Leverage streaming with Suspense boundaries to improve Time to First Byte (TTFB) for dynamic dashboards.

Rendering Model

• Next.js: Supports multiple rendering strategies per route — React Server Components (default), Server-Side Rendering (SSR), Static Site Generation (SSG), Incremental Static Regeneration (ISR), and client-side rendering via 'use client'.

• CRA: Client-side rendering only. The entire application runs in the browser after the initial HTML shell loads.

Routing

• Next.js: File-system based routing in the app/ directory (App Router) or pages/ directory (Pages Router). Supports nested layouts, route groups, parallel routes, and intercepting routes.

• CRA: No built-in routing. Requires installing react-router-dom and configuring routes manually in JavaScript.

Data Fetching & API Layer

• Next.js: Server Components fetch data directly at build or request time using async/await with native fetch extended with next: { revalidate, tags }. Server Actions handle mutations. Route Handlers (app/api/**/route.ts) create REST endpoints. Can connect to databases, ORMs, and secrets at build/runtime.

• CRA: Data fetching happens in useEffect or libraries like TanStack Query/SWR on the client. No server-side data access. Backend must be a separate service; environment variables only available at build time (prefixed with REACT_APP_).

Performance & Optimizations

Deployment, Ecosystem & Developer Experience

• Next.js: First-class support on Vercel (zero-config), Docker, Node.js servers, static export. Edge runtime support. Actively developed by Vercel. TypeScript by default, Turbopack (dev), fast refresh, built-in ESLint/Prettier config, middleware, instrumentation.

• CRA: Static export only. No active development since 2022; React team recommends Vite, Next.js, or Remix for new projects. TypeScript via template, webpack (slow), fast refresh, requires eject for advanced config.

When to Choose Which

• Next.js: Any production application needing SEO, performance, authentication, or full-stack capabilities. Current default recommendation from React team.

• CRA: Legacy maintenance only. Not recommended for new projects.

How It Works

• create-next-app is the official CLI maintained by the Next.js team. Invoking it through npx downloads the latest version from the npm registry without a permanent global install.

• The CLI copies a minimal starter, installs dependencies with the detected or requested package manager, and writes the project files (app/, public/, next.config.js or next.config.ts, tsconfig.json, lockfile, etc.).

• The default scaffold uses the App Router (app/) and React Server Components. The Pages Router (pages/) is still supported but must be selected explicitly.

• In Next.js 15, npm run dev uses Turbopack by default.

Key Options

• --yes / -y: skip every prompt and accept the CLI’s built-in defaults.

• --typescript: explicitly enable TypeScript; JavaScript is the default when prompts are skipped.

• --eslint / --tailwind: enable ESLint or Tailwind CSS; both are opt-in.

• --app / --no-app: select App Router (default) or Pages Router.

• --src-dir: place application code under src/ instead of the repository root.

• --import-alias "@/*": customize the path alias; the default is @/*.

• --use-pnpm / --use-yarn / --use-npm: force a specific package manager for installation.

• --example <name>: bootstrap from an official example such as with-mongodb.

Common Usage Examples

Code Example

# Scaffold a new App Router project non-interactively with built-in defaults
npx create-next-app@latest my-next-app --yes

# Enter the project and start the development server
cd my-next-app
npm run dev

The dev server prints a URL, typically http://localhost:3000.

Best Practices

• Pin the version when you need reproducible scaffolding, e.g. npx create-next-app@15.2.0, because @latest can change between releases.

• Run the command outside any existing Git repository to avoid nested node_modules or conflicting configuration.

• Commit the generated lockfile (package-lock.json, yarn.lock, or pnpm-lock.yaml) so all contributors install identical dependencies.

• If your team needs a custom baseline (internal design system, auth, etc.), publish a private template and use --example-path or plain git clone rather than modifying the official CLI output.

• Run the interactive version once before scripting --yes, so you know which defaults your installed CLI version applies.

How SSR Works

• Request arrives: The Next.js server receives a request for a route.

• Server Components execute: The route’s Server Components run on the server and can await data fetching directly in the component body.

• HTML streams: React streams rendered HTML to the client in chunks, so the browser can paint before the full page resolves.

• Hydration: The client downloads the JavaScript bundle and attaches event listeners, making the static HTML interactive.

Static vs Dynamic Rendering

A route renders dynamically instead of statically when it: - Imports headers() or cookies() from next/headers - Reads the searchParams prop on a page - Calls unstable_noStore() (or stable noStore() in Next.js 15) from next/cache - Sets export const dynamic = 'force-dynamic' - Omits generateStaticParams for a dynamic route segment, so it is rendered on demand

Streaming and Suspense

Next.js automatically wraps route segments in Suspense boundaries. When a Server Component awaits a slow operation, React streams the fallback and sibling components first, then replaces the placeholder when the promise resolves. This keeps Time to First Byte low for personalized or data-heavy pages.

Server Components vs Client Components

• Server Components: Run only on the server, send no JavaScript bundle, and are ideal for data fetching and heavy libraries.

• Client Components: Marked with 'use client', hydrated on the client, and required for useState, useEffect, and browser APIs.

• Import boundary: A Server Component can import a Client Component, but not the reverse; data flows down through props.

Best Practices

• Fetch data on the server instead of using useEffect plus fetch in Client Components.

• Opt into caching deliberately with export const revalidate = 60 or export const dynamic = 'force-static'.

• Wrap slow sections in <Suspense> with meaningful fallbacks.

• Keep Client Components minimal and add 'use client' only when interactivity is required.

• Handle mutations in Route Handlers (app/api/.../route.ts) or Server Actions, not inside page components.

• Remember that params is synchronous in Next.js 14 but becomes a Promise in Next.js 15.

How It Works

• File-system routing: pages/index.tsx maps to /, pages/about.tsx to /about, and pages/blog/[slug].tsx to dynamic routes such as /blog/my-post; nested folders create nested routes.

• Rendering modes: Export getStaticProps for static generation with data, or getServerSideProps for server-side rendering on every request. A page without either is still pre-rendered to static HTML at build time (static generation with no props); true client-side rendering occurs only when the page fetches data in the browser using useEffect, SWR, or React Query.

• Automatic code splitting: Each page loads only its own JavaScript bundle.

• API routes: Files under pages/api/ become serverless endpoints, for example pages/api/users.ts serves /api/users.

Key Files and Conventions

• _app.tsx: Wraps every page; used for global layout, context providers, and state that persists across navigations.

• _document.tsx: Customizes the server-rendered HTML shell (<html>, <body>); it does not run in the browser.

• _error.tsx: Fallback UI for server-rendered errors.

• 404.tsx and 500.tsx: Explicit not-found and server-error pages.

• _middleware.ts (Next.js 12+): Runs before a request completes and can rewrite, redirect, or modify request/response headers.

Data Fetching and Rendering

Incremental Static Regeneration

• Add revalidate: 60 to the object returned by getStaticProps to regenerate the page in the background at most once every 60 seconds.

• On-demand revalidation can be triggered from API routes using res.revalidate('/path') (Next.js 12+).

Transition to App Router

• The App Router (app/) introduces React Server Components, nested layouts, streaming, and Server Actions.

• Both routers can coexist during migration; app/ takes precedence when routes overlap.

• Start new projects with app/; keep pages/ for existing routes or cases where Pages Router patterns remain preferable.

Best Practices and Common Pitfalls

• Prefer getStaticProps with ISR for public content to minimize time to first byte and leverage CDN caching.

• Reserve getServerSideProps for per-request needs such as authentication or user-specific data.

• Return only serializable values from getStaticProps and getServerSideProps; Date objects and class instances will break serialization.

• Always provide fallback in getStaticPaths; without it, dynamic routes not generated at build time return 404.

• Do not mix router APIs: next/router belongs to the Pages Router, while next/navigation belongs to the App Router.

• Avoid slow external calls in getStaticProps that block the build; use ISR or background jobs instead.

How Rendering Modes Work

• dynamic: 'auto' (default): Next.js inspects the page for dynamic data sources. If none are found, it prerenders HTML at build time and caches it.

• dynamic: 'force-dynamic': Build-time prerendering is disabled; the server renders the page on every request.

• dynamic: 'force-static': Forces static generation even when dynamic APIs are present, and throws if request-time data is actually required.

Configuring force-dynamic

• Add export const dynamic = 'force-dynamic'; at the top of app/<route>/page.tsx, outside any component function.

• The export overrides automatic detection, so a page that looks static still renders per request.

• Placing it in a layout.tsx applies the same behavior to all nested pages.

• It is the App Router counterpart to the Pages Router getServerSideProps.

Alternative Dynamic Triggers

• Uncached fetch: In Next.js 15, fetch defaults to no-store, so a server-component fetch already makes the route dynamic. Passing { cache: 'no-store' } explicitly documents the intent.

• Request APIs: Awaiting headers() from next/headers or cookies() from next/cookies forces dynamic rendering because their values vary per request.

• Explicit is better: Implicit triggers can be missed during maintenance; use force-dynamic when the contract is “always render on the server.”

Code Example

// app/dashboard/page.tsx
import { headers } from 'next/headers';

// Render on the server for every request; do not emit static HTML
export const dynamic = 'force-dynamic';

async function getUserData() {
  // Next.js 15: headers() returns a promise. Awaiting it is also safe in Next.js 14.
  const headersList = await headers();
  const auth = headersList.get('authorization') ?? '';

  const res = await fetch('https://api.example.com/user', {
    headers: { Authorization: auth },
    cache: 'no-store', // explicit uncached fetch
  });

  if (!res.ok) {
    throw new Error('Failed to fetch user data');
  }

  return res.json();
}

export default async function DashboardPage() {
  const user = await getUserData();

  return (
    <div>
      <h1>Welcome, {user.name}</h1>
      <p>Last updated: {new Date().toISOString()}</p>
    </div>
  );
}

Performance and Best Practices

• Reserve for truly dynamic pages: authentication dashboards, user-specific feeds, or real-time data. Keep marketing pages and blog posts static.

• Expect higher TTFB and compute: because the page cannot be served from a static or edge cache, each request costs server rendering time.

• Keep server components server-only: do not add 'use client' to the page itself unless you need browser APIs. A client component cannot directly read headers() or cookies() at render time; fetch data in the server component and pass it down as props.

• Stream heavy UI: wrap slow dynamic sections in `<Suspense>` so the shell ships early while remaining content streams.

• Do not rely on revalidate for per-request rendering: revalidate controls incremental static regeneration; use force-dynamic when you need every request to be fresh.

Supported File Extensions

Next.js natively accepts the following extensions for page components and route handlers: - .js: Standard JavaScript files. Next.js enables JSX syntax within .js files by default, so you do not need .jsx strictly, though it is supported. - .jsx: Explicitly marks the file as containing JSX syntax. Useful for clarity in JavaScript-only projects. - .ts: Standard TypeScript files. Allows JSX syntax similar to .js. - .tsx: Explicitly marks the file as TypeScript containing JSX. This is the most common choice for typed components.

Files with other extensions (such as .html, .php, or .mjs) are not treated as Next.js pages by default and would require custom server configuration or middleware to serve.

App Router vs Pages Router

The extension rules apply similarly across both routing systems, but the directory structure differs: - App Router: Files reside in the app/ directory. A page is defined by page.tsx (e.g., app/about/page.tsx). - Pages Router: Files reside in the pages/ directory. A page is defined by the filename itself (e.g., pages/about.tsx).

When using the App Router, special files like layout.tsx, loading.tsx, and error.tsx also adhere to these same extension rules. Route Handlers (route.ts) follow the same pattern.

TypeScript Configuration

To use .ts or .tsx extensions, TypeScript must be installed in the project. Next.js automatically creates a tsconfig.json file if you create a TypeScript file during development. Key requirements include: - The typescript package must be present in devDependencies. - The tsconfig.json is typically auto-generated by Next.js, ensuring correct JSX transformation settings without manual intervention. - Strict mode is recommended but optional.

If you attempt to use TypeScript extensions without the compiler installed, the build process will fail with a module resolution error.

Best Practices

• Consistency: Choose one extension style (either .js/.jsx or .ts/.tsx) and stick with it across the project to prevent confusion.

• Prefer .tsx: In modern Next.js development, .tsx is recommended because it enables type checking for props and state, reducing runtime errors.

• Avoid Mixing: Do not mix .js and .jsx arbitrarily; while supported, it complicates linting and editor configuration.

• Server Components: Remember that in the App Router, files are Server Components by default. Use 'use client' at the top of .tsx files only when browser APIs or state are needed.

Common Pitfalls

• Incorrect Extension: Using .typescript or .jsb will cause the file to be ignored by the router.

• Missing ‘use client’: Using React hooks like useState in a .tsx page without the directive will throw a server-side rendering error.

• Case Sensitivity: File extensions are case-sensitive on Linux deployments; ensure .tsx is lowercase.

File Loading and Substitution

• Next.js automatically reads .env* files from the project root.

• Effective priority is .env.local > .env.development.local / .env.production.local / .env.test.local > .env.

• .env.local holds local overrides and must be gitignored; .env holds shared defaults checked into version control.

• In development, variables are read when the dev server starts, and modifying .env.local restarts the server.

• In production, values are normally inlined into the server bundle at build time; some hosting platforms can inject runtime variables, but that is platform-specific and does not automatically make them client-accessible.

Server vs Client Exposure

• NEXT_PUBLIC_ prefix: the value is compiled into both server and client bundles, so it is available in Server Components, Route Handlers, middleware, and Client Components. Use it for public data such as analytics IDs, public API URLs, or feature flags.

• No prefix: the value is available only in server-runtime code—Server Components, Route Handlers, server-side utilities, and middleware. Database URLs, private keys, and internal secrets belong here.

• Client-side fallback: reading an unprefixed variable in a Client Component resolves to undefined at build time rather than throwing, so mistakes can fail silently.

• Server Components are not automatically safe: a secret read on the server must never be rendered into JSX or passed as a prop to a Client Component, because the generated HTML is sent to the browser.

Access Patterns

• Read every variable with process.env.VAR_NAME; all values arrive as strings.

• Server Components: may read any variable during rendering or data fetching, but must keep secrets out of rendered output.

• Route Handlers (app/api/.../route.ts): the preferred location for logic requiring private keys or database credentials, because the handler never ships to the browser.

• Client Components: must declare 'use client' and can only read NEXT_PUBLIC_* variables.

• Middleware: runs before routing and can read server-only variables for authentication or redirects; its runtime environment depends on configuration and deployment.

Security and Operational Best Practices

• Add .env.local to .gitignore and ship a .env.example containing placeholder names.

• Never prefix secrets, passwords, or private keys with NEXT_PUBLIC_.

• Parse strings explicitly, for example Number(process.env.PORT) or process.env.ENABLE_FEATURE === 'true'.

• Treat runtime-injected variables as server-only unless they carry the public prefix.

• Prefer Route Handlers or Server Actions over Client Components for any operation that requires a secret.

Legacy Context: Pages Router

In the Pages Router, Automatic Static Optimization (introduced in Next.js 9) meant that any page without getServerSideProps or getInitialProps was automatically treated as a static page and rendered to HTML during next build. Developers could still opt into static generation with getStaticProps, but the automatic behavior removed the need for explicit data methods for purely static pages. This hybrid approach allowed a single app to mix static and server-rendered pages. The Pages Router remains supported for maintenance, but new projects should use the App Router.

App Router: Static Rendering by Default

In the App Router, every Server Component is statically rendered by default unless it opts into dynamic behavior. During the build, Next.js renders the component to HTML and caches the result (including the React server component payload). Subsequent requests are served from the cache, often from a CDN edge, which dramatically reduces Time to First Byte (TTFB) and origin load. Standard fetch inside a Server Component also defaults to cache: 'force-cache', so data fetching participates in static generation unless told otherwise. No configuration flags are required—static rendering is the baseline.

What Triggers Dynamic Rendering

A component automatically shifts from static to dynamic when it uses APIs that require a request-time context. Common triggers include: - Request APIs: reading cookies, headers, or searchParams from next/headers or next/navigation. - Uncached data: calling fetch with cache: 'no-store' or using noStore() from next/cache. - Non-deterministic values: invoking Date.now(), Math.random(), or crypto.randomUUID() in the component body. - Explicit opt-out: setting export const dynamic = 'force-dynamic' in a layout or page file.

This automatic detection replaces the manual method selection (getStaticProps vs getServerSideProps) of the Pages Router.

Incremental Static Regeneration (ISR)

Static content can be refreshed after the build using ISR. You can set a revalidation interval at the segment level with export const revalidate = 3600 (seconds) in a page.tsx or layout.tsx, or per-fetch with fetch(url, { next: { revalidate: 3600 } }). On the first request after the interval expires, Next.js serves the stale page while regenerating it in the background, then caches the fresh version. Setting revalidate: 0 disables regeneration and keeps the page static forever.

Comparison: Pages Router vs App Router Static Generation

Best Practices

• Default to static: Build as much of the app as static to maximize CDN caching and minimize TTFB.

• Introduce dynamic APIs deliberately: Only read cookies, headers, or searchParams when the UI truly depends on them.

• Use ISR for changing data: Prefer revalidate over forcing every request to be dynamic when data changes on a known schedule.

• Audit accidental dynamic rendering: A single Date.now() or uncached fetch can make an entire segment dynamic, negating caching benefits.

• Explicitly declare intent: When a segment must always be dynamic, set export const dynamic = 'force-dynamic' rather than relying on implicit triggers.

Core Mapping Mechanism

• The router walks app and treats each folder as one URL segment.

• app/page.tsx renders /; app/dashboard/settings/page.tsx renders /dashboard/settings.

• A folder only contributes a URL segment when it or a descendant contains a page.tsx or route.ts; a folder with only layout.tsx groups child routes but is not itself addressable.

• Nested folders create nested URLs and allow parent layout.tsx, loading.tsx, and error.tsx to wrap child segments, sharing UI and data-fetching boundaries.

Special File Conventions

Dynamic and Catch-All Segments

• [id] matches one segment, e.g. app/blog/[slug] serves /blog/hello.

• [...path] matches one or more segments; [[...path]] matches zero or more and makes the segment optional.

• Parameters arrive through the params prop on page.tsx, layout.tsx, and route.ts. In Next.js 15 params is a Promise and must be awaited.

• searchParams is passed to page.tsx as a Promise containing the parsed query string.

Best Practices and Common Pitfalls

• Server Components by default: Keep data fetching in app components and mark only interactive UI with 'use client'.

• Layout persistence: Nested layouts remain mounted when navigating between sibling pages, so put shared state and providers in the closest common layout.

• Route groups: Wrap a folder name in parentheses, e.g. (auth)/login/page.tsx, to organize files without adding a URL segment.

• Route priority: At the same level, static segments beat dynamic segments, and dynamic beats catch-all. A static about folder and a dynamic [slug] folder can coexist; about wins. Avoid two dynamic segments at the same level because they conflict.

• No pages mixing: In an App Router project, do not rely on getServerSideProps or getStaticProps; those belong to the Pages Router.

How Dynamic Routes Work

Dynamic routes are created by wrapping folder names in square brackets within the app directory. For example, app/blog/[slug]/page.tsx matches /blog/hello and exposes slug as a parameter. Catch-all segments use [...slug] for required arrays and [[...slug]] for optional arrays, allowing flexible URL structures like /blog/a/b.

Accessing Params in Server Components

Page components are Server Components by default. The params prop is a Promise that resolves to an object containing the dynamic segment values. You must await it before using the values. Route Handlers (app/api/.../route.ts) also receive params as a Promise in the context object (the second argument), enabling dynamic logic in API endpoints.

Accessing Params in Client Components

If a component requires browser APIs or state, it must include the 'use client' directive. Inside such components, URL parameters are retrieved using the useParams hook from next/navigation. This hook returns the params object directly (not a Promise) after hydration, meaning values may be undefined during the initial server render of the client component.

Code Example

The following Server Component awaits params to access slug, while the Client Component uses the navigation hook.

// app/blog/[slug]/page.tsx (Server Component)
export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  return <h1>Blog Post: {slug}</h1>;
}

// app/blog/[slug]/ClientDisplay.tsx (Client Component)
'use client';
import { useParams } from 'next/navigation';

export default function ClientDisplay() {
  const params = useParams<{ slug: string }>();
  return <p>Client sees: {params.slug}</p>;
}

Best Practices and Common Pitfalls

• Type Safety: Explicitly type the params Promise in Server Components and the generic in useParams to catch errors early.

• Encoding: URL segments are decoded automatically, but validate input before using it in database queries to prevent injection.

• Client vs Server: Avoid fetching data based on params in Client Components if possible; prefer passing data from the Server Component to reduce waterfalls.

• Catch-all Types: Remember that catch-all params return arrays, not strings, so type them as string[].

• Hydration Mismatch: Do not rely on useParams for critical SEO content since it is unavailable during server rendering.

• Async Params: In Next.js 15, params is a Promise in Server Components and Route Handlers; always await it. This is a change from Next.js 14 where params was synchronous.

Syntax and File Structure

• Create a folder named [...slug] inside app to capture one or more segments: app/blog/[...slug]/page.tsx matches /blog/a, /blog/a/b, and deeper.

• Use double brackets [[...slug]] for an optional catch-all that also matches the parent route /blog.

• The folder name becomes the key in params, and its position in the directory tree determines the URL prefix it matches.

• The page file must be named page.tsx and sits inside the catch-all folder.

Accessing Route Parameters

• In Next.js 15 the params prop is asynchronous, so you must await it before reading values.

• A required catch-all always supplies slug: string[]; an optional catch-all supplies slug?: string[], which is undefined when the parent path is matched.

• Because the value is an array, validate its contents before using it in queries or rendering.

Rendering and Caching

• Dynamic segments are rendered dynamically at request time unless you pre-render them with generateStaticParams.

• If you omit generateStaticParams, Next.js does not build HTML for those paths at build time.

• That function returns an array of params objects; requests matching a pre-generated param are served statically, while unmatched params fall back to dynamic rendering.

• You can combine it with revalidate to enable Incremental Static Regeneration for known routes.

Optional vs Required Catch-All

Code Example

// app/blog/[[...slug]]/page.tsx
export async function generateStaticParams() {
  // Pre-render known slugs at build time; other slugs render dynamically.
  return [{ slug: ['react'] }, { slug: ['next', 'js'] }];
}

export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
  const { slug } = await params;

  if (!slug) {
    return <div>Blog Home</div>;
  }

  return <div>Slug segments: {slug.join('/')}</div>;
}

Best Practices and Common Pitfalls

• Validate Input: Treat params as untrusted data; check array contents before database access.

• Handle Missing Params: For optional catch-alls, guard against undefined instead of assuming an array.

• Pre-render Known Routes: Use generateStaticParams when possible to reduce server load and improve SEO.

• Await Params: Forgetting await params in Next.js 15 causes type errors or undefined values.

• Avoid Route Conflicts: Do not place a catch-all folder alongside a conflicting dynamic segment in the same directory; specific matches take priority.

• Keep Logic on the Server: Only add 'use client' when the component needs state, effects, or browser APIs.

How It Works

• Build-time execution: getStaticProps runs during next build (or during revalidation) on the server, never in the browser.

• Return value: The function must return an object with a props key containing serializable data that becomes the page component’s props.

• Optional keys: revalidate (seconds) enables Incremental Static Regeneration (ISR); notFound: true triggers a 404; redirect sends the user elsewhere.

• Context parameter: Receives params (for dynamic routes), preview, previewData, and locale/locales for i18n.

When to Use It

• Content-heavy pages that change infrequently: marketing pages, blog posts, documentation, product catalogs.

• SEO-critical pages where fully rendered HTML at request time improves crawlability.

• High-traffic pages where serving static HTML from a CDN reduces server load and latency.

• Data from headless CMSs, databases, or APIs that can be queried at build time.

Comparison with App Router Equivalent

Code Example (Pages Router)

// pages/blog/[slug].tsx
import type { GetStaticProps, GetStaticPaths, GetStaticPropsContext } from 'next';

interface Post { slug: string; title: string; content: string; }
interface Props { post: Post; }

export const getStaticPaths: GetStaticPaths = async () => {
  const res = await fetch('https://cms.example.com/posts');
  const posts: Post[] = await res.json();
  const paths = posts.map(p => ({ params: { slug: p.slug } }));
  return { paths, fallback: 'blocking' };
};

export const getStaticProps: GetStaticProps<Props> = async ({ params }: GetStaticPropsContext) => {
  const slug = params?.slug as string;
  const res = await fetch(`https://cms.example.com/posts/${slug}`);
  if (!res.ok) return { notFound: true };
  const post: Post = await res.json();
  return { props: { post }, revalidate: 60 }; // ISR every 60s
};

export default function BlogPost({ post }: Props) {
  return (
    <article>
      <h1>{post.title}</h1>
      {/* Render plain text; sanitize HTML from untrusted sources instead of using dangerouslySetInnerHTML */}
      <p>{post.content}</p>
    </article>
  );
}

Best Practices and Pitfalls

• Keep payloads small: Only return data the component actually needs; large props increase HTML size and build time.

• Use ISR for freshness: Set revalidate (or fallback: 'blocking') instead of rebuilding the entire site on content changes.

• Handle errors gracefully: Return notFound: true for missing records so Next.js shows the 404 page.

• Avoid client-only APIs: Code inside getStaticProps runs in Node.js; window, localStorage, or browser-specific libraries will throw.

• Sanitize rich content: If your CMS returns HTML, sanitize it with a library such as DOMPurify before rendering; never pass untrusted HTML straight to dangerouslySetInnerHTML.

• Migrate to App Router for new projects: The App Router’s Server Components and fetch caching provide the same SSG/ISR benefits with a simpler mental model and streaming support.

How It Works

• Server-only execution: The function runs during the request lifecycle on the server and is never included in the browser bundle.

• Context object: It receives a context argument with params for dynamic route segments, query for URL query parameters, req for the incoming HTTP request, and res for the response.

• Return shape: It must return an object containing props, which are passed to the page component. It can also return redirect or notFound to control routing.

Rendering Strategy

• Request-time rendering: Unlike static generation, HTML is generated on every request, so the page can reflect user-specific or rapidly changing data.

• SEO and initial paint: Because the server sends fully rendered HTML, search engines and clients receive meaningful content before hydration completes.

• Performance trade-off: The server must finish data fetching before responding, so Time to First Byte is typically higher than with static generation.

App Router Equivalent

In the App Router (app/ directory), getServerSideProps does not exist. Data is fetched directly inside async React Server Components. By default, server components and fetch calls are statically cached. To achieve per-request SSR-like behavior, opt into dynamic rendering with dynamic = 'force-dynamic', call unstable_noStore() from next/cache, or set revalidate: 0. Route Handlers (app/api/.../route.ts) replace Pages Router API routes, and Server Actions handle mutations.

Best Practices

• Prefer static generation when possible: If content does not change per request, use getStaticProps with revalidation to reduce server load and improve response time.

• Keep server logic server-side: Never reference window, document, or localStorage inside getServerSideProps; it runs in a Node.js environment.

• Handle external failures: Wrap API and database calls in try/catch so a failed dependency returns an error page or fallback instead of crashing the request.

• Use types: Import GetServerSideProps and GetServerSidePropsContext from next to catch mismatched props and context shapes at compile time.

• Plan migration: For new projects, use the App Router, where data fetching is expressed through async components and caching options rather than special prop functions.

How ISR Works in the App Router

In the App Router, caching and revalidation are attached to data fetching and page exports rather than page-level methods like getStaticProps. When a Server Component fetches data with revalidate, Next.js caches the result for that many seconds. After the interval expires, the next request serves the stale page while regenerating it in the background, then caches the fresh result.

Page-Level vs Data-Fetching Revalidation

• export const revalidate = 60: Set in page.tsx or layout.tsx to revalidate the whole page every 60 seconds; this is the simplest page-level ISR configuration.

• fetch(url, { next: { revalidate: 60 } }): Scopes revalidation to a single data source, allowing different intervals for different APIs.

• cache: 'no-store' or export const dynamic = 'force-dynamic': Either makes the page fully dynamic, disabling ISR for that request or page.

Dynamic Routes and Parameters

For dynamic segments such as /blog/[slug], use generateStaticParams to list paths that should be pre-rendered at build time. The dynamicParams export then governs requests that match the route but are not in that list: - true: Renders the page on demand when first requested, which is the ISR behavior for unknown params. - false: Returns a 404 for params not returned by generateStaticParams.

Default Fetch Behavior

By default, fetch in Server Components uses cache: 'force-cache', so responses are cached indefinitely unless you specify revalidate. If you need fresh data on every request, use cache: 'no-store' instead of a revalidation interval.

Code Example

// app/blog/[slug]/page.tsx
import { notFound } from 'next/navigation';

// Revalidate the entire page every 60 seconds (ISR)
export const revalidate = 60;

// Render unknown slugs on demand instead of returning 404
export const dynamicParams = true;

export async function generateStaticParams() {
  const res = await fetch('https://api.example.com/posts');
  const posts = await res.json();
  return posts.map((post) => ({ slug: post.slug }));
}

async function getPost(slug: string) {
  const res = await fetch(`https://api.example.com/posts/${slug}`, {
    next: { revalidate: 60 }, // ISR for this data source
  });

  if (!res.ok) {
    notFound();
  }

  return res.json();
}

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  // In Next.js 15, params is a Promise and must be awaited
  const { slug } = await params;
  const post = await getPost(slug);

  return (
    <article>
      <h1>{post.title}</h1>
      <p>{post.body}</p>
    </article>
  );
}

Best Practices and Pitfalls

• Choose Revalidate Wisely: Set revalidate based on data volatility; a news feed might use 10 seconds, while documentation could use 3600.

• Expect Stale Content Briefly: Background regeneration means a visitor may see slightly stale content during the revalidation window.

• Keep Secrets Server-Side: Never expose API keys in generateStaticParams or fetch URLs; keep all logic inside Server Components.

• Watch dynamicParams Load: Setting dynamicParams = true can cause origin traffic spikes if many unknown URLs are hit at once; consider a CDN or rate limiting.

• Use App Router APIs: Pages Router methods such as getStaticProps and getStaticPaths are not available in the App Router; use generateStaticParams and revalidate instead.

App Router Route Handlers

• File placement: A file named route.ts (or .js) in any folder under app/ becomes a route; app/api/items/route.ts serves /api/items.

• HTTP methods: Export GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS as async functions.

• Dynamic segments: app/api/items/[id]/route.ts captures params.id; in Next.js 15 params is a Promise and must be awaited.

• Reading input: Use request.json(), request.formData(), request.text(), request.blob(), or request.nextUrl.searchParams.

• Writing output: NextResponse.json(data, { status }), NextResponse.redirect(url), NextResponse.rewrite(url), or new Response(body, init).

• Caching: Route handlers are dynamic by default (rendered per request). Use export const revalidate = 60 for ISR-style caching, export const dynamic = 'force-static' for fully static output, or export const dynamic = 'force-dynamic' to guarantee per-request rendering.

Pages Router API Routes (Legacy)

• Files under pages/api/ export a single default handler: export default function handler(req, res).

• req and res are extended Node.js http.IncomingMessage and http.ServerResponse objects.

• Still supported, but new projects should use App Router Route Handlers or Server Actions.

Server Actions as an Alternative

• For mutations started in client components, mark a function with 'use server' and call it directly from a form or event handler.

• They execute on the server, integrate with Next.js caching and revalidation, and avoid manual fetch calls and explicit endpoint files.

Code Example

// app/api/items/route.ts
import { NextRequest, NextResponse } from 'next/server';

// Guarantee per-request rendering instead of static caching
export const dynamic = 'force-dynamic';

export async function GET(request: NextRequest) {
  const limit = Number(request.nextUrl.searchParams.get('limit') ?? '10');
  if (Number.isNaN(limit) || limit <= 0) {
    return NextResponse.json({ error: 'Invalid limit' }, { status: 400 });
  }
  const items = await fetchItems(limit); // replace with your data layer
  return NextResponse.json(items);
}

export async function POST(request: NextRequest) {
  const body = await request.json();
  // Validate the payload with a schema such as Zod before using it
  const created = await createItem(body);
  return NextResponse.json(created, { status: 201 });
}

export async function PUT(request: NextRequest) {
  const body = await request.json();
  const updated = await updateItem(body.id, body);
  if (!updated) return NextResponse.json({ error: 'Not found' }, { status: 404 });
  return NextResponse.json(updated);
}

export async function DELETE(request: NextRequest) {
  const id = request.nextUrl.searchParams.get('id');
  if (!id) return NextResponse.json({ error: 'Missing id' }, { status: 400 });
  await deleteItem(id);
  return new NextResponse(null, { status: 204 });
}

// app/api/items/[id]/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function GET(
  _request: NextRequest,
  { params }: { params: Promise<{ id: string }> }
) {
  const { id } = await params;
  const item = await fetchItem(id); // replace with your data layer
  if (!item) return NextResponse.json({ error: 'Not found' }, { status: 404 });
  return NextResponse.json(item);
}

Best Practices and Common Pitfalls

• Prefer Server Actions for form submissions and client-initiated mutations; they reduce boilerplate and include CSRF protection.

• Validate and sanitize every input (query params, headers, body) with a schema library like Zod.

• Set caching explicitly: force-dynamic for personalized data, revalidate for public data that changes periodically, default dynamic for most API endpoints.

• Handle errors with try/catch and return meaningful status codes; never let unhandled rejections reach the client.

• Use NextResponse helpers for JSON, redirects, and rewrites instead of hand-building Response objects.

• Authenticate with middleware or handler-level checks; do not rely on URL obscurity.

• Offload long-running work to background jobs and return 202 Accepted instead of blocking the request.

• Keep client-only code out of Route Handlers; they run only on the server and cannot import browser APIs or hooks.

Conceptual Relationship

• CSS-in-JS Paradigm: A methodology where styles are written in JavaScript rather than external CSS files, enabling dynamic styling, scoping, and logic integration.

• styled-components Library: A popular implementation of CSS-in-JS that uses tagged template literals to generate unique class names and inject styles into the DOM at runtime.

• Distinction: You can practice CSS-in-JS using other libraries (like Emotion) or built-in solutions (like CSS Modules), whereas styled-components is a specific dependency with its own configuration requirements.

App Router Integration

In Next.js 14+ with the App Router, styled-components can be used in both Server and Client Components when the SWC compiler is enabled. - Compiler Support: Enable compiler: { styledComponents: true } in next.config.js. This allows styled-components to be used in Server Components by extracting styles at build time, eliminating the need for a client-side runtime in many cases. - Client Components: Without the compiler, or for highly dynamic styles that require runtime injection, components using styled must include the 'use client' directive. - SSR Handling: The compiler automatically extracts critical CSS during server rendering, preventing flash of unstyled content (FOUC) without manual StyleSheetManager setup. - Server Components: Can directly render styled-components when the compiler is active; they do not need to be wrapped in a Client Component boundary.

Comparison with Alternatives

Best Practices and Pitfalls

• Enable the Compiler: Set compiler: { styledComponents: true } in next.config.js for optimal SSR performance, smaller client bundles, and Server Component compatibility.

• Minimize Client Bundle: Use Server Components for static styled-components; only add 'use client' when browser APIs or dynamic theming require runtime injection.

• Migration: Replace Pages Router _document.js SSR logic with the App Router compiler; no custom provider is needed for basic SSR.

• Performance: Prefer CSS Modules or Tailwind for purely static styles to avoid any runtime overhead; reserve styled-components for dynamic, state-driven styling.

• Theming: Use ThemeProvider from styled-components for complex theme switching to leverage the library’s context system, but consider CSS variables for simpler cases to reduce provider nesting.

How Global Styles Work in App Router

In the App Router architecture, there is no _app.js file like in the Pages Router. Instead, the root layout (app/layout.tsx) acts as the wrapper for all child pages. Importing a CSS file here makes it global because the layout persists across navigation and wraps all route segments. The stylesheet is bundled during the build process and injected into the document head automatically.

Implementation Steps

1. Create a CSS file, typically named globals.css, inside the app directory.

2. Import this file at the top of app/layout.tsx.

3. Ensure the import statement appears before any JSX return logic.

4. Avoid importing global styles inside nested components unless scoped intentionally, as this can lead to duplication or specificity conflicts.

Code Example

Below is the standard configuration for global styles using the App Router.

/* app/globals.css */
:root {
  --foreground-rgb: 0, 0, 0;
  --background-rgb: 255, 255, 255;
}

body {
  color: rgb(var(--foreground-rgb));
  background-color: rgb(var(--background-rgb));
  margin: 0;
  padding: 0;
}

// app/layout.tsx
import './globals.css';
import type { Metadata } from 'next';

export const metadata: Metadata = {
  title: 'My App',
  description: 'Generated by create next app',
};

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

Best Practices and Considerations

• Use CSS Variables: Define theme colors and spacing in :root within the global file to maintain consistency.

• Prefer Utility Classes: Consider using Tailwind CSS via className props instead of raw global CSS to reduce conflicts.

• Avoid Overuse: Global styles should handle resets and base typography; component-specific styles should remain scoped (e.g., CSS Modules).

• Server Components: The root layout is a Server Component by default, so importing CSS here does not require the 'use client' directive.

• Third-Party Libraries: If using a UI library that requires global styles (like Bootstrap), import them here rather than in individual pages.

Common Pitfalls

• Importing in Page Components: Importing global CSS inside page.tsx files defeats the purpose of caching and can cause flash of unstyled content (FOUC) during navigation.

• Specificity Conflicts: Global styles can override component-scoped styles unexpectedly; use specific selectors or utility classes to mitigate this.

• Missing Reset: Forgetting a CSS reset in the global file often leads to inconsistent spacing across browsers.

Core Optimization Features

• On-Demand Resizing: Images are resized at request time to the dimensions specified by width, height, or fill plus sizes, so the browser never downloads a larger file than needed.

• Automatic Format Conversion: The optimizer inspects the browser’s Accept header and serves WebP by default; AVIF can be enabled by adding it to images.formats in next.config.js.

• Lazy Loading: loading="lazy" is the default, deferring offscreen images and reducing initial page weight and Time to Interactive.

• Responsive srcSet: Combined with the sizes prop, the component generates multiple resolutions so the browser selects the best one for the viewport and device pixel ratio.

Preventing Cumulative Layout Shift

• Unlike a plain <img>, next/image normally requires explicit width and height in pixels so the browser reserves the correct aspect ratio before the image loads.

• When dimensions are unknown or full coverage is needed, use fill on the image and a positioned parent, such as position: relative, to reserve space.

• Mark only Largest Contentful Paint images with priority; this disables lazy loading and loads them eagerly.

Handling Local and Remote Assets

• Local assets: Place files in public and reference them with an absolute path, or import them directly. Both are optimized; public is simpler for dynamic paths, while imports give type safety and bundler tracking.

• Remote assets: External URLs must be allowlisted in next.config.js via images.remotePatterns, which matches protocol, hostname, port, and pathname patterns. The older images.domains option is still supported, but remotePatterns is the recommended approach.

• Opt-out: Use unoptimized={true} when an image is already optimized or served by an external CDN that should handle resizing.

Additional Asset Features

• Placeholders: Use placeholder="blur" with blurDataURL to show a low-resolution preview while the full image loads; placeholder="empty" shows nothing.

• Quality and Caching: Adjust quality, which defaults to 75, and rely on the optimizer’s cache keys; stale images are revalidated based on the configured cache settings.

• Accessibility: alt is a required prop, ensuring screen readers have descriptive text and avoiding build-time errors in strict TypeScript configurations.

Best Practices and Common Pitfalls

• Do not mark every image as priority; doing so defeats lazy loading and can hurt Core Web Vitals.

• Always pair fill with a positioned parent, otherwise the image may render with zero size.

• Avoid the legacy layout prop, which was removed in Next.js 13; use width/height or fill with CSS instead.

• For external images, prefer remotePatterns over domains because it supports protocol and pathname restrictions.

• Test images on slow networks: priority images should be the only ones loading above the fold.

Automatic Prefetching with Link

The <Link> component from next/link handles prefetching automatically in the App Router. When a <Link> component enters the viewport, Next.js fetches the React Server Components (RSC) payload for the destination route. This behavior is enabled by default (prefetch={true}), meaning developers do not need to add extra attributes for standard navigation links. The fetched data is stored in the router cache, allowing for an instant transition when the user eventually clicks the link.

Manual Prefetching with useRouter

For scenarios where navigation is triggered by events other than clicking a visible link, such as hovering over a card or completing a form step, manual prefetching is available. The useRouter hook from next/navigation exposes a prefetch method. Because this hook interacts with browser-side router state, any component using it must include the 'use client' directive. This allows developers to proactively load data based on user behavior patterns that <Link> might not capture automatically.

Prefetching Behavior and Caching

Prefetching in the App Router fetches the route segment data rather than the entire JavaScript bundle. The cached data persists based on the route’s rendering strategy. Static routes remain cached indefinitely until revalidated, while dynamic routes may have shorter cache lifetimes depending on fetch caching options or revalidate settings. If a route is marked as dynamic, prefetching still occurs but the data might be refetched upon navigation if the cache expires. Developers should note that prefetching consumes bandwidth, so aggressive prefetching on data-heavy routes should be balanced against performance budgets.

Best Practices and Pitfalls

• Avoid Over-Prefetching: Prefetching every possible route can waste bandwidth and slow down the initial page load. Prioritize high-probability navigation paths.

• Respect Data Sensitivity: Do not prefetch routes containing sensitive user data unless authentication is confirmed, as the payload may be cached locally.

• Disable When Unnecessary: Use prefetch={false} on <Link> components for unlikely destinations (e.g., logout buttons) to conserve network resources.

• Server Actions: Remember that prefetching loads the route UI, not the results of Server Actions triggered within that route. Actions execute upon submission.

By leveraging both automatic and manual prefetching strategies, developers can ensure smooth transitions while maintaining efficient resource usage in Next.js applications.

Zero-Configuration Deployment

Vercel detects Next.js projects automatically during git pushes or CLI deployments. There is no need to write complex CI/CD pipelines or configure web servers like Nginx to handle rewrites and headers. The platform maps the App Router structure (app/page.tsx) directly to serverless or edge functions based on rendering requirements defined by fetch caching options. This reduces operational overhead significantly compared to generic cloud providers where you must manage container orchestration or server instances manually to achieve similar routing behavior.

Performance and Asset Optimization

Vercel deploys applications to a global edge network located physically close to users. Static assets and prerendered pages are cached at the edge, reducing latency for repeat visits. For dynamic content, Next.js Server Components can be rendered at the edge using Edge Functions. This architecture supports streaming responses, improving Time to First Byte (TTFB). Additionally, the next/image optimizer is included and scales automatically, whereas other platforms often require external loaders or storage buckets. Similarly, next/font self-hosts fonts at build time, eliminating layout shifts without extra configuration.

Workflow and Feature Parity

Every pull request generates a unique preview URL with a fresh deployment instance, allowing stakeholders to test changes in isolation. Environment variables can be managed per branch context, ensuring secrets are not hardcoded. Certain features rely on Vercel-specific infrastructure to function fully, such as ISR with revalidation tags (revalidateTag) which works seamlessly with the distributed cache invalidation system. Server Actions are also optimized for Vercel’s serverless runtime to prevent cold start latency, ensuring high reliability during form submissions and mutations.

Best Practices and Considerations

• Avoid Vendor Lock-In: While convenient, design critical business logic to remain portable across providers. Use standard Web APIs where possible.

• Monitor Costs: Serverless and edge invocations scale directly with traffic. Set budget alerts to prevent unexpected charges during sudden traffic spikes.

• Security: Never expose secret environment variables to the client. Vercel correctly distinguishes between public (NEXT_PUBLIC_) and private variables during the build process.

• Configuration: Use vercel.json only when overriding platform defaults. Prefer next.config.ts for framework-specific settings to maintain portability.

Deployment Platform Configuration

On Vercel, add the domain under Project Settings > Domains (e.g. app.example.com or example.com). Vercel then displays the DNS records you must create at your registrar and automatically provisions an HTTPS certificate once DNS resolves. The same pattern applies to Netlify, AWS Amplify, Cloudflare Pages, and similar platforms: attach the domain to the production deployment alias and let the platform manage TLS. For apex domains, Vercel supports CNAME flattening so you can point example.com without violating DNS standards.

DNS Record Setup

• Subdomain: Create a CNAME record pointing the subdomain to the provider’s domain, such as app.example.com → your-app.vercel.net.

• Apex domain: Use the provider’s IP addresses in an A record, or an ALIAS/ANAME record if the registrar supports it.

• Verification: Some providers require a TXT record for ownership verification before issuing the certificate.

• Propagation: Changes can take minutes to 48 hours; purge the CDN cache if stale content is served.

• HTTPS: Enforce HTTPS; Vercel redirects HTTP automatically once the certificate is active.

Image Optimization Allowlist

next/image only optimizes images from the same origin or from hosts listed in images.remotePatterns. If images are served from a separate custom domain or external CDN, add a pattern in next.config.ts: - protocol, hostname, port, and pathname are all filterable. - ** in hostname matches any number of subdomains; * matches one segment. - The older images.domains array is deprecated; use remotePatterns instead. Same-origin images served from the Next.js app’s own custom domain do not need a remote pattern.

Domain-Based Routing with Middleware

Middleware runs at the edge before rendering and can inspect request.nextUrl.hostname. This enables multi-tenant routing, A/B testing, or locale redirection without rebuilding: - Return NextResponse.rewrite() to render a different route while keeping the original URL. - Return NextResponse.redirect() to send the browser to another URL. - Return NextResponse.next() to continue normally. - Use export const config = { matcher: '/:path*' } to run on every route, or scope it to specific paths.

Code Example

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  images: {
    remotePatterns: [
      {
        protocol: 'https',
        hostname: '**.example.com', // matches any subdomain of example.com
        port: '',
        pathname: '/images/**',
      },
    ],
  },
};

export default nextConfig;

// middleware.ts
import { NextResponse } from 'next/server';
import type { NextRequest } from 'next/server';

export function middleware(request: NextRequest) {
  const hostname = request.nextUrl.hostname;

  if (hostname === 'tenant.example.com') {
    // Render the tenant dashboard while keeping the custom domain in the address bar.
    return NextResponse.rewrite(new URL('/tenant/dashboard', request.url));
  }

  return NextResponse.next();
}

export const config = { matcher: '/:path*' };

Common Pitfalls

• Apex DNS limits: Some registrars do not support ALIAS/ANAME; use the provider’s apex A records or move the domain to a DNS host that supports CNAME flattening.

• Stale CDN cache: During DNS propagation, edge nodes may still serve the old deployment; purge the cache in the provider dashboard.

• Overly broad remotePatterns: **.example.com allows every subdomain; restrict pathname and protocol to avoid unintended external image loading.

• Middleware matcher scope: A blanket /:path* matcher runs on static assets too; narrow it with /dashboard/:path* when possible to reduce edge compute.

• Mixed content: Ensure all assets and API calls use HTTPS, or browsers will block them on the custom domain.

Build Output Modes

Next.js offers distinct output modes tailored to different hosting environments. - Default (undefined): Optimized for Vercel; generates .next folder requiring specific serverless handling. - output: 'standalone': Copies only necessary files (including Node server) into .next/standalone. Ideal for Docker, EC2, ECS, or generic Node hosts. - output: 'export': Generates static HTML/CSS/JS. Disables SSR, API Routes, and Image Optimization (unless external). Suitable for pure static sites on Netlify, S3, or Cloudflare Pages.

Deploying to Netlify

Netlify supports Next.js via the @netlify/plugin-nextjs plugin, which handles serverless functions for SSR and API routes automatically. Do not use output: 'standalone' with this plugin. 1. Install the plugin: npm install @netlify/plugin-nextjs. 2. Create netlify.toml to configure the plugin and build command. 3. Connect your Git repository; Netlify runs the build command and the plugin processes the default .next output.

Deploying to AWS

AWS offers multiple paths depending on your infrastructure preference. - AWS Amplify Hosting: Fully managed; connects to Git and handles build commands (next build) and serverless functions similar to Vercel. - EC2/ECS with Docker: Use output: 'standalone'. Create a Dockerfile that copies .next/standalone and runs node server.js. This gives full control over scaling and networking. - Lambda: Use the Serverless Framework or AWS CDK with community plugins (e.g., serverless-next.js), though these are not officially maintained by Vercel and require careful cold-start management.

Code Example

Generic Node.js host (Docker, EC2, ECS) – next.config.ts

// next.config.ts
import type { NextConfig } from 'next';

const nextConfig: NextConfig = {
  output: 'standalone',
  reactStrictMode: true,
  images: {
    remotePatterns: [
      { protocol: 'https', hostname: 'example.com' },
    ],
  },
};

export default nextConfig;

Netlify – netlify.toml (use default output, no standalone)

# netlify.toml
[[plugins]]
package = "@netlify/plugin-nextjs"

[build]
command = "next build"

Best Practices and Pitfalls

• Image Optimization: Vercel’s default Image Optimization API may not work on all hosts. Configure loader: 'custom' with a CDN like Cloudinary or AWS CloudFront, or use remotePatterns to allow external sources.

• Incremental Static Regeneration (ISR): revalidate works on platforms supporting background regeneration (Netlify, Amplify), but pure static exports (output: 'export') do not support it.

• Middleware: Ensure your host supports Edge or Node.js runtime for Middleware. Netlify supports it via the plugin; AWS Lambda may require specific packaging.

• Cold Starts: On serverless AWS Lambda, cold starts can impact Time to First Byte (TTFB). Consider provisioned concurrency or container-based hosting for consistent performance.

• Environment Variables: Never commit secrets. Use platform-specific secret managers (AWS Secrets Manager, Netlify Environment Variables) and prefix client-side variables with NEXT_PUBLIC_.

Extensibility Architecture

Rather than loading plugins, Next.js allows customization via next.config.js for bundler settings and middleware.ts for request-level logic. The App Router emphasizes Server Components, so integrations must respect server-client boundaries. Libraries typically export components or providers that wrap the application root, while native features handle routing, caching, and rendering without external dependencies.

Common Third-Party Integrations

• Tailwind CSS: A utility-first CSS framework integrated via PostCSS, enabling rapid styling without leaving JSX. It requires configuring tailwind.config.ts and importing styles globally.

• Auth.js (formerly NextAuth.js): Provides authentication handlers and session management. Version 5 aligns better with the App Router using server-side helpers like auth().

• next-intl: Manages internationalization, offering message loading and locale routing compatible with Server Components.

• ESLint and Prettier: eslint-config-next includes rules specific to Next.js structures, while Prettier plugins ensure code formatting consistency across the project.

Native Middleware Capabilities

Middleware acts as the closest equivalent to a request-handling plugin. It executes code before a request is completed, allowing developers to modify incoming requests or outgoing responses. Common use cases include authentication checks, A/B testing, bot protection, and locale redirection. Middleware runs on the Edge Runtime, meaning it must avoid Node.js-specific APIs like fs or path.

Best Practices and Pitfalls

• Verify App Router Compatibility: Many older libraries target the Pages Router. Confirm support for Server Components before installing to avoid hydration errors.

• Minimize Middleware Logic: Since middleware runs on every matched request, heavy computation increases latency. Keep logic lightweight and edge-compatible.

• Avoid Obsolete Packages: Tools like next-seo are largely unnecessary in the App Router because the built-in metadata export handles SEO tags natively.

• Security First: Never hardcode secrets in middleware or config files. Use environment variables and validate all input data before processing.

Why Use a Custom Server

Most use cases previously solved by custom servers, such as authentication redirects or header manipulation, are now better handled by Middleware. However, you might need a custom server for integrating with legacy backend systems, implementing complex multi-tenant routing based on raw socket data, or adhering to specific enterprise security policies that require a unified entry point for all HTTP traffic.

Implementation Steps

1. Create a Node.js HTTP server (or HTTPS server) using the built-in http module.

2. Initialize the Next.js app with next({ dev }) where dev reflects the environment.

3. Call app.prepare() (or await app.prepare()) to compile the application and load the request handler.

4. Obtain the request handler via app.getRequestHandler().

5. Delegate incoming requests to the handler.

6. Update package.json scripts to run your server file (e.g., node server.js) instead of next start or next dev.

7. Run next build before starting the server in production.

Impact on Rendering and Caching

Using a custom server can interfere with Next.js automatic optimizations. Static generation and Incremental Static Regeneration (ISR) still function, but streaming and dynamic rendering behaviors may require manual configuration to ensure cache headers are respected correctly. Deployment platforms like Vercel do not support custom servers, limiting hosting options to Node.js-compatible environments. Specifically, dynamic rendering flags might not propagate correctly if the custom server buffers responses.

Recommended Alternatives

Before choosing a custom server, evaluate built-in features. Use middleware.ts for edge functions that run before routing, Route Handlers (app/api/.../route.ts) for backend logic, and next.config.js for redirects and headers. These preserve platform optimizations and are easier to maintain. Server Actions should be used for form submissions and mutations instead of custom API endpoints.

Code Example

import next from 'next'
import { createServer } from 'http'

const dev = process.env.NODE_ENV !== 'production'
const app = next({ dev })
const handle = app.getRequestHandler()

// Prepare the Next.js app once before starting the server
app.prepare().then(() => {
  const server = createServer((req, res) => {
    // Delegate all requests to Next.js routing
    handle(req, res)
  })

  server.listen(3000, () => {
    console.log('Server running on http://localhost:3000')
  })
})

Best Practices

Only implement a custom server if absolutely necessary, as it increases maintenance burden and reduces compatibility with serverless deployments. If the goal is Docker containerization, use output: 'standalone' in next.config.js with the standard next start command instead. Always test caching headers and ISR behavior thoroughly after introducing a custom server layer.

Routing Structure and Locale Segments

• In the App Router, locales are usually represented by a dynamic segment such as app/[locale]/page.tsx and app/[locale]/layout.tsx.

• You define the supported locales and default locale yourself, typically in a shared constants file or middleware, because there is no i18n block in next.config.js.

• The segment must be validated: a request for /xx/about where xx is unsupported should redirect to the default locale or return a 404.

Middleware for Detection and Redirection

• middleware.ts at the project root runs before rendering and is the standard place to inspect Accept-Language, cookies, or the pathname.

• If the URL lacks a locale prefix, redirect to the default locale; if it contains an unsupported locale, redirect or return 404.

• Use NextResponse.redirect when the browser URL should change, and NextResponse.rewrite when you want to serve different content while keeping the URL.

• Scope the middleware with matcher so it does not run on static assets, API routes, or _next resources.

Rendering, Caching, and Component Boundaries

• Reading headers() or cookies() in a Server Component makes that segment dynamic and disables static rendering for it.

• To preserve caching, detect the locale once in the root layout or middleware and pass it down as a prop instead of reading headers deep in the component tree.

• Interactive language switchers require 'use client'; translation data fetching and URL generation can remain server-side.

• Each locale variant is a separate route, so incremental static regeneration, revalidation, and prerendering must be handled per locale.

SEO and Metadata

• Use generateMetadata in layouts or pages to emit hreflang tags for every language variant, including the x-default URL.

• Include the locale prefix in canonical URLs so crawlers do not treat /en/about and /fr/about as duplicate content.

• If you use domain-based routing, pair hreflang tags with the correct domain and locale.

Best Practices and Pitfalls

• Validate every locale segment: never trust the URL value; reject unsupported locales before rendering.

• Preserve locale across navigation and actions: include the locale in links, router pushes, and Server Action payloads so users do not unexpectedly fall back to the default locale.

• Avoid redirection loops: a rule that sends /about to /en/about must not also redirect /en/about again.

• Choose a library for complex cases: next-intl is a widely used option that integrates with the App Router and handles messages, formatting, and routing.

• Document the convention: because the routing is manual, explicit locale constants and helper functions reduce mistakes across a team.

Error Boundaries with error.tsx

When a Server Component throws an error during rendering, data fetching, or effect execution, Next.js displays the nearest error.tsx file up the tree. This component must be a Client Component because it needs to render interactive recovery UI. It receives an error object containing the exception and a reset function to retry the failed segment. The boundary isolates the failure so surrounding layouts and navigation remain functional.

• Props: The component signature is ({ error, reset }) => { ... }.

• Boundary Scope: The boundary only covers the segment where the file exists and its children, not sibling routes.

• Recovery: Calling reset() re-renders the segment, attempting the operation again without a full page reload.

Handling Missing Routes with not-found.tsx

The not-found.tsx file renders when a route does not match or when notFound() is invoked programmatically. Unlike error.tsx, this does not require a client component unless interactivity is needed. It is commonly used for missing database records. This ensures users receive a clear message instead of a generic server exception.

• Programmatic Trigger: Import notFound from next/navigation and call it inside Server Components.

• Automatic Trigger: Occurs when the URL path does not match any layout or page in the app directory.

• Status Code: Automatically returns a 404 status to the client, which is crucial for SEO and analytics.

Scope and Nesting

Error handling is hierarchical. A root app/error.tsx catches errors across the entire application, while app/dashboard/error.tsx isolates issues to the dashboard section. If a nested error boundary catches an error, the root boundary remains unaffected. This allows specific UI fallbacks for critical sections like checkout flows versus generic blog posts. Layouts above the boundary persist, preserving navigation state.

Code Example

// app/error.tsx
'use client';

import { useEffect } from 'react';

export default function Error({
  error,
  reset,
}: {
  error: Error & { digest?: string };
  reset: () => void;
}) {
  useEffect(() => {
    console.error(error);
  }, [error]);

  return (
    <div>
      <h2>Something went wrong!</h2>
      <button onClick={() => reset()}>Try again</button>
    </div>
  );
}

// app/not-found.tsx
export default function NotFound() {
  return (
    <div>
      <h2>Page Not Found</h2>
      <p>The requested resource could not be located.</p>
    </div>
  );
}

Best Practices

• Log Server Errors: Since error.tsx is client-side, send error details to a logging service via an API route rather than relying solely on console logs.

• Avoid Sensitive Data: Do not expose stack traces or internal error messages to users in production to prevent information leakage.

• Use Server Actions: For form submission errors, handle validation within Server Actions and return error states instead of throwing uncaught exceptions.

• Distinguish Boundaries: Use error.tsx for unexpected crashes and not-found.tsx for expected missing resources to maintain correct HTTP semantics.

• Testing: Verify error states by intentionally throwing errors in development to ensure the UI renders correctly before deployment.

Recommended Directory Layout

Instead of grouping by file type, such as placing all components in one global folder, organize by domain or feature. A typical root layout includes app/ for routes, lib/ for reusable business logic and database clients, components/ for shared UI elements, assets/ for static media, types/ for global TypeScript interfaces, and styles/ for global CSS or theme configuration. Inside app/, further divide by feature rather than just URL path. For example, app/dashboard/ might contain layout.tsx, page.tsx, and sub-routes like settings/. This ensures that developers working on a specific feature can find all related code in one place.

Route Grouping and Layout Isolation

Next.js allows folder names wrapped in parentheses, such as (shop) or (auth). These groups do not affect the URL path but let you apply different layouts to different sections. This is critical for large apps where a marketing page needs a different root layout than a protected dashboard. For instance, (auth)/login.tsx uses an auth-specific layout, while (app)/dashboard/page.tsx uses the main application layout, yet both resolve to /login and /dashboard respectively. This isolation prevents layout bleed and simplifies authentication guards.

Server and Client Component Separation

By default, components in app/ are Server Components. Only mark files with 'use client' when they require interactivity, state, or browser APIs. Keeping logic on the server reduces bundle size and improves performance. Server Components fetch data, access environment variables, and run heavy logic, whereas Client Components handle events, use useState, useEffect, or custom hooks requiring DOM access. Place shared client components in components/client/ and server components in components/server/ to make boundaries explicit and prevent accidental client-side data fetching.

API and Data Handling

Use Route Handlers (app/api/.../route.ts) for external API endpoints or webhooks that need to be accessed by third parties. For form mutations and data updates originating from UI components, prefer Server Actions defined directly in server components or imported from lib/. This keeps data logic close to the UI that triggers it. Avoid mixing fetch logic inside deeply nested client components; lift data fetching to the nearest server component or layout. Use revalidate tags or fetch options like cache and next.revalidate to control caching behavior per route, enabling static generation or incremental static regeneration where appropriate.

Best Practices and Common Pitfalls

• Use Path Aliases: Configure tsconfig.json paths (e.g., @/components) to avoid fragile relative imports like ../../../.

• Avoid Deep Nesting: Keep route segments shallow to maintain readable URLs and simpler layout hierarchies.

• Colocate Tests: Place test files next to the component they verify (e.g., Button.test.tsx beside Button.tsx).

• Environment Variables: Prefix public variables with NEXT_PUBLIC_; keep secrets server-side only to prevent exposure.

• Naming Consistency: Stick to kebab-case for folders and PascalCase for components to reduce cognitive load during navigation.

Separating Server and Client Responsibilities

• Server Components: execute only on the server, can directly access backend resources, and are ideal for data fetching and layout structure. They are cached by default based on request inputs, which reduces load times.

• Client Components: marked with 'use client', handle interactivity such as state management, event listeners, and browser APIs.

• Data flow: keep data fetching in parent Server Components and pass the resulting data as props to child Client Components. This creates UI pieces that work regardless of where the data originated.

• Caching: Server Components are automatically cached; use dynamic() or revalidate when you need fresh or request-specific data.

Feature-Based Directory Organization

• Organize folders by feature or route rather than by file type.

• Example: place dashboard-specific UI under app/dashboard/components/, generic primitives (buttons, inputs, cards) under components/ui/, and shared utilities under lib/.

• Benefits: components are co-located with their usage context, while shared elements remain accessible across routes without creating deep dependency chains.

• Avoid a single flat components folder that grows unmanageably as the application scales.

Composition Over Inheritance

• Favor component composition using the children prop and custom hooks instead of inheritance hierarchies.

• A reusable layout component should accept children to wrap arbitrary content, while logic reuse should be encapsulated in custom hooks (e.g., useFormHandler, useDataFetch).

• This approach lets you combine small, single-purpose blocks into complex views without duplicating code.

• It also makes testing individual behaviors simpler because logic is decoupled from rendering.

Server vs Client Component Responsibilities

Best Practices and Pitfalls

• Keep components small and focused on a single responsibility to maximize reuse potential.

• Avoid prop drilling by passing only necessary data; use Context sparingly for truly global state such as themes or authentication.

• Never import client-side libraries directly into Server Components, because browser APIs are unavailable on the server and this causes rendering errors. Always isolate interactive dependencies within 'use client' boundaries.

• Keep business logic out of UI components; extract it into services or hooks so the logic remains testable and reusable outside the rendering tree.

• Prefer Server Actions for mutations in the App Router; they keep logic close to the server and avoid manual API route boilerplate.

• When sharing components across features, place them in a shared directory and use absolute imports or path aliases to avoid relative path spaghetti.

Core Built-in Mechanisms

Next.js builds on React primitives rather than introducing its own global store. On the client, useState, useReducer, and createContext cover UI state that must survive navigation. On the server, components read data directly and rely on Next.js caching (fetch options, revalidate) rather than client-held state. The URL itself acts as a source of truth for query state through next/navigation hooks, making filters, pagination, and sort order bookmarkable without extra libraries.

Client State with React Context

Create a Context Provider for values many client components need (theme, auth status, locale). The provider must be a Client Component ('use client') because it owns interactive state. Render it in the root layout or a nested layout so useContext works anywhere in the subtree. For complex state logic, pair createContext with useReducer instead of multiple useState calls. Keep the context value shallow to avoid unnecessary re-renders.

Server State and Mutations

Server Components fetch data directly, which eliminates hydration mismatches and shrinks the client bundle. Use fetch(url, { next: { revalidate: 3600 } }) for ISR or cache: 'no-store' for fully dynamic requests. Mutations belong in Server Actions: mark a function with 'use server' and call it from client components or forms. Server Actions run on the server, so they can safely write to databases, set cookies, or revalidate tags. They can also be passed as props to client components, keeping the mutation boundary clear.

URL and Search Parameters

For state that should be shared, persisted, or deep-linked, read and write query strings with useSearchParams and useRouter from next/navigation. This state lives in the browser address bar, so it survives refreshes and can be bookmarked. It is especially suited to filters, pagination, tabs, and modal open/close state that you want to encode in a link.

Best Practices and Pitfalls

• Avoid putting server data in client context: pass fetched data as props to reduce hydration work and keep the client bundle small.

• Limit client context scope: wrapping the entire app in a heavy client context disables server rendering for that subtree; prefer layout-level providers.

• Validate Server Action inputs: treat arguments as untrusted and validate them before using them in queries or writes.

• Compose contexts: several small contexts beat one giant store for maintainability and code-splitting.

• Use URL state for shareable state: if a user would expect to copy the link and see the same view, keep it in search params.

How Next.js Changes State Management Needs

• Server Components fetch data directly on the server, serialize it as props, and stream it to the client — no client store required for initial data.

• Route Handlers and Server Actions mutate server data and trigger revalidation, replacing the classic “fetch → dispatch → reducer” cycle.

• Client Components (marked 'use client') only need state for interactive UI: form inputs, toggles, drag-and-drop, optimistic updates, etc.

When Redux Is Justified

When Simpler Alternatives Suffice

• React Context + useReducer — fine for theme, auth user, or a handful of global flags.

• Zustand / Jotai / Valtio — minimal boilerplate, atomic updates, work well with Server Components (no provider hell).

• TanStack Query / SWR — server cache + mutations + optimistic updates; often replaces Redux for “server state”.

• Local component state (useState/useReducer) — the default for anything that doesn’t leave the component tree.

Common Pitfalls

• Putting server-fetched data in Redux — duplicates Next.js cache, causes hydration mismatches, wastes bandwidth.

• Wrapping the whole app in a Redux Provider — forces 'use client' at the layout root, opting entire subtrees out of Server Components.

• Over-fetching in getServerSideProps style — App Router’s fetch + next/cache tags (revalidateTag) are purpose-built for this.

Decision Checklist

1. Is the state purely client-side UI state? → Start with useState/useReducer or Context.

2. Does it involve server data? → Use fetch in Server Components + revalidatePath/revalidateTag in Server Actions.

3. Do you need time-travel debugging, middleware, or cross-tab sync? → Redux (or Redux Toolkit) pays off.

4. Is the team already productive with Redux? → Stay consistent; migrate incrementally.

Best Practices If You Adopt Redux

• Keep the store client-only: create it inside a 'use client' provider component, not at the top-level layout.

• Use Redux Toolkit (configureStore, createSlice) — it’s the official, opinionated API.

• Serialize only what the client needs; let Server Components pass initial data as props to avoid double-fetching.

• Enable serializableCheck middleware (default in RTK) to catch non-serializable values that break hydration.

State Location Strategies

Next.js differentiates between Server Components (default) and Client Components ('use client'). Server Components do not retain local state between requests unless data is cached via fetch options or revalidate. Client Components unmount when navigating away unless they are part of a persistent layout. To persist state, you must choose a storage mechanism that survives unmounting. Choosing the wrong location causes data loss when users navigate back and forth.

URL State with searchParams

For state that should be shareable or bookmarkable, encode it in the URL. Use useSearchParams from next/navigation in Client Components. This persists automatically across transitions because the URL remains consistent or updates predictably. It is ideal for filters, sorting, pagination, and any state that should survive a refresh or be linked. - Pros: Refresh-safe, shareable, back-button compatible, works without JavaScript on the server. - Cons: Limited data size, exposes logic to users, requires parsing and serialization.

Global Client State

For UI state unrelated to the URL (e.g., theme, sidebar open/close, form progress), use a global store. Create a React Context or use a library such as Zustand. The provider must be rendered in the root layout.tsx so it isn’t unmounted during page navigation. Any component consuming this state must be marked 'use client'. This ensures the store instance remains singular across the session. Because the root layout wraps all pages, sibling navigations do not reset the store.

Comparison of Strategies

Best Practices

• Minimize Client State: Prefer server state and URL params where possible to reduce hydration overhead and improve SEO.

• Layout Persistence: Keep providers in layout.tsx, not page.tsx, to avoid re-initialization on navigation between sibling pages.

• Server Actions: Use Server Actions for mutations instead of client-side fetches to maintain server authority and simplify data flow.

• Avoid Large Objects in URL: Use URL state for filters/IDs, not complex objects, to prevent URL length limits and encoding issues.

• Type Safety: Ensure context values or store interfaces are typed strictly to avoid runtime errors during navigation.

• Know When to Reset: If a store should reset when entering a specific flow, place the provider in a nested layout rather than the root layout.

App Router Page Structure

Pages in the App Router are React Server Components by default. They receive params (dynamic route segments) and searchParams (query string) as props. Unlike the Pages Router, you type the component function signature directly without getServerSideProps or getStaticProps.

Typing in Next.js 15 (Async Props)

Starting in Next.js 15, params and searchParams are Promises in Server Components to support streaming and improved caching. Define the expected shape inside the Promise resolution. The component must be async and await the props before use.

Client Component Pages

If a page needs browser APIs or state, mark it with 'use client'. In Next.js 15, Client Component pages do not receive params and searchParams as props; instead, use the useParams and useSearchParams hooks from next/navigation. The typing approach changes accordingly.

Code Example

// app/products/[slug]/page.tsx (Server Component)
type PageProps = {
  params: Promise<{ slug: string }>;
  searchParams: Promise<{ [key: string]: string | string[] }>;
};

export default async function ProductPage({ params, searchParams }: PageProps) {
  const { slug } = await params;
  const { sort } = await searchParams;

  return <div>Product Slug: {slug}</div>;
}

// app/products/[slug]/page.tsx (Client Component)
'use client';

import { useParams, useSearchParams } from 'next/navigation';

export default function ProductPageClient() {
  const params = useParams<{ slug: string }>();
  const searchParams = useSearchParams();
  const slug = params.slug;
  const sort = searchParams.get('sort');

  return <div>Product Slug: {slug}</div>;
}

Common Pitfalls and Best Practices

• Avoid any: Define specific keys for params to catch route mismatches at build time.

• Version Differences: In Next.js 14 and earlier, params and searchParams are synchronous; omit the Promise wrapper.

• Serialization: Props passed to Client Components must be JSON-serializable; avoid functions or class instances.

• Pages Router: The Pages Router uses getServerSideProps/getStaticProps for data fetching; types are defined on the returned props object. It is not deprecated but the App Router is recommended for new projects.

Installation and Configuration

• Install the compiler and type definitions: npm install --save-dev typescript @types/react @types/react-dom @types/node.

• Next.js generates a baseline tsconfig.json when it encounters a .ts/.tsx file or when you run next dev; review it rather than accepting it blindly.

• Keep strict: true for full type safety and allowJs: true so existing JavaScript files can remain during a gradual migration.

• Leave jsx: "preserve" so Next.js handles JSX transformation; use moduleResolution: "bundler", esModuleInterop, and skipLibCheck as the modern baseline.

• Add a script: "type-check": "tsc --noEmit" to catch errors without a full build.

File Conversion Strategy

• Rename files systematically: .tsx for anything containing JSX, .ts for pure logic modules.

• Convert shared utilities and components first, then app/ pages and layouts.

• In Next.js 15, params and searchParams are asynchronous in Server Components, so type them as Promise<...> and await them inside the component.

• Add 'use client' at the top of components that use hooks, browser APIs, or DOM events; keep data fetching in Server Components.

Handling JavaScript Interop

• Untyped JavaScript imports resolve as any; protect critical paths with JSDoc annotations or ambient .d.ts declarations instead of relying on implicit any.

• Use // @ts-ignore only as a temporary escape hatch; prefer // @ts-expect-error so the comment becomes an error once the type is fixed.

• For third-party packages without bundled types, check @types/<package> before writing custom definitions.

• Keep noImplicitAny enabled under strict so untyped boundaries are visible.

Code Example

// app/page.tsx
import { Suspense } from 'react';
import ClientComponent from './ClientComponent';

interface PageProps {
  params: Promise<{ id: string }>;
  searchParams: Promise<Record<string, string | string[] | undefined>>;
}

export default async function Page({ params, searchParams }: PageProps) {
  const { id } = await params;
  const search = await searchParams;

  return (
    <div>
      <h1>{id}</h1>
      <Suspense fallback={<div>Loading...</div>}>
        <ClientComponent searchParams={search} />
      </Suspense>
    </div>
  );
}

// app/ClientComponent.tsx
'use client';

import { useEffect, useState } from 'react';

interface Props {
  searchParams: Record<string, string | string[] | undefined>;
}

export default function ClientComponent({ searchParams }: Props) {
  const [value, setValue] = useState<string>('');

  useEffect(() => {
    setValue((searchParams.q as string) || '');
  }, [searchParams]);

  return <input value={value} onChange={(e) => setValue(e.target.value)} />;
}

Common Pitfalls

• Rename next.config.js to next.config.ts only if you want typed configuration; in Next.js 15 this works natively with import type { NextConfig } from 'next' and no extra loader.

• Environment variables accessed through process.env are not compile-time guaranteed; validate them or wrap them in a typed accessor.

• Run npm run type-check and next build frequently, because type errors can break server rendering and static generation.

• Never pass server-only values such as headers or cookies to Client Components; serialize only plain data that can cross the server boundary.

Route Handler Architecture

Route Handlers replace the Pages Router API routes (pages/api) and are defined as route.ts files within the app directory. Each HTTP method corresponds to an exported async function, such as GET, POST, PUT, or DELETE. These functions execute exclusively on the server, so they do not require the 'use client' directive and have direct access to server-side resources like databases or environment variables.

Typing Request and Response Data

To enforce type safety, you define interfaces for the expected request body and the response payload. The request argument is typed as NextRequest, which provides methods like json() to parse incoming data. The response is constructed using NextResponse, which includes a generic json() method to type the outgoing payload. This ensures that mismatched data structures are caught during development rather than at runtime.

Code Example

The following example demonstrates a typed POST handler that accepts a user creation request and returns a standardized response.

import { NextRequest, NextResponse } from 'next/server';

// Define the expected shape of the request body
interface CreateUserRequest {
  name: string;
  email: string;
}

// Define the expected shape of the response body
interface CreateUserResponse {
  id: string;
  message: string;
}

export async function POST(request: NextRequest) {
  try {
    // Parse and type the incoming JSON body
    const body: CreateUserRequest = await request.json();

    // Validate required fields (example logic)
    if (!body.name || !body.email) {
      return NextResponse.json(
        { error: 'Name and email are required' },
        { status: 400 }
      );
    }

    // Process data and return typed response
    const response: CreateUserResponse = {
      id: 'user_123',
      message: 'User created successfully',
    };

    return NextResponse.json<CreateUserResponse>(response, { status: 201 });
  } catch (error) {
    return NextResponse.json(
      { error: 'Failed to process request' },
      { status: 500 }
    );
  }
}

Best Practices and Common Pitfalls

Always validate incoming data even when using TypeScript, as types are stripped during compilation and do not guarantee runtime safety. Use libraries like zod or yup to validate the parsed JSON body against your interfaces. Avoid placing sensitive logic or secrets in client components; Route Handlers are secure server-side boundaries. Remember that caching is enabled by default for GET handlers; use revalidate or dynamic settings if you require fresh data on every request. Finally, ensure error responses always return a consistent structure to simplify client-side error handling.

Understanding Route Parameters

In the App Router, dynamic segments are defined using brackets, such as app/posts/[id]/page.tsx. Next.js automatically infers the shape of the params prop based on the folder structure. However, because HTTP parameters are always transmitted as strings, TypeScript cannot natively enforce that an id segment is a number without additional logic. You must explicitly type the params prop to catch missing or misspelled segments during development.

Runtime Validation with Zod

Type checking alone is insufficient because it only verifies the structure, not the value. To enforce data integrity, use a schema validation library like Zod inside the server component. This allows you to parse and coerce string parameters into their expected types, throwing errors if validation fails. This step is crucial for preventing runtime crashes caused by malformed URLs.

Generating Static Parameters

For static generation, implement generateStaticParams to define valid route segments at build time. This function returns an array of objects matching the dynamic segment names. It ensures that only known routes are pre-rendered, reducing server load and improving performance. To enable Incremental Static Regeneration (ISR), export a revalidate constant from the page (e.g., export const revalidate = 60).

Code Example

The following example demonstrates typing params as a Promise, validating with Zod, and generating static params.

// app/posts/[id]/page.tsx
import { z } from 'zod';

const paramsSchema = z.object({
  id: z.string().pipe(z.coerce.number()),
});

export async function generateStaticParams() {
  return [{ id: '1' }, { id: '2' }];
}

export default async function Page({
  params,
}: { params: Promise<{ id: string }> }) {
  const { id } = paramsSchema.parse(await params);
  return <div>Post ID: {id}</div>;
}

Common Pitfalls

Avoid treating params as synchronous in Next.js 15, as this leads to type errors and runtime issues. Do not rely solely on TypeScript interfaces for validation, as they are erased at compile time. Always handle validation errors gracefully using Next.js error boundaries or redirects instead of allowing uncaught exceptions to propagate to the client.

Environment and Type Generation

When a Next.js project is initialized with TypeScript, the framework creates a next-env.d.ts file in the root directory. This file is regenerated during development and build processes to ensure the TypeScript compiler recognizes Next.js-specific modules and environment variables. It adds triple-slash references to the next package (e.g., /// <reference types="next" />) but does not generate business logic types for individual pages. Instead, it enables global type declarations for assets like images and fonts, allowing developers to import them without type errors. This file should generally be committed to version control to ensure consistent typing across environments.

App Router Route Handlers

In the App Router, API routes are replaced by Route Handlers located in app/api/.../route.ts. These handlers export asynchronous functions named after HTTP methods (e.g., GET, POST). Next.js does not automatically infer the request body schema; developers must import NextRequest and NextResponse from next/server to type the arguments and return values correctly. This explicit typing ensures that JSON parsing and response serialization are handled safely.

Server Component Props

Server Components within the app directory receive props dynamically based on the URL structure. The params object contains dynamic route segments, while searchParams holds URL query parameters. By default, these are typed loosely as string records. To enforce stricter validation, developers should define interfaces for these props or use Zod for runtime validation. Components requiring browser APIs or state management must include the 'use client' directive at the top of the file.

Best Practices

• Enable Strict Mode: Set "strict": true in tsconfig.json to catch nullability and implicit any errors early.

• Avoid Implicit Any: Never rely on implicit typing for request bodies; always define interfaces or use validation libraries.

• Separate Concerns: Keep data fetching in Server Components and move interactive logic to Client Components marked with 'use client'.

• Update Types Regularly: Ensure next and @types/react versions are compatible to avoid declaration conflicts.

Core Functionality

• Generation: The file is created when TypeScript is introduced with npx next --typescript or npx create-next-app@latest --typescript.

• Scope: It controls type-checking strictness, JSX emit strategy, module resolution, target environment, library definitions, and which files participate via include/exclude.

• Compilation relationship: Next.js compiles application code with SWC rather than tsc, so the file primarily powers IDE features and build-time type checks. By default next build fails on type errors; this can be relaxed with typescript.ignoreBuildErrors in next.config.js.

• Bundler separation: It does not configure Webpack/Turbopack or runtime behavior.

Key Compiler Options

Customization Methods

1. Edit compilerOptions directly to change strictness, target, or resolution strategy.

2. Use extends to share a base configuration across packages in a monorepo.

3. Adjust include and exclude to limit type checking to specific directories; do not exclude .next if generated types are referenced.

4. Define baseUrl plus paths for aliases, and mirror the same mapping in Jest/Vitest moduleNameMapper or bundler configuration.

5. Set skipLibCheck to reduce noise from third-party declarations with weak types.

6. Keep framework-level control separate: next.config.js typescript.ignoreBuildErrors can stop type errors from failing a build, but it does not change tsconfig.json rules.

Code Example

{
  "compilerOptions": {
    "target": "ES2017",
    "lib": ["dom", "dom.iterable", "esnext"],
    "allowJs": true,
    "skipLibCheck": true,
    "strict": true,
    "noEmit": true,
    "incremental": true,
    "module": "esnext",
    "moduleResolution": "bundler",
    "resolveJsonModule": true,
    "isolatedModules": true,
    "jsx": "preserve",
    "baseUrl": ".",
    "paths": {
      "@/*": ["./*"]
    }
  },
  "include": ["next-env.d.ts", "**/*.ts", "**/*.tsx"],
  "exclude": ["node_modules"]
}

Best Practices and Common Pitfalls

• Keep jsx as preserve: Switching to react-jsx or react-jsxdev breaks Next.js Server Component compilation.

• Enable strictness gradually: On legacy code, turn on strict and address errors with // @ts-expect-error rather than blanket @ts-ignore.

• Aliases are compile-time only: paths does not affect runtime resolution; mismatched Jest/Vitest or Turbopack aliases cause “module not found” errors even when TypeScript is happy.

• Do not disable noEmit: Next.js handles emission; letting tsc write files can duplicate output and interfere with the build pipeline.

• Server/Client boundaries are not type-checked: tsconfig.json is global and cannot prevent a Server Component from using window. Use the server-only package for server modules and rely on the 'use client' directive plus ESLint for boundaries.

• Validate after changes: Run npx tsc --noEmit and next build to confirm the framework accepts the configuration.