❤ Like

🔖 Save

🔗 Share

Eric Hu

Next.js File Conventions

File	Description
`page.tsx`	The UI for a route segment. Makes a path public.
`layout.tsx`	Shared UI that wraps child segments and persists.
`loading.tsx`	Instant loading UI shown while the segment loads.
`error.tsx`	Error boundary UI for a segment.
`not-found.tsx`	UI shown when `notFound()` is called.
`template.tsx`	Like layout, but remounts on navigation.
`default.tsx`	Fallback for parallel routes when no match.
`route.tsx`	API endpoint for a route segment.
`middleware.ts`	Run code before a request completes.
`icon.png`	Favicon and app icons.
`opengraph-image.png`	Open Graph image for social sharing.
`sitemap.ts`	Generate a sitemap for search engines.
`robots.ts`	Generate a robots.txt file.
`manifest.ts`	Generate a web app manifest.

`page.tsx`

Define the UI for a route. A route is only public when it has a page.

text

app
├── page.tsx              → /
└── blog
    ├── page.tsx          → /blog
    └── [slug]
        └── page.tsx      → /blog/hello

tsx

// app/blog/page.tsx → /blog
export default function BlogPage() {
  return <h1>Blog</h1>;
}

Pages receive params and searchParams as props.

params are the dynamic segments of the URL.

text

app
├── page.tsx              → /
└── blog
    ├── page.tsx          → /blog
    └── [slug]
        └── page.tsx      → /blog/hello

tsx

export default async function Page({ params, searchParams }) {
  const { id } = await params;
  const { q } = await searchParams;
}

searchParams are the query parameters.

url

https://example.com/blog/hello?q=search

tsx

export default async function Page({ params, searchParams }) {
  const { id } = await params;
  const { q } = await searchParams;
}

`layout.tsx`

Shared UI that wraps a segment and its children. Layouts preserve state and do not re-render on navigation.

text

app
├── layout.tsx            # root layout (required)
└── dashboard
    ├── layout.tsx        # wraps /dashboard/*
    └── page.tsx

tsx

// app/dashboard/layout.tsx
export default function DashboardLayout({ children }) {
  return (
    <section>
      <Sidebar />
      {children}
    </section>
  );
}

The root layout.tsx is required and must include html and body.

tsx

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

`loading.tsx`

Wraps the page in a React Suspense boundary. Shown instantly while the segment loads.

text

app
└── dashboard
    ├── loading.tsx       # shown while dashboard/page.tsx loads
    └── page.tsx

tsx

// app/dashboard/loading.tsx
export default function Loading() {
  return <Spinner />;
}

`error.tsx`

Catches errors in the segment and its children. Must be a client component.

text

app
├── global-error.tsx      # catches errors in the root layout
└── dashboard
    ├── error.tsx         # catches errors in /dashboard/*
    └── page.tsx

tsx

"use client";
 
export default function Error({ error, reset }) {
  return (
    <div>
      <p>{error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

Use global-error.tsx to catch errors in the root layout.

`not-found.tsx`

Rendered when notFound() is called or a URL matches nothing.

text

app
├── not-found.tsx         # root 404 page
└── blog
    ├── not-found.tsx     # 404 for /blog/*
    └── [slug]
        └── page.tsx

tsx

import { notFound } from "next/navigation";
 
export default async function Post({ params }) {
  const post = await getPost((await params).id);
  if (!post) notFound(); // renders not-found.tsx
}

tsx

// app/not-found.tsx
export default function NotFound() {
  return <h1>404 - Page not found</h1>;
}

`template.tsx`

Like a layout, but creates a new instance on navigation. State is not preserved.

text

app
├── template.tsx          # remounts on every navigation
└── page.tsx

tsx

// app/template.tsx
export default function Template({ children }) {
  return <div>{children}</div>;
}

Use it for enter/exit animations or per-page effects.

`default.tsx`

Fallback UI for parallel routes when the current URL doesn't match a slot.

text

app
├── @modal
│   ├── default.tsx       # fallback when no modal is active
│   └── login
│       └── page.tsx
└── layout.tsx            # receives { modal } as a prop

tsx

// app/@modal/default.tsx
export default function Default() {
  return null;
}

`route.tsx`

Create an API endpoint. Cannot coexist with page.tsx at the same segment.

text

app
└── api
    └── users
        └── route.ts      → /api/users

tsx

// app/api/users/route.ts → /api/users
import { NextResponse } from "next/server";
 
export async function GET() {
  const users = await getUsers();
  return NextResponse.json(users);
}
 
export async function POST(request) {
  const body = await request.json();
  return NextResponse.json(body, { status: 201 });
}

`middleware.ts`

Run code before a request completes: redirects, rewrites, auth checks.

text

project-root
├── middleware.ts         # root of the project, next to app/
└── app
    └── page.tsx

// middleware.ts (project root)
import { NextResponse } from "next/server";
 
export function middleware(request) {
  if (!request.cookies.has("session")) {
    return NextResponse.redirect(new URL("/login", request.url));
  }
}
 
export const config = {
  matcher: ["/dashboard/:path*"],
};

Metadata files

Special files that map to SEO and browser features.

text

app
├── icon.png              # favicon
├── apple-icon.png        # Apple touch icon
├── opengraph-image.png   # social sharing image
├── sitemap.ts            # generated sitemap
├── robots.ts             # generated robots.txt
└── manifest.ts           # web app manifest

// app/sitemap.ts
export default function sitemap() {
  return [{ url: "https://example.com", lastModified: new Date() }];
}

// app/robots.ts
export default function robots() {
  return { rules: { userAgent: "*", allow: "/" } };
}

Image files like icon.png, apple-icon.png, and opengraph-image.png are picked up automatically.

❤ Like

🔖 Save

🔗 Share

Eric Hu

Next.js File Conventions

File	Description
`page.tsx`	The UI for a route segment. Makes a path public.
`layout.tsx`	Shared UI that wraps child segments and persists.
`loading.tsx`	Instant loading UI shown while the segment loads.
`error.tsx`	Error boundary UI for a segment.
`not-found.tsx`	UI shown when `notFound()` is called.
`template.tsx`	Like layout, but remounts on navigation.
`default.tsx`	Fallback for parallel routes when no match.
`route.tsx`	API endpoint for a route segment.
`middleware.ts`	Run code before a request completes.
`icon.png`	Favicon and app icons.
`opengraph-image.png`	Open Graph image for social sharing.
`sitemap.ts`	Generate a sitemap for search engines.
`robots.ts`	Generate a robots.txt file.
`manifest.ts`	Generate a web app manifest.

`page.tsx`

Define the UI for a route. A route is only public when it has a page.

text

app
├── page.tsx              → /
└── blog
    ├── page.tsx          → /blog
    └── [slug]
        └── page.tsx      → /blog/hello

tsx

// app/blog/page.tsx → /blog
export default function BlogPage() {
  return <h1>Blog</h1>;
}

Pages receive params and searchParams as props.

params are the dynamic segments of the URL.

text

app
├── page.tsx              → /
└── blog
    ├── page.tsx          → /blog
    └── [slug]
        └── page.tsx      → /blog/hello

tsx

export default async function Page({ params, searchParams }) {
  const { id } = await params;
  const { q } = await searchParams;
}

searchParams are the query parameters.

url

https://example.com/blog/hello?q=search

tsx

export default async function Page({ params, searchParams }) {
  const { id } = await params;
  const { q } = await searchParams;
}

`layout.tsx`

Shared UI that wraps a segment and its children. Layouts preserve state and do not re-render on navigation.

text

app
├── layout.tsx            # root layout (required)
└── dashboard
    ├── layout.tsx        # wraps /dashboard/*
    └── page.tsx

tsx

// app/dashboard/layout.tsx
export default function DashboardLayout({ children }) {
  return (
    <section>
      <Sidebar />
      {children}
    </section>
  );
}

The root layout.tsx is required and must include html and body.

tsx

// app/layout.tsx
export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>{children}</body>
    </html>
  );
}

`loading.tsx`

Wraps the page in a React Suspense boundary. Shown instantly while the segment loads.

text

app
└── dashboard
    ├── loading.tsx       # shown while dashboard/page.tsx loads
    └── page.tsx

tsx

// app/dashboard/loading.tsx
export default function Loading() {
  return <Spinner />;
}

`error.tsx`

Catches errors in the segment and its children. Must be a client component.

text

app
├── global-error.tsx      # catches errors in the root layout
└── dashboard
    ├── error.tsx         # catches errors in /dashboard/*
    └── page.tsx

tsx

"use client";
 
export default function Error({ error, reset }) {
  return (
    <div>
      <p>{error.message}</p>
      <button onClick={reset}>Try again</button>
    </div>
  );
}

Use global-error.tsx to catch errors in the root layout.

`not-found.tsx`

Rendered when notFound() is called or a URL matches nothing.

text

app
├── not-found.tsx         # root 404 page
└── blog
    ├── not-found.tsx     # 404 for /blog/*
    └── [slug]
        └── page.tsx

tsx

import { notFound } from "next/navigation";
 
export default async function Post({ params }) {
  const post = await getPost((await params).id);
  if (!post) notFound(); // renders not-found.tsx
}

tsx

// app/not-found.tsx
export default function NotFound() {
  return <h1>404 - Page not found</h1>;
}

`template.tsx`

Like a layout, but creates a new instance on navigation. State is not preserved.

text

app
├── template.tsx          # remounts on every navigation
└── page.tsx

tsx

// app/template.tsx
export default function Template({ children }) {
  return <div>{children}</div>;
}

Use it for enter/exit animations or per-page effects.

`default.tsx`

Fallback UI for parallel routes when the current URL doesn't match a slot.

text

app
├── @modal
│   ├── default.tsx       # fallback when no modal is active
│   └── login
│       └── page.tsx
└── layout.tsx            # receives { modal } as a prop

tsx

// app/@modal/default.tsx
export default function Default() {
  return null;
}

`route.tsx`

Create an API endpoint. Cannot coexist with page.tsx at the same segment.

text

app
└── api
    └── users
        └── route.ts      → /api/users

tsx

// app/api/users/route.ts → /api/users
import { NextResponse } from "next/server";
 
export async function GET() {
  const users = await getUsers();
  return NextResponse.json(users);
}
 
export async function POST(request) {
  const body = await request.json();
  return NextResponse.json(body, { status: 201 });
}

`middleware.ts`

Run code before a request completes: redirects, rewrites, auth checks.

text

project-root
├── middleware.ts         # root of the project, next to app/
└── app
    └── page.tsx

// middleware.ts (project root)
import { NextResponse } from "next/server";
 
export function middleware(request) {
  if (!request.cookies.has("session")) {
    return NextResponse.redirect(new URL("/login", request.url));
  }
}
 
export const config = {
  matcher: ["/dashboard/:path*"],
};

Metadata files

Special files that map to SEO and browser features.

text

app
├── icon.png              # favicon
├── apple-icon.png        # Apple touch icon
├── opengraph-image.png   # social sharing image
├── sitemap.ts            # generated sitemap
├── robots.ts             # generated robots.txt
└── manifest.ts           # web app manifest

// app/sitemap.ts
export default function sitemap() {
  return [{ url: "https://example.com", lastModified: new Date() }];
}

// app/robots.ts
export default function robots() {
  return { rules: { userAgent: "*", allow: "/" } };
}

Image files like icon.png, apple-icon.png, and opengraph-image.png are picked up automatically.

Next.js File Conventions

`page.tsx`

`layout.tsx`

`loading.tsx`

`error.tsx`

`not-found.tsx`

`template.tsx`

`default.tsx`

`route.tsx`

`middleware.ts`

Metadata files

Full-Stack AI Developer Roadmap

Next.js File Conventions

`page.tsx`

`layout.tsx`

`loading.tsx`

`error.tsx`

`not-found.tsx`

`template.tsx`

`default.tsx`

`route.tsx`

`middleware.ts`

Metadata files

Full-Stack AI Developer Roadmap