Project structure overview in NextJS - Deep Dive

Overview - Project structure overview

What is it?

Project structure overview in Next.js explains how files and folders are organized in a Next.js app. It shows where to put pages, components, styles, and other resources. This structure helps Next.js know how to build and serve your website efficiently. Understanding it makes building and scaling apps easier.

Why it matters

Without a clear project structure, your code becomes messy and hard to maintain. Next.js uses its structure to automatically handle routing, server rendering, and static generation. If you don't follow this structure, your app won't work as expected, and you will waste time fixing errors. A good structure saves time and helps teams work together smoothly.

Where it fits

Before learning project structure, you should know basic JavaScript and React concepts. After understanding the structure, you can learn about routing, data fetching, and deployment in Next.js. This topic is an early step in mastering Next.js development.

Mental Model

Core Idea

Next.js project structure is a set of folders and files arranged so the framework can automatically create pages, handle routing, and manage resources without extra setup.

Think of it like...

It's like organizing a kitchen: you keep pots in one cabinet, spices in another, and utensils in a drawer. When you cook, you know exactly where to find what you need, and the kitchen works smoothly.

┌─────────────────────────────┐
│        nextjs-project       │
├──────────────┬──────────────┤
│ pages/       │ components/  │
│ ├ index.js   │ ├ Header.js  │
│ ├ about.js   │ ├ Footer.js  │
│ └ api/       │              │
│   └ hello.js │              │
├──────────────┴──────────────┤
│ public/                    │
│ ├ favicon.ico             │
│ └ images/                 │
├ styles/                    │
│ └ globals.css             │
└─────────────────────────────┘

Build-Up - 7 Steps

1

Foundation

Basic folder roles in Next.js

Concept: Learn the main folders and their purposes in a Next.js project.

The 'pages' folder contains files that become website pages automatically. Each file inside 'pages' is a route. The 'components' folder holds reusable UI parts like buttons or headers. The 'public' folder stores static files like images or icons that the browser can access directly. The 'styles' folder contains CSS files for styling the app.

Result

You understand where to put pages, UI parts, static files, and styles in your project.

Knowing folder roles helps you organize code so Next.js can build your app without extra configuration.

2

Foundation

How pages map to routes

Concept: Files inside the 'pages' folder automatically become routes in the app.

If you create 'pages/index.js', it becomes the home page at '/'. A file 'pages/about.js' becomes the '/about' page. Nested folders create nested routes, like 'pages/blog/post.js' becomes '/blog/post'. This automatic routing means you don't write route code manually.

Result

You can create new pages just by adding files in the right place.

Understanding automatic routing saves time and reduces errors in navigation setup.

3

Intermediate

API routes inside pages/api

🤔Before reading on: do you think API routes are defined in a separate folder or inside 'pages/api'? Commit to your answer.

Concept: Next.js lets you create backend API endpoints inside the 'pages/api' folder.

Files inside 'pages/api' become serverless functions. For example, 'pages/api/hello.js' defines an API endpoint at '/api/hello'. These functions run on the server and can handle requests like fetching data or processing forms.

Result

You can build backend logic without a separate server setup.

Knowing API routes are part of the project structure helps you build full-stack apps in one place.

4

Intermediate

Static assets in the public folder

🤔Before reading on: do you think files in 'public' are imported in code or accessed by URL? Commit to your answer.

Concept: Static files in 'public' are served directly by the server and accessed by URL paths.

If you put 'logo.png' in 'public', you can use it in your app with '/logo.png' URL. You don't import these files in JavaScript; instead, you reference them in HTML or CSS. This folder is for images, fonts, or other files that don't change.

Result

You can add images and other static files easily and use them in your app.

Understanding how static assets are served prevents confusion about file paths and loading resources.

5

Intermediate

Styling organization with styles folder

Concept: The 'styles' folder holds CSS files that style your app globally or per component.

You can put global CSS files like 'globals.css' here and import them in your app entry point. You can also create CSS modules for component-level styles. This keeps styles organized and scoped properly.

Result

Your app looks good and styles are easy to manage and update.

Knowing where and how to organize styles helps maintain consistent design and avoid style conflicts.

6

Advanced

App Router and new folder structure

🤔Before reading on: do you think Next.js uses only 'pages' folder for routing or also 'app' folder? Commit to your answer.

Concept: Next.js 13 introduced the 'app' folder as a new way to organize routes and layouts with React Server Components.

The 'app' folder replaces or works alongside 'pages'. It allows nested layouts, loading states, and server components by default. Files like 'app/page.js' define routes, and folders can have 'layout.js' for shared UI. This structure improves flexibility and performance.

Result

You can build modern Next.js apps with better routing and UI patterns.

Understanding the 'app' folder is key to using the latest Next.js features and writing scalable apps.

7

Expert

Customizing structure with config files

🤔Before reading on: do you think Next.js requires strict folder names or allows customization? Commit to your answer.

Concept: Next.js allows some customization of the project structure using configuration files like next.config.js.

You can customize build settings, add aliases for imports, or change output folders. However, core folders like 'pages' or 'app' have special meaning and should be used carefully. Customizing structure helps integrate with complex projects or tools.

Result

You can adapt Next.js to fit unique project needs without losing framework benefits.

Knowing when and how to customize structure prevents breaking automatic features and supports advanced workflows.

Under the Hood

Next.js scans the project folders like 'pages' or 'app' at build time to create a routing map. Each file corresponds to a route or API endpoint. The framework bundles components and styles, and serves static files from 'public' directly. The new 'app' folder uses React Server Components to split rendering between server and client, improving performance.

Why designed this way?

Next.js was designed to reduce manual setup by using conventions over configuration. Automatic routing and folder roles let developers focus on building features, not wiring routes. The 'app' folder was introduced to leverage React's latest capabilities and simplify complex UI patterns. This design balances ease of use with flexibility.

┌───────────────┐       ┌───────────────┐
│  pages/       │──────▶│ Routing Map   │
│  ├ index.js   │       └───────────────┘
│  ├ about.js   │               │
│  └ api/       │               ▼
│    └ hello.js │         ┌───────────────┐
└───────────────┘         │ Serverless    │
                          │ Functions     │
┌───────────────┐         └───────────────┘
│ public/       │
│  ├ logo.png   │────────▶ Served as URL
└───────────────┘

┌───────────────┐
│ app/          │
│  ├ page.js    │
│  └ layout.js  │
└───────────────┘
       │
       ▼
 React Server Components
       │
       ▼
  Rendered UI

Myth Busters - 4 Common Misconceptions

Quick: Do you think you can put any file anywhere and Next.js will route it automatically? Commit to yes or no.

Common Belief: I can put page files anywhere in the project and Next.js will create routes for them.

Reality: Only files inside the 'pages' or 'app' folders are used for routing. Files elsewhere are ignored for routing purposes.

Why it matters: Placing files outside these folders means your pages won't appear, causing broken navigation and confusion.

Quick: Do you think files in 'public' are imported in JavaScript code? Commit to yes or no.

Common Belief: Static files in 'public' should be imported like modules in JavaScript code.

Reality: Files in 'public' are accessed by URL paths, not imported. Importing them will cause errors or bundling issues.

Why it matters: Misusing 'public' files leads to broken images or failed builds, wasting development time.

Quick: Do you think the 'app' folder replaces 'pages' completely in all Next.js versions? Commit to yes or no.

Common Belief: The 'app' folder is mandatory and replaces 'pages' in all Next.js projects now.

Reality: The 'app' folder is optional and introduced in Next.js 13. Older projects or versions still use 'pages'. Both can coexist during migration.

Why it matters: Assuming 'app' is mandatory can cause confusion or errors when working with older projects or tutorials.

Quick: Do you think you can freely rename the 'pages' folder to something else? Commit to yes or no.

Common Belief: I can rename the 'pages' folder to any name I want and Next.js will still work.

Reality: The 'pages' folder name is special and required for routing. Renaming it breaks automatic routing unless you configure custom settings, which is rare and complex.

Why it matters: Renaming core folders without proper setup causes your app to fail routing, leading to wasted debugging time.

Expert Zone

1

The 'app' folder uses React Server Components by default, which means components inside it run on the server unless marked otherwise, improving performance but requiring understanding of server vs client boundaries.

2

Next.js supports module path aliases configured in 'jsconfig.json' or 'tsconfig.json' to simplify imports, but misconfiguring them can cause confusing errors that are hard to debug.

3

Static files in 'public' are cached aggressively by browsers, so updating them requires cache busting strategies like changing file names or query strings.

When NOT to use

If your project requires a highly customized routing system or non-React frontend, Next.js default project structure may be limiting. In such cases, consider frameworks like Remix or custom Express servers where routing and structure are fully manual.

Production Patterns

In production, teams often separate 'components' into subfolders by feature or domain for scalability. They use the 'app' folder for layouts and server components, and keep 'pages/api' for lightweight backend routes. Static assets are optimized and served via CDNs from 'public'. Configuration files manage environment variables and build optimizations.

Connections

Convention over Configuration

Next.js project structure is an example of this software design principle.

Understanding this principle helps grasp why Next.js enforces specific folders and file names to reduce setup and errors.

React Server Components

The 'app' folder structure in Next.js builds on React Server Components to improve rendering.

Knowing React Server Components clarifies why the new folder structure changes how components are rendered and organized.

Library Organization in a Kitchen

Both organize resources by type and usage for efficiency.

Recognizing that organizing code folders is like organizing kitchen tools helps appreciate the importance of structure for smooth workflows.

Common Pitfalls

#1 Placing page files outside the 'pages' or 'app' folder expecting them to become routes.

Wrong approach:

Create a file 'src/home.js' and expect it to be accessible at '/home'.

Correct approach:

Create 'pages/home.js' or 'app/home/page.js' to define the route properly.

Root cause:

Misunderstanding that Next.js only scans specific folders for routing.

#2 Importing images from the 'public' folder in JavaScript code.

Wrong approach:

import logo from '../public/logo.png';

Correct approach:

Use without importing the file.

Root cause:

Confusing static asset serving with module imports.

#3 Renaming the 'pages' folder to 'screens' without configuration.

Wrong approach:

Rename 'pages' to 'screens' and expect routing to work.

Correct approach:

Keep the folder named 'pages' or use the 'app' folder for routing.

Root cause:

Not knowing that folder names have special meaning in Next.js.

Key Takeaways

Next.js uses a special project structure where folders like 'pages', 'app', 'components', and 'public' have clear roles.

Files inside 'pages' or 'app' folders automatically become routes, simplifying navigation setup.

Static files in 'public' are served directly by URL and should not be imported in code.

The new 'app' folder introduced in Next.js 13 enables advanced routing and server components.

Following the structure conventions is essential for Next.js to build and run your app correctly.