Next.js Project Structure Guide

Learn how to organize Next.js projects using the App Router and create a scalable, maintainable code structure.

After learning how to configure NextDevKit development tools, we'll start learning about our code and project structure.

Before learning specific NextDevKit code details, let's first understand NextDevKit's code structure. Since NextDevKit is a production-ready SaaS template, the code structure is already complex. This tutorial will start from the simplest Next.js project structure and teach you step by step how NextDevKit's code structure is organized and built.

Understanding Next.js App Router

NextDevKit uses Next.js App Router instead of monorepo architecture to reduce complexity and learning costs. It's a modern approach to building React applications with enhanced features:

File-based routing: Create pages by adding files to the app directory
Server and Client Components: Better performance through strategic rendering
Route Groups: Organize routes without affecting URL structure
Parallel Routes: Display multiple pages in the same layout simultaneously

Step 1: Basic Core Files

To understand NextDevKit's code structure, let's start with the simplest Next.js project file structure.

Besides configuration files, every Next.js project starts with 2 core files:

layout.tsx - Defines the root layout that contains all pages (can define header, footer, navigation, affects all pages in this directory)
page.tsx - Creates the homepage that users see when visiting

These two files form the foundation of your Next.js application.

layout.tsx

page.tsx

next.config.ts

package.json

tsconfig.json

App Router Core Concepts:

layout.tsx: Shared UI for its children. Layouts maintain state and stay interactive
page.tsx: Unique UI of a route, makes routes publicly accessible
loading.tsx: Loading UI shown instantly while page content loads
error.tsx: Error UI shown when something goes wrong
not-found.tsx: UI shown when notFound function is thrown

Step 2: Adding Page Routes

To create new pages and routes, simply create folders containing page.tsx files:

/pricing folder + page.tsx → Creates pricing page
/contact folder + page.tsx → Creates contact page
/blog folder + page.tsx → Creates blog page

Next.js uses file-system routing to automatically convert these folders into accessible pages.

page.tsx

layout.tsx

page.tsx

loading.tsx

not-found.tsx

next.config.ts

package.json

tsconfig.json

Dynamic Routes:

[slug] - Dynamic segment (e.g., /blog/hello-world)
[...slug] - Catch-all segment (e.g., /blog/2024/hello-world)
[[...slug]] - Optional catch-all segment

Dynamic routes are very useful for rendering pages like blogs, docs, and dynamic data. You can see examples of dynamic routes in the blog pages in NextDevKit code.

Step 3: Using Route Groups and Layouts for Organization

As features grow, having all pages in the same directory becomes hard to maintain. We need to use route groups and nested layouts for better organization:

Route Groups:

(marketing)/ - Organize marketing pages (pricing, contact, blog)
(app)/ - Organize app pages (dashboard, settings)

Internationalization:

[locale]/ - Automatically handle different languages (Chinese, English, etc.)

Important Note: Parentheses () organize code but don't affect URL. They only help organize your code directories and routes better, without affecting your actual URL. [locale] represents i18n routing, this config will affect your URL, for example your page routes will accept /zh/pricing and /en/pricing.

layout.tsx

page.tsx

layout.tsx

page.tsx

layout.tsx

page.tsx

loading.tsx

page.tsx

layout.tsx

page.tsx

next.config.ts

package.json

tsconfig.json

Step 4: Adding Server-Side Functionality

Besides page routes, Next.js also supports defining API routes through the file system. We need API routes to implement backend, Auth, and third-party integrations like Stripe.

Adding API Routes:

API Routes:

api/auth/ - Handle user authentication
api/search/ - Provide search functionality
api/webhooks/ - Webhook handlers for third-party services

Route Handlers:

route.ts - Handle GET, POST, PUT, DELETE requests

layout.tsx

page.tsx

route.ts

layout.tsx

page.tsx

button.tsx

input.tsx

next.config.ts

package.json

tsconfig.json

Besides APIs can operate the database, we can also directly use server components to get database data and render pages. We'll talk about this later.

Step 5: Component Architecture

After understanding NextDevKit's basic code structure, we'll learn how to organize and reuse frontend UI components.

UI Components (Design System):

components/ui/ - shadcn ui primitive base components (buttons, inputs, dialogs)
components/auth/ - Authentication specific components
components/marketing/ - Marketing page components
components/dashboard/ - App specific components

Server vs Client Components:

Server Components: Default, render on server
Client Components: Use 'use client', handle interactions and state

layout.tsx

page.tsx

button.tsx

input.tsx

dialog.tsx

data-table.tsx

signup-form.tsx

social-signin.tsx

hero-section.tsx

pricing-card.tsx

testimonials.tsx

stats-cards.tsx

recent-activity.tsx

user-profile.tsx

client.ts

server.ts

api.ts

use-mobile.ts

use-session.ts

use-payment.ts

utils.ts

validations.ts

Step 6: Production-Ready Architecture

For enterprise applications, besides the basic frontend features above, we need to implement these core modules:

Business Logic Modules:

actions/ - Server actions for data mutations
mail/ - Email sending functionality
payment/ - Payment processing and subscriptions
storage/ - File storage management

Data Layer:

database/ - Database schema and data management

Configuration and Content:

config/ - Application configuration
content/ - MDX content for blogs and docs
messages/ - Internationalization files

All marketing pages...

page.tsx

All your backend APIs...

More components...

utils.ts

user-actions.ts

post-actions.ts

Send emails to users

Handle payments & subscriptions

Store files & images

schema.ts

migrations/

en.json

zh.json

next.config.ts

package.json

At this point, we have an organization structure very similar to a complete production-ready NextDevKit project. I believe you now have a basic understanding of NextDevKit's project directory structure. If you still have questions, you can ask AI based on NextDevKit's current code structure for help. Below are some App Router best practices.

App Router Best Practices

Server vs Client Components Strategy

Use Server Components for:

Fetching data from databases or APIs
Accessing backend services
Large dependencies that should stay on server
SEO-sensitive content

Use Client Components for:

Interactive elements (onClick, onChange, etc.)
Browser-only APIs (localStorage, geolocation)
State management (useState, useReducer)
Effects and lifecycle methods (useEffect)

Performance Optimization

Route-Level Optimizations:

Loading UI: Use loading.tsx to provide instant loading states
Streaming: Progressive page rendering with React Suspense
Parallel Data Fetching: Fetch data in parallel in layouts and pages
Static Generation: Pre-build pages at build time when possible

On this page