The app Directory

Key points:

• components inside app are React Server Components by default
• fetch is cached by default
• fetch data from anywhere: layout, page, component (can use async / await)
• folders are used to define routes, files are used to create UI or API endpoint
• no rerender for shared layouts - partial rendering
• segments are wrapped in error boundary and suspense
• new routes: parallel routes, intercepting routes
• can use pages and app alongside with priority to app
• routing on server, navigation on client

Roles of Folders and Files

• Folders are used to define routes. A route is a single path of nested folders, following the hierarchy from the root folder down to a final leaf folder that includes a page.js file.
• Files are used to create UI that is shown for the route segment.

Dynamic Routes

Catch-all Segments

Optional Catch-all Segments

Route Groups

The hierarchy of the app folder maps directly to URL paths. However, it’s possible to break out of this pattern by creating a route group. Route groups can be used to:

• Organize routes without affecting the URL structure.
• Opting-in specific route segments into a layout.
• Create multiple root layouts by splitting your application.

Even though routes inside (marketing) and (shop) share the same URL hierarchy, you can create a different layout for each group by adding a layout.js file inside their folders.

File Conventions

• page.js: Create the unique UI of a route and make the path publicly accessible.
  • route.js: Create server-side API endpoints for a route.
• layout.js: Create shared UI for a segment and its children. A layout wraps a page or child segment.
  • template.js: Similar to layout.js, except a new component instance is mounted on navigation. Use layouts unless you need this behavior.
• loading.js: Create loading UI for a segment and its children. loading.js wraps a page or child segment in a React Suspense Boundary, showing the loading UI while they load.
• error.js: Create error UI for a segment and its children. error.js wraps a page or child segment in a React Error Boundary, showing the error UI if an error is caught.
  • global-error.js: Similar to error.js, but specifically for catching errors in the root layout.js.
• not-found.js: Create UI to show when the notFound function is thrown within a route segment or when a URL is not matched by any route.

Component Hierarchy

• layout.js
• template.js
• error.js (React error boundary)
• loading.js (React suspense boundary)
• not-found.js (React error boundary)
• page.js or nested layout.js

In a nested route, the components of a segment will be nested inside the components of its parent segment.

Colocation

In addition to special files, you have the option to colocate your own files inside folders. For example, stylesheets, tests, components, and more.

Server-Centric Routing with Client-side Navigation

The App Router uses server-centric routing to align with Server Components and data fetching on the server. With server-centric routing, the client does not have to download a route map and the same request for Server Components can be used to look up routes.

Although routing is server-centric, the router uses client-side navigation with the Link Component - resembling the behavior of a Single-Page Application. This means when a user navigates to a new route, the browser will not reload the page. Instead, the URL will be updated and Next.js will only render the segments that change.

Additionally, as users navigate around the app, the router will store the result of the React Server Component payload in an in-memory client-side cache. The cache is split by route segments which allows invalidation at any level and ensures consistency across React's concurrent renders.

Partial Rendering

When navigating between sibling routes (e.g. /dashboard/settings and /dashboard/analytics below), Next.js will only fetch and render the layouts and pages in routes that change. It will not re-fetch or re-render anything above the segments in the subtree. This means that in routes that share a layout, the layout will be preserved when a user navigates between sibling pages.

Advanced Routing Patterns

• Parallel Routes: Allow you to simultaneously show two or more pages in the same view that can be navigated independently. You can use them for split views that have their own sub-navigation. E.g. Dashboards.
• Intercepting Routes: Allow you to intercept a route and show it in the context of another route. You can use these when keeping the context for the current page is important. E.g. Seeing all tasks while editing one task or expanding a photo in a feed.

Route Handlers

Route Handlers are defined in a route.js|ts file inside the app directory:

app/api/route.ts

export async function GET(request: Request) {}

Route Handlers can be nested inside the app directory, similar to page.js and layout.js. But there cannot be a route.js file at the same route segment level as page.js.

Supported HTTP Methods

The following HTTP methods are supported: GET, POST, PUT, PATCH, DELETE, HEAD, and OPTIONS. If an unsupported method is called, Next.js will return a 405 Method Not Allowed response.

Static Route Handlers

Route Handlers are statically evaluated by default when using the GET method with the Response object.

app/items/route.ts

import { NextResponse } from 'next/server';

export async function GET() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
  });
  const data = await res.json();

  return NextResponse.json({ data });
}

Dynamic Route Handlers

Route handlers are evaluated dynamically when:

• Using the Request object with the GET method.
• Using any of the other HTTP methods.
• Using Dynamic Functions like cookies and headers.
• The Segment Config Options manually specifies dynamic mode.

app/products/api/route.ts

import { NextResponse } from 'next/server';

export async function GET(request: Request) {
  const { searchParams } = new URL(request.url);
  const id = searchParams.get('id');
  const res = await fetch(`https://data.mongodb-api.com/product/${id}`, {
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
  });
  const product = await res.json();

  return NextResponse.json({ product });
}

Similarly, the POST method will cause the Route Handler to be evaluated dynamically.

app/items/route.ts

import { NextResponse } from 'next/server';

export async function POST() {
  const res = await fetch('https://data.mongodb-api.com/...', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'API-Key': process.env.DATA_API_KEY,
    },
    body: JSON.stringify({ time: new Date().toISOString() }),
  });

  const data = await res.json();

  return NextResponse.json(data);
}

Note: Previously, API Routes could have been used for use cases like handling form submissions. Route Handlers are likely not the solution for these uses cases. We will be recommending the use of mutations for this when ready.

Edge and Node.js Runtimes

Route Handlers have an isomorphic Web API to support both Edge and Node.js runtimes seamlessly, including support for streaming. Since Route Handlers use the same route segment configuration as pages and layouts, they support long-awaited features like general-purpose statically regenerated Route Handlers.

You can use the runtime segment config option to specify the runtime:

export const runtime = 'edge'; // 'nodejs' is the default

New Functions

useSelectedLayoutSegment

useSelectedLayoutSegment is a Client Component hook that lets you read the active route segment one level below the Layout it is called from.

app/example-client-component.tsx

'use client';

import { useSelectedLayoutSegment } from 'next/navigation';

export default function ExampleClientComponent() {
  const segment = useSelectedLayoutSegment();

  return <>Active segment: {segment}</>;
}

Returns

useSelectedLayoutSegment returns a string of the active segment or null if one doesn't exist.

useSelectedLayoutSegments

useSelectedLayoutSegments is a Client Component hook that lets you read the active route segments below the Layout it is called from.

Returns

useSelectedLayoutSegments returns an array of strings containing the active segments one level down from the layout the hook was called from. Or an empty array if none exist.

usePathname

usePathname is a Client Component hook that lets you read the current URL's pathname.

app/example-client-component.tsx

'use client';

import { usePathname } from 'next/navigation';

export default function ExampleClientComponent() {
  const pathname = usePathname();
  return <>Current pathname: {pathname}</>;
}

Good to know:

• usePathname can return null when a fallback route is being rendered or when a pages directory page has been automatically statically optimized by Next.js and the router is not ready.

Returns

fetch

Next.js extends the native Web fetch() API to allow each request on the server to set its own persistent caching semantics.

Can call fetch with async and await directly within Server Components.

app/page.tsx

export default async function Page() {
  // This request should be cached until manually invalidated.
  // Similar to `getStaticProps`.
  // `force-cache` is the default and can be omitted.
  const staticData = await fetch(`https://...`, { cache: 'force-cache' });

  // This request should be refetched on every request.
  // Similar to `getServerSideProps`.
  const dynamicData = await fetch(`https://...`, { cache: 'no-store' });

  // This request should be cached with a lifetime of 10 seconds.
  // Similar to `getStaticProps` with the `revalidate` option.
  const revalidatedData = await fetch(`https://...`, {
    next: { revalidate: 10 },
  });

  return <div>...</div>;
}

fetch(url, options)

options.cache

Configure how the request should interact with Next.js HTTP cache.

fetch(`https://...`, { cache: 'force-cache' | 'no-store' });

• force-cache (default) - Next.js looks for a matching request in its HTTP cache.
  • If there is a match and it is fresh, it will be returned from the cache.
  • If there is no match or a stale match, Next.js will fetch the resource from the remote server and update the cache with the downloaded resource.
• no-store - Next.js fetches the resource from the remote server on every request without looking in the cache, and it will not update the cache with the downloaded resource.

Good to know:

• If you don't provide a cache option, Next.js will default to force-cache, unless a dynamic function such as cookies() is used, in which case it will default to no-store.
• The no-cache option behaves the same way as no-store in Next.js.

options.next.revalidate

fetch(`https://...`, { next: { revalidate: false | 0 | number } } });

Set the cache lifetime of a resource (in seconds).

• false - Cache the resource indefinitely. Semantically equivalent to revalidate: Infinity. The HTTP cache may evict older resources over time.
• 0 - Prevent the resource from being cached.
• number - (in seconds) Specify the resource should have a cache lifetime of at most n seconds.

Good to know:

• If an individual fetch() request sets a revalidate number lower than the default revalidate of a route, the whole route revalidation interval will be decreased.
• If two fetch requests with the same URL in the same route have different revalidate values, the lower value will be used.
• As a convenience, it is not necessary to set the cache option if revalidate is set to a number since 0 implies cache: 'no-store' and a positive value implies cache: 'force-cache'.
• Conflicting options such as { revalidate: 0, cache: 'force-cache' } or { revalidate: 10, cache: 'no-store' } will cause an error.

notFound

The notFound function allows you to render the not-found file within a route segment as well as inject a <meta name="robots" content="noindex" /> tag.

notFound()

Invoking the notFound() function throws a NEXT_NOT_FOUND error and terminates rendering of the route segment in which it was thrown. Specifying a not-found file allows you to gracefully handle such errors by rendering a Not Found UI within the segment.

app/user/[id]/page.js

import { notFound } from 'next/navigation';

async function fetchUsers(id) {
  const res = await fetch('https://...');
  if (!res.ok) return undefined;
  return res.json();
}

export default async function Profile({ params }) {
  const user = await fetchUser(params.id);

  if (!user) {
    notFound();
  }

  // ...
}

Note: notFound() does not require you to use return notFound() due to using the TypeScript never type.

cookies

The cookies function allows you to read the HTTP incoming request cookies from a Server Component or write outgoing request cookies in a Server Action or Route Handler.

Good to know:

• cookies() is a Dynamic Function whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into dynamic rendering at request time.

cookies().get(name)

cookies().getAll()

cookies().has(name)

cookies().set(name, value, options)

A method that takes a cookie name, value, and options and sets the outgoing request cookie. This method is only available in a Server Action or Route Handler.

import { cookies } from 'next/headers';

async function create(data) {
  'use server';
  cookies().set('name', 'lee');
  // or
  cookies().set('name', 'lee', { secure: true });
  // or
  cookies().set({
    name: 'name',
    value: 'lee',
    httpOnly: true,
    path: '/',
  });
}

headers

The headers function allows you to read the HTTP incoming request headers from a Server Component.

headers()

This API extends the Web Headers API. It is read-only, meaning you cannot set / delete the outgoing request headers.

app/page.tsx

import { headers } from 'next/headers';

export default function Page() {
  const headersList = headers();
  const referer = headersList.get('referer');

  return <div>Referer: {referer}</div>;
}

Good to know:

• headers() is a Dynamic Function whose returned values cannot be known ahead of time. Using it in a layout or page will opt a route into dynamic rendering at request time.

Returns

• Headers.entries(): Returns an iterator allowing to go through all key/value pairs contained in this object.
• Headers.forEach(): Executes a provided function once for each key/value pair in this Headers object.
• Headers.get(): Returns a String sequence of all the values of a header within a Headers object with a given name.
• Headers.has(): Returns a boolean stating whether a Headers object contains a certain header.
• Headers.keys(): Returns an iterator allowing you to go through all keys of the key/value pairs contained in this object.
• Headers.values(): Returns an iterator allowing you to go through all values of the key/value pairs contained in this object.