Skip to main content

Web frameworks · Beginner · 22 min

How to Build Your First Next.js 16 App with the App Router

By Padding · Updated 15 Nov 2026
Next.js 16 · React 19.3 · Node.js 26

You will create a Next.js 16 app, add pages, a shared layout, a dynamic route that is built ahead of time, one interactive component and a JSON route, then run a production build and read what Next.js decided to prerender.

On this page

Next.js is a framework built on React. You put files in folders, and Next.js turns them into pages, handles routing, renders on the server, splits your JavaScript and produces a production build. The App Router, the app/ folder, is the modern way to use it. In it, every component is a Server Component unless you mark it otherwise, which means it runs on the server and ships no JavaScript of its own to the browser.

You will build a small notes site: a home page, a list of notes, a page for each note, a like button and a JSON endpoint. The aim is to see each building block once, and to see which parts Next.js builds ahead of time and which it leaves for the request. A new Next.js 16 project has Cache Components switched on, and that setting decides much of this, so the tutorial explains it as you go. It assumes Node.js 26 from the Node.js install tutorial.

Step 1 · Create the app

create-next-app scaffolds a project. The options choose TypeScript, Tailwind CSS, ESLint, the App Router, a src/ folder, npm and the default import alias, and skip creating a Git repository so the command asks nothing:

Bash
cd ~
npx create-next-app@16 field-notes --ts --tailwind --eslint --app --src-dir --use-npm --import-alias "@/*" --disable-git --yes
cd field-notes

It installs the dependencies, which takes a minute or two. Look at what you got:

Bash
ls
ls src/app
cat next.config.ts

Check it worked

create-next-app ends with Success! Created field-notes. The project root holds package.json, next.config.ts, tsconfig.json, eslint.config.mjs and public/. The folder src/app holds layout.tsx, page.tsx, globals.css and an icon. next.config.ts turns on cacheComponents, which this tutorial returns to in the build step. The project also contains an AGENTS.md file with notes for AI coding tools, and the Next.js documentation for this exact version, in node_modules/next/dist/docs, which you can read offline.

Step 2 · Start the dev server

Run the development server. It stays in the foreground, and reloads the browser when you save, so use a second terminal for the commands below:

Bash
npm run dev

The first terminal prints the Next.js version, Local: http://localhost:3000 and Ready. Fetch the page:

Bash
curl -s http://localhost:3000/ | grep -o '<title>[^<]*</title>'

Check it worked

The output is <title>Create Next App</title>. Open http://localhost:3000 in a browser to see the starter page. Keep the server running while you edit the files that follow, and refresh to see each change.

Step 3 · Write a layout and a home page

src/app/layout.tsx is the root layout. It wraps every page, and must contain the html and body tags. Replace it with one that has a title and a navigation bar. Link navigates between pages without a full reload:

Bash
cat > src/app/layout.tsx <<'TSX'
import type { Metadata } from "next";
import Link from "next/link";
import "./globals.css";

export const metadata: Metadata = {
  title: { default: "Field Notes", template: "%s · Field Notes" },
  description: "A small site built with the Next.js App Router.",
};

export default function RootLayout({ children }: LayoutProps<"/">) {
  return (
    <html lang="en">
      <body className="mx-auto max-w-2xl p-6">
        <nav className="flex gap-4 pb-6">
          <Link href="/">Home</Link>
          <Link href="/notes">Notes</Link>
        </nav>
        {children}
      </body>
    </html>
  );
}
TSX
cat > src/app/page.tsx <<'TSX'
export default function HomePage() {
  return (
    <main>
      <h1 className="text-3xl font-semibold">Field Notes</h1>
      <p className="pt-2">Short notes, served by the Next.js App Router.</p>
    </main>
  );
}
TSX

LayoutProps<"/"> is a type that Next.js generates for you, so children is typed correctly without you writing it. The metadata export sets the page title for every page. The template puts the site name after each page's own title.

Step 4 · Add a list of notes and a page for each

A folder under app/ is a route, and its page.tsx is the page. Put the data in one small module first. A real app would read a database or a CMS here, and the pages would not change:

Bash
mkdir -p src/lib
cat > src/lib/notes.ts <<'TS'
export type Note = { slug: string; title: string; body: string };

const notes: Note[] = [
  { slug: "first-note", title: "First note", body: "Routes are folders." },
  { slug: "second-note", title: "Second note", body: "Pages are Server Components." },
];

export function getNotes(): Note[] {
  return notes;
}

export function getNote(slug: string): Note | undefined {
  return notes.find((note) => note.slug === slug);
}
TS

The list page lives at /notes:

Bash
mkdir -p src/app/notes
cat > src/app/notes/page.tsx <<'TSX'
import type { Metadata } from "next";
import Link from "next/link";
import { getNotes } from "@/lib/notes";

export const metadata: Metadata = { title: "Notes" };

export default function NotesPage() {
  return (
    <main>
      <h1 className="text-2xl font-semibold">Notes</h1>
      <ul className="list-disc pl-6 pt-2">
        {getNotes().map((note) => (
          <li key={note.slug}>
            <Link href={`/notes/${note.slug}`}>{note.title}</Link>
          </li>
        ))}
      </ul>
    </main>
  );
}
TSX

A folder name in square brackets is a dynamic segment. notes/[slug]/page.tsx handles /notes/first-note, /notes/second-note and any other value, and receives it in params. In this version params is a promise, so you await it:

Bash
mkdir -p "src/app/notes/[slug]"
cat > "src/app/notes/[slug]/page.tsx" <<'TSX'
import { notFound } from "next/navigation";
import { getNote, getNotes } from "@/lib/notes";

export function generateStaticParams() {
  return getNotes().map((note) => ({ slug: note.slug }));
}

export default async function NotePage({ params }: PageProps<"/notes/[slug]">) {
  const { slug } = await params;
  const note = getNote(slug);
  if (!note) notFound();

  return (
    <main>
      <h1 className="text-2xl font-semibold">{note.title}</h1>
      <p className="pt-2">{note.body}</p>
    </main>
  );
}
TSX

generateStaticParams lists the slugs that exist, so Next.js can build those pages ahead of time instead of waiting for a visitor. With Cache Components on, a dynamic segment without this function makes the value unknown until the request, which Next.js then asks you to wrap in a Suspense boundary. notFound() shows the not-found page for a slug that has no note.

Check it worked

With the dev server still running, check the three pages and their titles:

Bash
curl -s http://localhost:3000/notes | grep -o '<title>[^<]*</title>\|<h1[^>]*>[^<]*</h1>'
curl -s http://localhost:3000/notes/second-note | grep -o '<h1[^>]*>[^<]*</h1>\|<p class="pt-2">[^<]*</p>'

The first prints <title>Notes · Field Notes</title> and the heading Notes. The second prints the heading Second note and the paragraph Pages are Server Components.

Troubleshooting

An error overlay in the browser names the file and line, and the terminal repeats it. A type error about PageProps or LayoutProps usually clears when the dev server regenerates its route types, so save the file again or restart the server. If a page shows the old content, check you saved the file in src/app and not an app folder in the project root.

Step 5 · Add one interactive component

Server Components cannot hold state or respond to clicks. Anything that does needs a Client Component, marked by the 'use client' line at the top of its file. Keep those components small, so the rest of the page stays on the server:

Bash
mkdir -p src/components
cat > src/components/like-button.tsx <<'TSX'
"use client";

import { useState } from "react";

export default function LikeButton() {
  const [likes, setLikes] = useState(0);
  return (
    <button
      type="button"
      className="mt-4 rounded border px-3 py-1"
      onClick={() => setLikes(likes + 1)}
    >
      Likes: {likes}
    </button>
  );
}
TSX

Use it from the note page. Replace the page with a version that imports the button:

Bash
cat > "src/app/notes/[slug]/page.tsx" <<'TSX'
import { notFound } from "next/navigation";
import LikeButton from "@/components/like-button";
import { getNote, getNotes } from "@/lib/notes";

export function generateStaticParams() {
  return getNotes().map((note) => ({ slug: note.slug }));
}

export default async function NotePage({ params }: PageProps<"/notes/[slug]">) {
  const { slug } = await params;
  const note = getNote(slug);
  if (!note) notFound();

  return (
    <main>
      <h1 className="text-2xl font-semibold">{note.title}</h1>
      <p className="pt-2">{note.body}</p>
      <LikeButton />
    </main>
  );
}
TSX
curl -s http://localhost:3000/notes/first-note | grep -o 'Likes: <!-- -->[0-9]*'

The page is still a Server Component. Only LikeButton and what it imports go to the browser as JavaScript. Click the button in the browser, and the count goes up without a page load. The curl command prints Likes: <!-- -->0: the comment marker is React's separator between the text and the number, and the server sends the first version with the count at 0.

Step 6 · Add a JSON route

A route handler answers a request with data and not a page. Create route.ts in a folder, and export a function named after the HTTP method:

Bash
mkdir -p src/app/api/notes
cat > src/app/api/notes/route.ts <<'TS'
import { getNotes } from "@/lib/notes";

export function GET() {
  return Response.json(getNotes());
}
TS
Bash
curl -s http://localhost:3000/api/notes

If the first request after saving the file answers with a 404 page, wait a few seconds and run the curl command again, because the dev server may need a moment to pick up a new route file.

Check it worked

The output is a JSON array of the two notes, each with slug, title and body.

Now stop the dev server by pressing Ctrl+C in its terminal.

Step 7 · Build for production

The dev server compiles on demand and is not what you deploy. A production build compiles everything, type checks and decides, route by route, what can be prerendered. It does not run the linter, so run npm run lint yourself or in CI:

Bash
npm run build

Check it worked

The build ends with a route table like this one. The symbols are Next.js's own, and the legend printed below the table explains them:

Text
Route (app)
┌ ○ /
├ ○ /_not-found
├ ○ /api/notes
├ ○ /notes
└   /notes/[slug]
  ├ ◐ /notes/[slug]
  ├ ○ /notes/first-note
  └ ○ /notes/second-note

○ means the route was prerendered as static content at build time. /notes/first-note and /notes/second-note are there because of generateStaticParams. The ◐ line is a partial prerender: Next.js builds the fixed shell of the page ahead of time and streams what depends on the request. You did not write a single cache setting, because with Cache Components, what can be known at build time is prerendered by default, and what depends on the request, such as cookies, headers or live data, is not. The Next.js documentation in node_modules/next/dist/docs/01-app/01-getting-started/08-caching.md explains the model in full.

Run the production server and request the pages:

Bash
npm run start
Bash
curl -s http://localhost:3000/notes | grep -o '<title>[^<]*</title>'
curl -s http://localhost:3000/notes/first-note | grep -o '<h1[^>]*>[^<]*</h1>'
curl -s http://localhost:3000/api/notes | head -c 80

npm run start serves the build on port 3000. Stop it with Ctrl+C when you have seen enough.

Step 8 · Where to go from here

Remove the demo project when you finish:

Bash
cd ~
rm -rf ~/field-notes

To put a site like this online, the quickest route is Vercel, the company that makes Next.js. You can also run npm run start behind Nginx on your own server. Check the Next.js version's own deployment guide before you choose.

Next steps

Need this done for you?

Padding does this work for growing companies, from the first diagnosis to a system that keeps working.

Platform Engineering

Get new tutorials

New tutorials, about twice a month.