Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: Add some App Router FAQs #55186

Merged
merged 4 commits into from
Sep 12, 2023
Merged
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
65 changes: 62 additions & 3 deletions docs/02-app/index.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -3,8 +3,67 @@ title: App Router
description: Use the new App Router with Next.js' and React's latest features, including Layouts, Server Components, Suspense, and more.
---

The App Router is a new paradigm for building applications using React's latest features. If you're already familiar with Next.js, you'll find that the App Router is a natural evolution of the existing file-system based router in the [Pages Router](/docs/pages).
The Next.js App Router is a new paradigm for building applications using React's latest features. If you're already familiar with Next.js, you'll find that the App Router is a natural evolution of the existing file-system based router in the [Pages Router](/docs/pages).

For new applications, we recommend using the App Router. For existing applications, you can [incrementally migrate to the App Router](/docs/app/building-your-application/upgrading/app-router-migration).
For new applications, **we recommend using the App Router**. For existing applications, you can [incrementally adopt the App Router](/docs/app/building-your-application/upgrading/app-router-migration). It's also possible to use both routers in the same application.

This section of the documentation includes the features available in the App Router:
## Frequently Asked Questions

### How can I access the request object in a layout?

You intentionally cannot access the raw request object. However, you can access [`headers`](/docs/app/api-reference/functions/headers) and [`cookies`](/docs/app/api-reference/functions/cookies) through server-only functions. You can also [set cookies](#how-can-i-set-cookies).

[Layouts](/docs/app/building-your-application/routing/pages-and-layouts#layouts) do not rerender. They can be cached and reused to avoid unnecessary computation when navigating between pages. By restricting layouts from accessing the raw request, Next.js can prevent the execution of potentially slow or expensive user code within the layout, which could negatively impact performance.

This design also enforces consistent and predictable behavior for layouts across different pages, simplify development and debugging since developers can rely on layouts behaving the same way regardless of the specific page they are applied to.

Depending on the UI pattern you're building, [Parallel Routes](/docs/app/building-your-application/routing/parallel-routes) allow you to render multiple pages in the same layout, and pages have access to the route segments as well as the URL search params.

### How can I access the URL on a page?

By default, pages are Server Components. You can access the route segments through the [`params`](/docs/app/api-reference/file-conventions/page#params-optional) prop and the URL search params through the [`searchParams`](/docs/app/api-reference/file-conventions/page#searchparams-optional) prop for a given page.

If you are using Client Components, you can use [`usePathname`](/docs/app/api-reference/functions/use-pathname), [`useSelectedLayoutSegment`](/docs/app/api-reference/functions/use-selected-layout-segment), and [`useSelectedLayoutSegments`](/docs/app/api-reference/functions/use-selected-layout-segments) for more complex routes.

Further, depending on the UI pattern you're building, [Parallel Routes](/docs/app/building-your-application/routing/parallel-routes) allow you to render multiple pages in the same layout, and pages have access to the route segments as well as the URL search params.

### How can I redirect from a Server Component?

You can use [`redirect`](/docs/app/api-reference/functions/redirect) to redirect from a page to a relative or absolute URL. [`redirect`](/docs/app/api-reference/functions/redirect) is a temporary (307) redirect, while [`permanentRedirect`](/docs/app/api-reference/functions/permanentRedirect) is a permanent (308) redirect. When these functions are used while streaming UI, they will insert a meta tag to emit the redirect on the client side.

### How can I handle authentication with the App Router?

Here are some common authentication solutions that support the App Router:

- [NextAuth](https://next-auth.js.org/configuration/nextjs#in-app-router)
leerob marked this conversation as resolved.
Show resolved Hide resolved
- [Clerk](https://clerk.com/docs/quickstarts/nextjs)
- [Auth0](https://github.com/auth0/nextjs-auth0#app-router)
- Or manually handling sessions or JWTs

### How can I set cookies?

You can set cookies in [Server Actions](/docs/app/building-your-application/data-fetching/forms-and-mutations#setting-cookies) or [Route Handlers](/docs/app/building-your-application/routing/route-handlers) using the [`cookies`](/docs/app/api-reference/functions/cookies) function.

Since HTTP does not allow setting cookies after streaming starts, you cannot set cookies from a page or layout directly. You can also set cookies from [Middleware](/docs/app/building-your-application/routing/middleware#using-cookies).

### How can I build multi-tenant apps?

If you are looking to build a single Next.js application that serves multiple tenants, we have [built an example](https://vercel.com/templates/next.js/platforms-starter-kit) showing our recommended architecture.

### How can I invalidate the App Router cache?

There are multiple layers of caching in Next.js, and thus, multiple ways to invalidate different parts of the cache. [Learn more about caching](/docs/app/building-your-application/caching).

### Are there any comprehensive, open-source applications built on the App Router?

Yes. You can view [Next.js Commerce](https://vercel.com/templates/next.js/nextjs-commerce) or the [Platforms Starter Kit](https://vercel.com/templates/next.js/platforms-starter-kit) for two larger examples of using the App Router that are open-source.

## Learn More

- [Routing Fundamentals](/docs/app/building-your-application/routing)
- [Data Fetching, Caching, and Revalidating](/docs/app/building-your-application/data-fetching/fetching-caching-and-revalidating)
- [Forms and Mutations](/docs/app/building-your-application/data-fetching/forms-and-mutations)
- [Caching](/docs/app/building-your-application/caching)
- [Rendering Fundamentals](/docs/app/building-your-application/rendering)
- [Server Components](/docs/app/building-your-application/rendering/server-components)
- [Client Components](/docs/app/building-your-application/rendering/client-components)