#Project Structure & Conventions Deep Dive¶

Next.js is convention over configuration. Knowing the conventions saves you from reading docs every time you add a feature.

Top-Level Folders¶

Special Files in app/¶

These file names have superpowers. Every other file is just a regular module.

Routing Conventions¶

Component Conventions¶

A page.tsx must default-export a React component:

1// app/about/page.tsx
2export default function AboutPage() {
3  return <h1>About</h1>;
4}

A layout.tsx must accept { children }:

1// app/blog/layout.tsx
2export default function BlogLayout({ children }: { children: React.ReactNode }) {
3  return (
4    <div className="grid grid-cols-[200px_1fr]">
5      <Sidebar />
6      <main>{children}</main>
7    </div>
8  );
9}

A route.ts exports HTTP verbs:

1// app/api/health/route.ts
2export async function GET() {
3  return Response.json({ status: "ok" });
4}

File Co-location¶

You can place any non-special file inside app/ — components, tests, hooks, CSS. Only files with reserved names participate in routing.

Metadata Files¶

Drop the file in the right place — Next does the wiring.

A Realistic Folder for a Mid-Size App¶

This structure scales from prototype to 200 KLOC apps without restructuring.