Next.js Project Structure

A typical Next.js project contains specific files and directories. Understanding their roles helps you better organize and develop your application.

Top-Level Files and Directories

When you create a new project using create-next-app, you'll see the following basic structure:

my-next-app/
├── .next/
├── node_modules/
├── pages/
│   ├── _app.js
│   ├── api/
│   │   └── hello.js
│   └── index.js
├── public/
│   ├── favicon.ico
│   └── vercel.svg
├── styles/
│   ├── globals.css
│   └── Home.module.css
├── .eslintrc.json
├── .gitignore
├── next.config.js
├── package.json
├── README.md
└── yarn.lock

Let's understand the purpose of each file and directory.

`.next`

This is the Next.js build directory, containing compiled code, cache, and static assets. You don't need to manually modify anything in this directory; Next.js automatically manages it during build and development.

`node_modules`

Contains all project dependencies. When you run npm install or yarn, dependencies are downloaded to this directory.

`pages`

This is one of the most important directories in Next.js, used for file system routing.

Page Routing: Each React component in the pages directory maps to a route. For example, pages/about.js corresponds to the /about route, and pages/posts/first-post.js corresponds to /posts/first-post.
index.js: The index.js file in each directory serves as the root route for that directory. For example, pages/index.js is the homepage (/), and pages/posts/index.js is the /posts route.
_app.js: A special component used to initialize all pages. You can add global styles, layouts, or state management here.
_document.js: Another special component used to customize the HTML document structure returned by the server. Typically used to add attributes to <html> and <body>.
api Directory: Files in pages/api are mapped as API routes. For example, pages/api/user.js creates a /api/user API endpoint.

`public`

Used to store static assets such as images, fonts, and icons. Files in the public directory can be accessed directly from the application's root path. For example, public/my-image.png can be accessed via /my-image.png.

`styles`

Contains the application's style files. Next.js supports multiple styling solutions:

Global Styles: The styles/globals.css file is used for global styles and needs to be imported in pages/_app.js.
CSS Modules: Files ending with .module.css are CSS Modules. They generate unique class names to avoid style conflicts. For example, styles/Home.module.css.

`components` (Optional)

Although create-next-app doesn't create a components directory by default, it's usually recommended to create one for storing reusable React components such as navigation bars, buttons, and cards. This helps keep the code clean and maintainable.

Configuration Files

.eslintrc.json: ESLint configuration file for code standards and error checking.
.gitignore: Tells Git which files or directories shouldn't be included in version control, such as .next and node_modules.
next.config.js: The main Next.js configuration file. You can configure environment variables, redirects, proxies, Webpack, and other advanced features here.
package.json: Project metadata file containing project name, version, dependencies, and script commands.
README.md: Project documentation, typically containing project introduction, installation, and usage instructions.

App Router (Next.js 13+)

Starting from Next.js 13, a new App Router was introduced, using the app directory instead of pages. The App Router brings more powerful layout features and server components.

If your project uses the App Router, the project structure will be somewhat different:

my-next-app/
├── app/
│   ├── layout.js
│   └── page.js
...

app Directory: Stores App Router pages, layouts, and components.
layout.js: Defines shared UI layouts.
page.js: Defines page UI content.

This tutorial is mainly based on the pages directory, but understanding the App Router is very important for learning the latest Next.js.

Summary

Understanding the Next.js project structure is the foundation for efficient development. By properly organizing files and directories, you can build clear, maintainable web applications.

Previous Chapter: Next.js Installation | Next Chapter: Next.js Project Explanation

Next.js Project Structure ​

Top-Level Files and Directories ​

.next ​

node_modules ​

pages ​

public ​

styles ​

components (Optional) ​

Configuration Files ​

App Router (Next.js 13+) ​

Summary ​