Folder Structure

Master Next.js project organization and understand how folders control your application's behavior and routing.

Next.js has strong opinions about how you organize your code. Unlike plain React where you can put components anywhere, Next.js uses folder structure to determine routes, control rendering, and optimize your application.

The NewsWave team needs a well-organized project that scales from a dozen articles to thousands. Your folder structure becomes the blueprint for both your application's URLs and its performance characteristics.

App Router vs Pages Router

Next.js 13 introduced the App Router — a new way to organize your application. You'll see both patterns in the wild, but App Router is the future.

We'll focus on App Router since that's what modern Next.js applications use. But understanding both helps when you encounter older codebases.

Core Folder Structure

When you run create-next-app, Next.js creates a specific folder structure. Each folder has a purpose.

The app/ directory is where the magic happens. Every folder inside becomes a route. Every special file controls behavior.

Special Files in App Router

Next.js reserves certain filenames for specific purposes. These aren't arbitrary — they're how Next.js understands your application structure.

Without page.js, your folder is just organizational. Add page.js and boom — it becomes a route users can visit.

// app/articles/page.js — Creates /articles route
export default function ArticlesPage() {
  return (
    <div>
      <h1>NewsWave Articles</h1>
      <p>Browse our latest stories</p>
    </div>
  )
}

NewsWave Folder Organization

Here's how we'll organize the NewsWave project for maximum scalability and developer experience:

Notice how folder names become URLs. The [slug] and [name] folders use square brackets — those are dynamic routes that accept parameters.

Route Groups and Private Folders

Sometimes you want to organize folders without affecting URLs. Next.js provides two special folder patterns:

// Route Groups — organize without URL impact
app/
├── (marketing)/           // ← Parentheses = route group
│   ├── about/
│   │   └── page.js       // → /about (not /marketing/about)
│   └── contact/
│       └── page.js       // → /contact
└── (news)/
    ├── articles/
    │   └── page.js       // → /articles
    └── category/
        └── page.js       // → /category

// Private Folders — never become routes
app/
├── _components/          // ← Underscore = private
│   ├── Button.js        // Private component
│   └── Modal.js
├── _utils/
│   └── helpers.js       // Private utilities
└── articles/
    └── page.js          // → /articles (public route)

Route groups help you organize code by feature area. Private folders keep implementation details out of your routing system.

Component Organization Patterns

Beyond the app/ directory, you need patterns for organizing reusable code. Here are three proven approaches:

Colocation wins because it reduces the mental overhead of finding related code. When you're working on the search feature, everything you need is in the search/ folder.

Public Folder and Static Assets

The public/ folder serves static files directly from your domain root. No processing, no optimization — just raw files served at lightning speed.

// Files in public/ are served from domain root
public/
├── logo.png              // → yoursite.com/logo.png
├── favicon.ico           // → yoursite.com/favicon.ico
├── robots.txt           // → yoursite.com/robots.txt
└── images/
    └── hero-bg.jpg      // → yoursite.com/images/hero-bg.jpg

// Use them in components like this:
<img src="/logo.png" alt="NewsWave Logo" />
<link rel="icon" href="/favicon.ico" />

For NewsWave, public/ holds the logo, favicon, and any static images that are part of the design. Article images would come from a CDN or cloud storage.

Configuration Files

Your Next.js project root contains several configuration files that control build behavior, dependencies, and development experience:

The most important is next.config.js — where you customize Next.js behavior:

// next.config.js — NewsWave configuration
/** @type {import('next').NextConfig} */
const nextConfig = {
  // Enable image domains for external images
  images: {
    domains: ['images.unsplash.com', 'cdn.newswave.com']
  },
  
  // Experimental App Router features
  experimental: {
    appDir: true,
  },
  
  // Environment-specific settings
  env: {
    SITE_NAME: 'NewsWave',
    SITE_URL: 'https://newswave.com'
  }
}

module.exports = nextConfig

Best Practices and Common Mistakes

After organizing hundreds of Next.js projects, here are the patterns that consistently work and the mistakes that consistently hurt:

Remember: your folder structure is your application's skeleton. It should make sense to someone seeing the code for the first time. If you're constantly confused about where to put files, your structure needs work.

Quiz