1# File Conventions
2 
3Next.js App Router uses file-based routing with special file conventions.
4 
5## Project Structure
6 
7Reference: https://nextjs.org/docs/app/getting-started/project-structure
8 
9```
10app/
11├── layout.tsx          # Root layout (required)
12├── page.tsx            # Home page (/)
13├── loading.tsx         # Loading UI
14├── error.tsx           # Error UI
15├── not-found.tsx       # 404 UI
16├── global-error.tsx    # Global error UI
17├── route.ts            # API endpoint
18├── template.tsx        # Re-rendered layout
19├── default.tsx         # Parallel route fallback
20├── blog/
21│   ├── page.tsx        # /blog
22│   └── [slug]/
23│       └── page.tsx    # /blog/:slug
24└── (group)/            # Route group (no URL impact)
25    └── page.tsx
26```
27 
28## Special Files
29 
30| File | Purpose |
31|------|---------|
32| `page.tsx` | UI for a route segment |
33| `layout.tsx` | Shared UI for segment and children |
34| `loading.tsx` | Loading UI (Suspense boundary) |
35| `error.tsx` | Error UI (Error boundary) |
36| `not-found.tsx` | 404 UI |
37| `route.ts` | API endpoint |
38| `template.tsx` | Like layout but re-renders on navigation |
39| `default.tsx` | Fallback for parallel routes |
40 
41## Route Segments
42 
43```
44app/
45├── blog/               # Static segment: /blog
46├── [slug]/             # Dynamic segment: /:slug
47├── [...slug]/          # Catch-all: /a/b/c
48├── [[...slug]]/        # Optional catch-all: / or /a/b/c
49└── (marketing)/        # Route group (ignored in URL)
50```
51 
52## Parallel Routes
53 
54```
55app/
56├── @analytics/
57│   └── page.tsx
58├── @sidebar/
59│   └── page.tsx
60└── layout.tsx          # Receives { analytics, sidebar } as props
61```
62 
63## Intercepting Routes
64 
65```
66app/
67├── feed/
68│   └── page.tsx
69├── @modal/
70│   └── (.)photo/[id]/  # Intercepts /photo/[id] from /feed
71│       └── page.tsx
72└── photo/[id]/
73    └── page.tsx
74```
75 
76Conventions:
77- `(.)` - same level
78- `(..)` - one level up
79- `(..)(..)` - two levels up
80- `(...)` - from root
81 
82## Private Folders
83 
84```
85app/
86├── _components/        # Private folder (not a route)
87│   └── Button.tsx
88└── page.tsx
89```
90 
91Prefix with `_` to exclude from routing.
92 
93## Middleware / Proxy
94 
95### Next.js 14-15: `middleware.ts`
96 
97```ts
98// middleware.ts (root of project)
99import { NextResponse } from 'next/server';
100import type { NextRequest } from 'next/server';
101 
102export function middleware(request: NextRequest) {
103  // Auth, redirects, rewrites, etc.
104  return NextResponse.next();
105}
106 
107export const config = {
108  matcher: ['/dashboard/:path*', '/api/:path*'],
109};
110```
111 
112### Next.js 16+: `proxy.ts`
113 
114Renamed for clarity - same capabilities, different names:
115 
116```ts
117// proxy.ts (root of project)
118import { NextResponse } from 'next/server';
119import type { NextRequest } from 'next/server';
120 
121export function proxy(request: NextRequest) {
122  // Same logic as middleware
123  return NextResponse.next();
124}
125 
126export const config = {
127  matcher: ['/dashboard/:path*', '/api/:path*'],
128};
129```
130 
131| Version | File | Export | Config |
132|---------|------|--------|--------|
133| v14-15 | `middleware.ts` | `middleware()` | `config` |
134| v16+ | `proxy.ts` | `proxy()` | `config` |
135 
136**Migration**: Run `npx @next/codemod@latest upgrade` to auto-rename.
137 
138## File Conventions Reference
139 
140Reference: https://nextjs.org/docs/app/api-reference/file-conventions