You created your first application in the previous Next.js 16 Installation & Setup tutorial. Now it is time to understand what Next.js actually generated. A clear mental model of the project structure makes routing, layouts, data, and deployment much easier to learn.
This guide explains the current Next.js 16 App Router conventions, then separates those framework rules from optional team preferences. The website you are reading is PHP-based, so the trees below describe the Next.js learning project created in Blog 1, not this site's repository.
The Big Picture
A fresh project can vary with your create-next-app answers and future patch releases. This compact tree shows the core files in the TypeScript App Router project used throughout this series:
my-app/
|-- app/
| |-- favicon.ico
| |-- globals.css
| |-- layout.tsx
| `-- page.tsx
|-- public/
|-- eslint.config.mjs
|-- next.config.ts
|-- package.json
|-- postcss.config.mjs
`-- tsconfig.jsonThe app directory contains routes and route-related code. public contains static assets served from the base URL. Root files configure Next.js, TypeScript, CSS tooling, linting, dependencies, and scripts.
app/Routes and shared UI
layout.tsxShared UIpage.tsxRoute UIblog//blog
public/Static assets
package.jsonDependencies & scripts
next.config.*Next.js configuration
Understanding the app Directory
App Router uses file-system routing. Each folder inside app can represent a URL segment, and nesting folders creates nested segments. A folder alone does not automatically publish a page; the segment becomes publicly accessible when it contains a page or route file.
app/
|-- layout.tsx
|-- page.tsx -> /
`-- about/
`-- page.tsx -> /about
app/page.tsx/app/about/page.tsx/aboutapp/blog/page.tsx/blogapp/contact/page.tsx/contactWhat Is page.tsx?
A page.tsx file defines the UI that visitors see at a route. It exports a React component as the default export. Without a page or route file, ordinary files colocated in that segment are not directly exposed as a URL.
export default function AboutPage() {
return (
<main>
<h1>About</h1>
<p>Welcome to the about page.</p>
</main>
)
}Because this file sits at app/about/page.tsx, its URL is /about.
What Is layout.tsx?
A layout is shared UI for a route segment and its descendants. It receives a children prop containing the page or nested layout below it. Layouts preserve state and remain interactive across navigation, which makes them suitable for stable shells such as headers, sidebars, and footers.
import type { Metadata } from 'next'
import './globals.css'
export const metadata: Metadata = {
title: 'My App',
description: 'Learning the Next.js App Router',
}
export default function RootLayout({
children,
}: Readonly<{ children: React.ReactNode }>) {
return (
<html lang="en">
<body>{children}</body>
</html>
)
}The root layout is the top-most layout and must contain the html and body elements. The next tutorial, Blog #3: Next.js Layouts and Pages, will explore nesting and layout behavior in depth.
Nested Folders and Routes
Nesting route folders produces a matching URL path. For example, app/dashboard/settings/page.tsx maps to /dashboard/settings. Parent layouts, when present, wrap their child segments recursively.
Important App Router File Conventions
Next.js recognizes special filenames inside route segments. The TypeScript forms below are current App Router conventions:
| File | Purpose | Key idea |
|---|---|---|
page.tsx | Page UI | Makes a route publicly accessible |
layout.tsx | Shared UI | Wraps a segment and its descendants |
loading.tsx | Loading UI | Provides an instant loading state using Suspense |
error.tsx | Error UI | Creates an error boundary for a route segment; it is a Client Component |
not-found.tsx | Not-found UI | Renders when notFound() is called for that segment |
route.ts | Route handler | Handles HTTP methods with the Web Request and Response APIs |
Other conventions include template.tsx, default.tsx, metadata files, and advanced parallel or intercepting route folders. Learn these when a real interface needs them; a small application does not need every convention on day one.
What Is the public Folder?
The top-level public directory stores static assets such as images, fonts, and downloadable files. Files are referenced from the base URL, so public/logo.svg becomes /logo.svg.
public/
|-- logo.svg -> /logo.svg
|-- hero.webp -> /hero.webp
`-- icons/
`-- github.svg -> /icons/github.svgUse the built-in next/image component when its resizing, modern-format delivery, lazy loading, and layout-shift protection are useful. Never put API keys, passwords, private documents, or server-only files in public: visitors can request anything stored there.
Should You Use a src Directory?
Next.js supports an optional top-level src folder. It separates application code from root configuration, but it does not make the application faster and is not required.
srcapp/
components/
lib/srcsrc/
|-- app/
|-- components/
`-- lib/Choose one structure, configure import aliases accordingly, and stay consistent. If you use src, keep public and root configuration files outside it.
Components, lib, and Regular Folders
Folders such as components, lib, utils, types, and hooks are ordinary developer-created names. Next.js gives them no special routing behavior. A shared components folder might hold reusable interface elements; lib might hold data access, database utilities, server helpers, or configuration utilities.
You can keep globally reused code outside app, place shared code at the top of app, or colocate feature code with the route that consumes it. These are organization strategies, not framework requirements.
Route Groups, Private Folders, and Dynamic Routes
Route groups
Wrap a folder name in parentheses, such as (marketing), to organize routes without adding that group to the URL. For example, app/(marketing)/pricing/page.tsx still maps to /pricing. Groups are useful for applying a layout to selected routes or organizing sections by team or purpose.
Private folders
Prefix a folder with an underscore, such as _components. Next.js opts that folder and its descendants out of routing, making the intent of internal implementation code explicit. Private folders are useful but not required because ordinary colocated files are already safe when they do not use a routing convention.
Dynamic routes
Square brackets create a dynamic segment. A file at app/blog/[slug]/page.tsx can render URLs such as /blog/nextjs-project-structure. In current Next.js 16 examples, the page receives params as a promise, so an async page awaits it before reading slug.
export default async function BlogPost({
params,
}: {
params: Promise<{ slug: string }>
}) {
const { slug } = await params
return <h1>Post: {slug}</h1>
}Important Root Configuration Files
package.json
This manifest stores project metadata, dependencies, and scripts. The learning project created with the current generator uses the familiar commands below; your real file remains the source of truth.
{
"scripts": {
"dev": "next dev",
"build": "next build",
"start": "next start",
"lint": "eslint"
}
}next.config.*
This optional configuration file customizes framework behavior. Add options only when your application needs them; do not turn it into a collection of copied settings.
tsconfig.json
This controls TypeScript checking, compiler behavior, included files, and path aliases. Next.js writes required defaults during setup and can update necessary options when development starts.
eslint.config.mjs
The Blog 1 setup uses ESLint's flat configuration file. It loads the Next.js recommended rules and provides a separate lint command because Next.js 16 no longer runs lint automatically during next build.
A Practical Structure That Can Grow
For a small application, start with the folders you use today instead of creating an empty architecture for imagined features:
src/
|-- app/
|-- components/
|-- lib/
`-- types/A growing application can introduce route groups, route-local private folders, and clearer shared-component boundaries:
src/
|-- app/
| |-- (marketing)/
| |-- dashboard/
| | |-- _components/
| | `-- page.tsx
| `-- api/
|-- components/
| |-- ui/
| `-- shared/
|-- lib/
|-- hooks/
`-- types/This is an example architecture, not an official required structure. Colocation often improves maintenance because a route's UI and utilities change together, while global folders work well for code genuinely reused across unrelated routes.
Common Next.js Project Structure Mistakes
- Thinking every folder becomes a page. Folders define segments; a
pageorroutefile exposes a public route. - Confusing pages and layouts. A page supplies route-specific UI; a layout wraps its segment and descendants.
- Treating
componentsas mandatory. It is a helpful team convention, not a special Next.js directory. - Creating too many folders too early. Begin with real responsibilities, then introduce boundaries as the project grows.
- Putting secrets in
public. Every public asset is requestable from the browser. - Mixing Pages Router and App Router examples. Files such as
pages/_app.tsxbelong to a different routing model and should not be pasted into an App Router tree.
Special Next.js Conventions vs Regular Folders
| Name | Special to Next.js? | Purpose |
|---|---|---|
app | Yes | App Router root |
page.tsx | Yes | Route UI |
layout.tsx | Yes | Shared layout UI |
public | Yes | Static files served from the base URL |
components | No | Developer organization |
lib | No | Developer organization |
utils | No | Developer organization |
Frequently Asked Questions
What is the app folder in Next.js?
It is the root of App Router routing. Nested folders define segments, and special files provide pages, layouts, loading states, error handling, endpoints, and metadata.
What is the difference between page.tsx and layout.tsx?
A page exposes route-specific UI. A layout wraps that page and child segments with shared UI.
Does every folder inside app become a route?
No. A segment is not publicly accessible until a page or route file exists. Route groups and private folders also have special non-URL behavior.
Do I need a components folder?
No. Use one if it makes shared UI easier to find, but Next.js does not require or interpret the name.
Should I use the src directory?
It is optional. Use it when separating application code from configuration improves clarity for your project or team.
What is the public folder used for?
It serves static files from the base URL. Keep only assets intended to be publicly accessible there.
Where should API routes go in App Router?
Create a route.ts handler in the relevant app segment, commonly below app/api. A route.ts and page.tsx cannot share the same route segment level.
Official Resources
Use the current Next.js project structure and organization guide for the complete convention list. The official guides to layouts and pages and image optimization provide deeper explanations for the two most important follow-up topics.
