Understanding the `app` Directory and Its Conventions

The app directory is the root of the App Router. Learn the file names that matter and how folders map to URLs.

RuneHub Team
RuneHub Team
6 min read

The app directory is the root of the Next.js App Router. Every folder inside it maps to a URL segment, and a handful of file names have special meaning. Put the right file in the right folder and Next.js handles the route, the layout, and the page for you.

Here is a small app directory that produces three routes:

texttext
app/
  layout.tsx
  page.tsx
  blog/
    page.tsx
    [slug]/
      page.tsx

Each page file is a route, and each folder contributes one segment to the URL. The file system is the router, so there is no route table to configure.

Files and foldersResulting route
app/page.tsx/
app/blog/page.tsx/blog
app/blog/[slug]/page.tsx/blog/anything

The square brackets around slug make it a dynamic segment, so one file serves many URLs such as /blog/first-post and /blog/second-post.

The special file names

A page file is the only file a folder needs to become a visible route. It must default-export a React component, which Next.js renders for that segment, and it can be a server component or a client component.

The layout file wraps child pages with shared UI. The root layout at the top of the app directory is required and must include the html and body tags, because it is the outer shell of every page.

The route file creates an API endpoint instead of a page, exporting HTTP methods such as GET and POST. It is the convention for a route that returns JSON rather than markup.

What is not a route

Only special file names become routes. You can keep a components folder or a data file inside any segment, and they stay private unless they are named page, layout, or route. This colocation lets you group a page with the code only that page uses, instead of splitting related files across the project.

A folder name that starts with an underscore, such as _lib, is explicitly private and is ignored by the router. A folder wrapped in parentheses, such as (marketing), groups routes without adding to the URL. Both let you organize files without changing the routes users see.

The app directory is the one place to look whenever a route, a layout, or an endpoint misbehaves. For the full project layout, read Next.js Project Structure Explained. To see how folders map to URLs in detail, read How File-Based Routing Works in the Next.js App Router.

Rune AI

Rune AI

Key Insights

  • The app directory is the root of the App Router.
  • Folders map to URL segments, and special files create the UI.
  • page.tsx creates a page, layout.tsx wraps child routes.
  • The root layout is required and holds html and body tags.
  • Only page and route files make a segment public.
RunePowered by Rune AI

Frequently Asked Questions

Which file makes a folder a public route?

A page.tsx or route.ts file. Without one of those, the folder is just a place to keep related files, and the route is not reachable.

Is the root layout required?

Yes. The layout.tsx at the top of the app directory is required and must include the html and body tags.

Can I keep other files inside app?

Yes. Only special file names such as page, layout, and route become routes. Other files and folders are safely colocated unless their names match a convention.

Conclusion

The app directory turns folders into URL segments and reserves a few file names for pages, layouts, and APIs. Place the right file in the right folder and Next.js handles the rest.

Previous
Next.js Project Structure Explained: Files and Folders
6 min read
Next
How to Add Next.js to an Existing React Project
6 min read

More in this topic

`generateMetadata` Explained with Real Examples

What generateMetadata does, when it runs, and how to use it for real routes: awaited params, deduplicated data fetching, extending parent metadata, and returning a 404 from metadata.

Canonical URLs in Next.js: `metadataBase`, `alternates.canonical`, and Dynamic Pages

How canonical URLs work in the Next.js App Router: setting metadataBase once, writing alternates.canonical per route, handling dynamic segments, and what happens when the base URL is missing.

Open Graph and Twitter Card Metadata in Next.js

How to write Open Graph and Twitter card metadata in the Next.js App Router: the openGraph and twitter fields, automatic card defaults, article tags, and image merge rules.