Skip to content
Tutorials Center
My learning

Topics

Lesson 3 of 72 ยท Getting Started

Project Structure

A tour of a Next.js project: the app folder, public, config files, special file names, colocation, private folders, route groups and the src directory.

A Next.js project is mostly ordinary folders and files, but a handful of names carry special meaning. Once you know which names are special and which folders are ignored by the router, you can read any Next.js codebase and organize your own with confidence.

This lesson is a tour. We will walk through the top level, then the app folder, then the file names the framework recognizes, and finally the rules that let you keep your own helper code next to your pages without accidentally creating URLs. Every project tree here is read-only, and the live examples are stand-ins that apply the same naming rules to a list of files you can read.

The top level

Here is a project after a few features have been added:

TEXT
my-app/
  app/                 routes, layouts and the UI that belongs to them
  public/              static files served from the site root
  src/                 optional: holds app/ when you choose the src layout
  .env.local           environment variables (never committed)
  next.config.ts       Next.js configuration
  package.json         dependencies and scripts
  proxy.ts             optional: code that runs before requests (Next.js 16)
  tsconfig.json        TypeScript settings
  • app/ is the heart of the project. Folders inside it are URL segments, and special files inside those folders define the pages.
  • public/ holds static assets. A file at public/logo.svg is available at /logo.svg. Anything here is public to the whole world and is not processed by the bundler, so put images, fonts you self-host by hand, robots.txt and similar files here.
  • next.config.ts configures the framework. It exports an object; a fresh project exports an almost empty one. We cover it in depth in Configuring Next.js.
  • .env.local and related .env* files hold environment variables. Local files are for your machine and belong in .gitignore.
  • proxy.ts (called middleware.ts before Next.js 16) is an optional file at the root that runs before a request reaches your routes. See Middleware and the Proxy File.
  • package.json and tsconfig.json work like they do in any Node.js and TypeScript project.

The src directory

If you choose the src option, create-next-app puts the code folder inside it: src/app/page.tsx instead of app/page.tsx. Only your source moves. public/, next.config.ts, package.json, the .env* files and other config stay at the project root. Some teams like this because it separates code from configuration; others prefer the shorter paths. It makes no difference to how Next.js works. Pick one layout and keep to it, and do not keep an app folder in both places.

Inside the app folder

The app folder uses folders for URLs and files for roles. A folder becomes a URL segment, and the files inside it say what that segment shows:

TEXT
app/
  layout.tsx           wraps every page (required at the top)
  page.tsx             the home page, URL: /
  globals.css          global styles
  dashboard/
    layout.tsx         wraps pages under /dashboard
    page.tsx           URL: /dashboard
    loading.tsx        shown while the page loads
    error.tsx          shown when something throws
    _components/
      chart.tsx        private helper, not routable
  (marketing)/
    pricing/
      page.tsx         URL: /pricing  (the group name is not in the URL)
  api/
    health/
      route.ts         an HTTP endpoint at /api/health

The key rule is that a folder is not publicly reachable until it contains a page file or a route file. Making a folder named dashboard alone does nothing. Adding dashboard/page.tsx creates the URL /dashboard. This is what lets you put any other file next to a page safely.

The special file names

Next.js recognizes certain file names (with .js, .jsx, .ts or .tsx extensions) inside app. Each one has a single job:

File Job
page The unique UI of a route; makes it public
layout Shared UI wrapped around a segment and its children
template Like a layout, but re-created on every navigation
loading Instant loading UI shown while a segment streams in
error Error UI for a segment
global-error Error UI for the root layout itself
not-found UI for unknown URLs, or when you call notFound()
default Fallback for parallel routes
route An HTTP endpoint instead of a page

There are also file names for metadata: favicon.ico, icon, apple-icon, opengraph-image, robots, sitemap. You can drop an image in, or write a small function that generates the file. A few more live outside app: proxy (or middleware in older versions) and instrumentation.

Every one of these gets its own lesson later; for now, just learn to recognize them. A page folder usually contains two or three of them, and the names tell you what a file does before you open it. Because the roles are fixed, there is no argument about where error handling or loading screens should go: they go in a file with the matching name.

Colocation

Because only page and route files create URLs, you can colocate everything a page needs in its own folder: components, styles, tests, helper functions, data helpers. Nothing becomes a route by accident.

TEXT
app/blog/
  page.tsx
  post-card.tsx          colocated component, not a route
  post-card.module.css   its styles
  get-posts.ts           its data helper
  post-card.test.tsx     its test

Some teams prefer to keep shared code outside app entirely, in folders such as components/, lib/ or src/lib/, and use the @/ alias to import it. Both approaches work, and many projects combine them: truly shared code outside, page-specific code beside the page.

Private folders and route groups

Two folder-name conventions help you organize without changing URLs. We preview them here and cover them fully in Route Groups and Private Folders.

  • Private folders start with an underscore: _components, _lib. The router ignores the folder and everything under it, so it can never become a route. This is useful for making your intent clear to your teammates and to editors that sort files by name.
  • Route groups are wrapped in parentheses: (marketing), (shop). The parentheses mean "organize here, but leave this out of the URL", so app/(marketing)/pricing/page.tsx serves /pricing. Groups also let different sections of a site have different layouts.

Other symbols appear in folder names too: square brackets for dynamic segments ([slug]), an @ for parallel route slots and dots in parentheses for intercepting routes. You will meet each of them in the Routing chapter, starting with File-Based Routing.

Try it: which files are routes?

Real framework or stand-in? The two live examples below do not run Next.js. They apply the naming rules from this lesson to a list of file paths, to show what the router would see. Real Next.js reads your real folders and also handles dynamic segments, slots and more.

The first example is a Node.js program that classifies each file in a project tree as a page, an endpoint, a special file, a metadata file, private or simply colocated.

Node.js Classify every file in the app folder

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Look at app/dashboard/chart.tsx and app/globals.css: they sit in route folders, yet they are just colocated files. Then look at (marketing)/pricing/page.tsx, whose URL is /pricing because the group name is dropped.

The second example is an interactive explorer. Click a file to see its role. It is a hand-written model of a typical tree, so you can use it as a flash card for the names.

Click a file to learn its role

A sensible way to organize

You do not need a perfect structure on day one. A common starting point is: routes and their private helpers inside app, shared UI in components/, shared logic such as database code in lib/, and static assets in public/. Move things around when pain appears. Because folders in app map to URLs, renaming a route folder changes the URL, so rename carefully on live sites.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What makes a folder inside app publicly reachable as a URL?

    A folder only becomes a URL when it contains a page file (a UI route) or a route file (an HTTP endpoint). Other files next to them are ignored by the router.
  2. 2. Where does app/(marketing)/pricing/page.tsx get served?

    Parentheses mark a route group. The group name organizes files but is left out of the URL.
  3. 3. Which statement about public/logo.svg is true?

    Files in public are served from the site root exactly as they are.
  4. 4. What does a leading underscore on a folder name, like _components, do?

    Private folders opt a whole folder out of routing. They do not change what runs on the server or the browser.
  5. 5. When you choose the src directory option, which of these moves into src?

    Only the source folders move. Configuration files, package.json, public and the .env files stay at the project root.

Summary

  • The top level holds app/ (routes), public/ (static files), config files such as next.config.ts, environment files and optionally proxy.ts.
  • Folders in app are URL segments; a folder is only reachable if it contains page or route.
  • Special file names (layout, loading, error, not-found, template, default, route) each have one fixed job.
  • You can colocate components, styles and tests next to a page without creating routes.
  • _private folders are ignored by the router, and (groups) organize files without adding to the URL.
  • The src option moves only the source folders; configuration stays at the root.

Next: How a Request Flows Through Next.js