Project Structure

Project Structure & Organization

Next.js is unopinionated about how you organize your project. This skill provides proven patterns for small, medium, and large applications.

File Conventions (Next.js 16)

These files have special meaning inside app/:

Top-level files:

Recommended Structures

Small App (< 10 routes)

Keep everything colocated in app/. Shared code in top-level folders:

src/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── about/
│   │   └── page.tsx
│   └── blog/
│       ├── page.tsx
│       └── [slug]/
│           └── page.tsx
├── components/
│   ├── header.tsx
│   └── footer.tsx
├── lib/
│   └── utils.ts
└── public/
    └── images/

Medium App (10–30 routes)

Use route groups for organizational separation and colocate related code:

src/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── (marketing)/
│   │   ├── layout.tsx
│   │   ├── about/page.tsx
│   │   ├── blog/page.tsx
│   │   └── pricing/page.tsx
│   ├── (dashboard)/
│   │   ├── layout.tsx
│   │   ├── dashboard/page.tsx
│   │   ├── settings/page.tsx
│   │   └── _components/        # Private folder — not routable
│   │       ├── sidebar.tsx
│   │       └── nav.tsx
│   └── api/
│       └── webhooks/
│           └── route.ts
├── components/                  # Shared UI components
│   ├── ui/                      # Primitives (button, input, card)
│   └── shared/                  # Composed components (data-table, file-upload)
├── lib/
│   ├── db.ts                    # Database client
│   ├── utils.ts                 # Generic utilities
│   └── constants.ts
├── actions/                     # Server Actions
│   ├── auth.ts
│   └── posts.ts
└── types/
    └── index.ts

Large App (30+ routes)

Use feature-based organization — group by domain, not by technical layer:

src/
├── app/
│   ├── layout.tsx
│   ├── page.tsx
│   ├── (auth)/
│   │   ├── login/page.tsx
│   │   └── register/page.tsx
│   ├── (dashboard)/
│   │   ├── layout.tsx
│   │   └── [...slug]/page.tsx
│   └── api/
│       └── webhooks/stripe/route.ts
├── features/
│   ├── auth/
│   │   ├── components/
│   │   │   ├── login-form.tsx
│   │   │   └── register-form.tsx
│   │   ├── actions/
│   │   │   └── auth-actions.ts
│   │   ├── lib/
│   │   │   └── session.ts
│   │   └── types.ts
│   ├── posts/
│   │   ├── components/
│   │   │   ├── post-card.tsx
│   │   │   └── post-list.tsx
│   │   ├── actions/
│   │   │   └── post-actions.ts
│   │   ├── queries/
│   │   │   └── get-posts.ts
│   │   └── types.ts
│   └── billing/
│       ├── components/
│       ├── actions/
│       ├── lib/
│       └── types.ts
├── components/                  # Truly shared UI only
│   └── ui/
├── lib/                         # Truly shared utilities only
│   ├── db.ts
│   └── utils.ts
└── types/
    └── globals.d.ts

Key Organization Patterns

Route Groups (name)

Wrap folders in parentheses to organize without affecting URLs:

app/
├── (marketing)/        # URL: /about, /blog — NOT /marketing/about
│   ├── layout.tsx      # Marketing-specific layout
│   ├── about/page.tsx
│   └── blog/page.tsx
├── (shop)/             # URL: /cart, /products
│   ├── layout.tsx      # Shop-specific layout (with cart sidebar)
│   ├── cart/page.tsx
│   └── products/page.tsx

Each route group can have its own layout.tsx, loading.tsx, and error.tsx.

Private Folders _name

Prefix with underscore to exclude from routing. Safe for colocated utilities:

app/dashboard/
├── page.tsx
├── _components/        # NOT a route — colocated UI
│   ├── stats-card.tsx
│   └── recent-activity.tsx
├── _lib/               # NOT a route — colocated helpers
│   └── format-data.ts
└── _hooks/
    └── use-dashboard-data.ts

Data Layer Organization

Separate data access from UI:

// src/features/posts/queries/get-posts.ts — Data fetching
import { db } from '@/lib/db'

export async function getPosts(limit = 10) {
  return db.post.findMany({ take: limit, orderBy: { createdAt: 'desc' } })
}

// src/features/posts/actions/post-actions.ts — Mutations
'use server'
import { revalidatePath } from 'next/cache'
import { db } from '@/lib/db'

export async function createPost(formData: FormData) {
  await db.post.create({ data: { title: formData.get('title') as string } })
  revalidatePath('/posts')
}

// src/app/posts/page.tsx — Route (thin, delegates to feature)
import { getPosts } from '@/features/posts/queries/get-posts'
import { PostList } from '@/features/posts/components/post-list'

export default async function PostsPage() {
  const posts = await getPosts()
  return <PostList posts={posts} />
}

Naming Conventions

Path Aliases

Configure in tsconfig.json for clean imports:

{
  "compilerOptions": {
    "paths": {
      "@/*": ["./src/*"],
      "@/components/*": ["./src/components/*"],
      "@/features/*": ["./src/features/*"],
      "@/lib/*": ["./src/lib/*"]
    }
  }
}

Anti-patterns

• "Utils" dumping ground — Don't create a catch-all utils/ with 50+ files. Split by domain or move into features.
• Deep barrel exports — Avoid index.ts re-exporting from deeply nested files. Causes circular imports and bundle bloat.
• Mixing concerns in app/ — Don't put business logic, database queries, or utility functions directly in route files. Route files should be thin orchestrators.
• Unnecessary abstraction — Don't create features/ for a 5-page app. Start simple, extract when it hurts.
• Importing server code in client components — Use server-only package to prevent accidental leaks. See security-patterns skill.

What This Skill Does NOT Cover

• Monorepo setup with Turborepo (tool-specific)
• CI/CD and deployment configuration (see cli-recipes)
• Routing patterns like parallel/intercepting routes (see app-router-patterns)
• Component architecture decisions (see server-client-components)