Next.js Project Structure

⏱ Estimated reading time: 2 min

Next.js provides a clean and organized project structure that helps developers build scalable and maintainable applications. Below is an overview of the commonly used Next.js project structure (App Router).

Basic Project Structure

my-next-app/
│── app/
│   ├── layout.js
│   ├── page.js
│   ├── loading.js
│   ├── error.js
│   ├── not-found.js
│   └── globals.css
│
│── components/
│── public/
│── styles/
│── lib/
│── hooks/
│
│── next.config.js
│── package.json
│── jsconfig.json / tsconfig.json
│── .env.local

Explanation of Important Folders & Files

app/

The core directory used for routing and rendering.

• page.js – Defines a route and renders UI for that page

• layout.js – Shared layout across pages (header, footer, etc.)

• loading.js – Loading UI while page data is being fetched

• error.js – Handles runtime errors in routes

• not-found.js – Custom 404 page

• globals.css – Global styles for the application

components/

Contains reusable UI components such as buttons, headers, cards, and forms.

public/

Stores static assets like images, fonts, icons, and videos. Files here are directly accessible via URL.

styles/

Used for CSS files, CSS Modules, or other styling-related files (if not using Tailwind).

lib/

Contains utility functions, API helpers, database connections, and shared logic.

hooks/

Custom React hooks used across the application.

Configuration Files

• next.config.js – Next.js configuration settings

• package.json – Project dependencies and scripts

• jsconfig.json / tsconfig.json – Path aliases and TypeScript configuration

• .env.local – Environment variables

Example: Route Structure

app/
├── blog/
│   └── page.js      → /blog
├── blog/[slug]/
│   └── page.js      → /blog/my-post
├── dashboard/
│   ├── layout.js
│   └── page.js      → /dashboard

Pages Router (Older Structure)

Older Next.js versions use the pages/ directory:

pages/
├── index.js         → /
├── about.js         → /about
├── api/
│   └── users.js     → /api/users

Note: The App Router (app/) is recommended for new projects.

Conclusion

The Next.js project structure is designed to be modular, scalable, and easy to maintain. Understanding this structure helps you organize code efficiently and build large applications with confidence.