Using App Router

Features available in /app App Router

Copy page
Getting Started Project …
Latest Version
16.1.6

Getting Started Project structure

Installation

Project Structure
and organization
Last updated February 27, 2026
Layouts and Pages

Linking and Navigating This page provides an overview of all the

Server and Client Components folder and file conventions in [Link], and
Cache Components recommendations for organizing your project.

Fetching Data

Updating Data

Caching and Revalidating

Folder and file conventions
Error Handling

CSS Top-level folders

Image Optimization
Top-level folders are used to organize your
Font Optimization application's code and static assets.
Metadata and OG images

Route Handlers

Proxy

Deploying

Upgrading
app App Router
Guides
pages Pages Router
API Reference
public Static assets to be served
Directives
src Optional application source
Components folder

Top-level files
Top-level files are used to configure your
application, manage dependencies, run proxy,
integrate monitoring tools, and define
environment variables.

[Link]

[Link] Configuration file for

[Link]

[Link] Project dependencies and

scripts

[Link] OpenTelemetry and

Instrumentation file

[Link] [Link] request proxy

.env Environment variables

(should not be tracked by
version control)

.[Link] Local environment

variables (should not be
tracked by version control)

.[Link] Production environment

variables (should not be
tracked by version control)

.[Link] Development environment

variables (should not be
tracked by version control)
[Link] Configuration file for
ESLint

.gitignore Git files and folders to

ignore

[Link] TypeScript declaration file

for [Link] (should not be
tracked by version control)

[Link] Configuration file for

TypeScript

[Link] Configuration file for

JavaScript

Routing Files
Add page to expose a route, layout for
shared UI such as header, nav, or footer,
loading for skeletons, error for error
boundaries, and route for APIs.

layout .js .jsx Layout

.tsx

page .js .jsx Page

.tsx

loading .js .jsx Loading UI

.tsx

not-found .js .jsx Not found UI

.tsx

error .js .jsx Error UI

.tsx

global-error .js .jsx Global error UI

.tsx
route .js .ts API endpoint

template .js .jsx Re-rendered

.tsx layout

default .js .jsx Parallel route

.tsx fallback page

Nested routes
Folders define URL segments. Nesting folders
nests segments. Layouts at any level wrap
their child segments. A route becomes public
when a page or route file exists.
Path URL pattern

app/[Link] —

app/blog/[Link] —

app/[Link] /

app/blog/[Link] /blog

app/blog/authors/[Link] /blog/authors

Dynamic routes
Parameterize segments with square brackets.
Use [segment] for a single param,
[...segment] for catch‑all, and
[[...segment]] for optional catch‑all.
Access values via the params prop.
Path URL pattern

app/blog/[slug]/[Link] /blog/my-fi

app/shop/[...slug]/[Link] /shop/cloth
/shop/cloth

app/docs/[[...slug]]/[Link] /docs ,
/docs/layou
pages
,
/docs/api-
reference/u

Route groups and private folders

Organize code without changing URLs with
route groups (group) , and colocate non-
routable files with private folders _folder .
Path URL pattern

app/(marketing)/[Link] /

app/(shop)/cart/[Link] /cart

app/blog/_components/[Link] —

app/blog/_lib/[Link] —

Parallel and Intercepted Routes

These features fit specific UI patterns, such
as slot-based layouts or modal routing.
Use @slot for named slots rendered by a
parent layout. Use intercept patterns to
render another route inside the current layout
without changing the URL, for example, to
show a details view as a modal over a list.
Typical use
Pattern (docs) Meaning case

@folder Named slot Sidebar + main

content

(.)folder Intercept same Preview sibling

level route in a moda

(..)folder Intercept Open a child of

parent the parent as a
overlay

(..) Intercept two Deeply nested

(..)folder levels overlay

(...)folder Intercept from Show arbitrary

root route in current
view

Metadata file conventions

App icons

favicon .ico Favicon file

icon .ico .jpg App Icon file

.jpeg .png
.svg

icon .js .ts Generated App

.tsx Icon

apple-icon .jpg .jpeg , Apple App Icon

.png file
apple-icon .js .ts Generated
.tsx Apple App Icon

Open Graph and Twitter images

opengraph- .jpg .jpeg Open Graph

image .png .gif image file

opengraph- .js .ts Generated Ope

image .tsx Graph image

twitter- .jpg .jpeg Twitter image

image .png .gif file

twitter- .js .ts Generated

image .tsx Twitter image

SEO

sitemap .xml Sitemap file

sitemap .js .ts Generated

Sitemap

robots .txt Robots file

robots .js .ts Generated

Robots file

Organizing your project

[Link] is unopinionated about how you
organize and colocate your project files. But it
does provide several features to help you
organize your project.

Component hierarchy
The components defined in special files are
rendered in a specific hierarchy:

- [Link]

- [Link]

- [Link] (React error boundary)

- [Link] (React suspense boundary)
- [Link] (React error boundary for
"not found" UI)
- [Link] or nested [Link]

The components are rendered recursively in

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

Colocation
In the app directory, nested folders define
route structure. Each folder represents a
route segment that is mapped to a
corresponding segment in a URL path.

However, even though route structure is

defined through folders, a route is not
publicly accessible until a [Link] or
[Link] file is added to a route segment.

And, even when a route is made publicly

accessible, only the content returned by
[Link] or [Link] is sent to the client.

This means that project files can be safely

colocated inside route segments in the app
directory without accidentally being routable.
 Good to know: While you can colocate your
project files in app you don't have to. If you
prefer, you can keep them outside the app
directory.

Private folders
Private folders can be created by prefixing a
folder with an underscore: _folderName

This indicates the folder is a private

implementation detail and should not be
considered by the routing system, thereby
opting the folder and all its subfolders out
of routing.

Since files in the app directory can be safely

colocated by default, private folders are not
required for colocation. However, they can be
useful for:

- Separating UI logic from routing logic.

- Consistently organizing internal files
across a project and the [Link]
ecosystem.
- Sorting and grouping files in code editors.
- Avoiding potential naming conflicts with
future [Link] file conventions.
 Good to know:
- While not a framework convention, you
might also consider marking files outside
private folders as "private" using the same
underscore pattern.
- You can create URL segments that start with
an underscore by prefixing the folder name
with %5F (the URL-encoded form of an
underscore): %5FfolderName .
- If you don't use private folders, it would be
helpful to know [Link] special file
conventions to prevent unexpected naming
conflicts.

Route groups
Route groups can be created by wrapping a
folder in parenthesis: (folderName)

This indicates the folder is for organizational

purposes and should not be included in the
route's URL path.

Route groups are useful for:

- Organizing routes by site section, intent,

or team. e.g. marketing pages, admin
pages, etc.
- Enabling nested layouts in the same route
segment level:
 - Creating multiple nested layouts in the
same segment, including multiple root
layouts
- Adding a layout to a subset of routes in
a common segment

src folder
[Link] supports storing application code
(including app ) inside an optional src folder.
This separates application code from project
configuration files which mostly live in the
root of a project.

Examples
The following section lists a very high-level
overview of common strategies. The simplest
takeaway is to choose a strategy that works
for you and your team and be consistent
across the project.

Good to know: In our examples below, we're

using components and lib folders as
generalized placeholders, their naming has no
special framework significance and your
projects might use other folders like ui , utils ,
hooks , styles , etc.
Store project files outside of app

This strategy stores all application code in

shared folders in the root of your project and
keeps the app directory purely for routing
purposes.

Store project files in top-level

folders inside of app
This strategy stores all application code in
shared folders in the root of the app
directory.

Split project files by feature or

route
This strategy stores globally shared
application code in the root app directory
and splits more specific application code into
the route segments that use them.
Organize routes without affecting
the URL path
To organize routes without affecting the URL,
create a group to keep related routes
together. The folders in parenthesis will be
omitted from the URL (e.g. (marketing) or
(shop) ).

Even though routes inside (marketing) and

(shop) share the same URL hierarchy, you
can create a different layout for each group
by adding a [Link] file inside their
folders.
Opting specific segments into a
layout
To opt specific routes into a layout, create a
new route group (e.g. (shop) ) and move the
routes that share the same layout into the
group (e.g. account and cart ). The routes
outside of the group will not share the layout
(e.g. checkout ).

Opting for loading skeletons on a

specific route
To apply a loading skeleton via a [Link]
file to a specific route, create a new route
group (e.g., /(overview) ) and then move
your [Link] inside that route group.
Now, the [Link] file will only apply to
your dashboard → overview page instead of
all your dashboard pages without affecting
the URL path structure.

Creating multiple root layouts

To create multiple root layouts, remove the
top-level [Link] file, and add a
[Link] file inside each route group. This
is useful for partitioning an application into
sections that have a completely different UI or
experience. The <html> and <body> tags
need to be added to each root layout.

In the example above, both (marketing)

and (shop) have their own root layout.

Previous Next
Installation Layouts and Pages

Was this helpful?

 Resources More About Vercel Legal

Docs [Link] Commerce [Link] + Vercel Privacy Policy

Support Policy Contact Sales Open Source Software Cookie Preferences
Learn Community GitHub
Showcase GitHub Bluesky
Blog Releases X
Team Telemetry
Analytics Governance
[Link] Conf
Previews
Evals
Subscribe to our newsletter

Stay updated on new releases and

features, guides, and case studies.

you@[Link] Subscribe

© 2026 Vercel, Inc.