Project: a full-stack app

An invoices dashboard, built from parts you know

The tea company has two sellers, Asha and Ben. Each one bills cafés and shops for boxes of tea, and wants one place to see what they have billed and what is still unpaid. Here you build that place: a small invoices dashboard with a real database, sign-in, a form that saves invoices, a cached total, a page that streams, tests and a server you can deploy.

The app is built in this order: plan the routes and the tables, make the database, add sign-in and the data access layer, write the pages, save invoices with a Server Action, cache the one value everyone shares, stream the dashboard, handle failures, test, and deploy.

Here is the finished app. It's a real Next.js 16.4.3 project, built with next build and run with next start; then real Chrome signed in as Asha and used it. Click a file in the tree to read it. Open the Steps tab under the files and click through what Chrome did: Asha signs in and the dashboard fills in, she makes a mistake in the new-invoice form and sees what's wrong, she saves invoice 6, the dashboard shows it, and then she types the address of Ben's invoice 4 and gets Invoice not found.

1import { Suspense } from "react";2import type { Metadata } from "next";3import { Totals, TotalsSkeleton } from "./totals";4import { InvoiceTable, InvoiceTableSkeleton } from "./invoice-table";5 6export const metadata: Metadata = { title: "Dashboard" };7 8export default function DashboardPage() {9  return (10    <main>11      <h1>Dashboard</h1>12      <Suspense fallback={<TotalsSkeleton />}>13        <Totals />14      </Suspense>15      <Suspense fallback={<InvoiceTableSkeleton />}>16        <InvoiceTable />17      </Suspense>18    </main>19  );20}

The app has five pages. The picture shows each page file, the address it makes, and two facts the rest of the lesson builds on: the symbol next build printed for it, and who may open it. ○ means, in the build's own words, prerendered as static content. ◐ means prerendered as static HTML with dynamic server-streamed content: a static shell made during the build, with the parts for one visitor streamed in for each request.

Plan the routes and the data

Before any code, write down three things: the pages and who may open each one, the tables, and where each check happens. A plan this small fits in one table. Each row is one page:

Two pages need a word. /invoices/new is only for sellers, yet the build made it once for everyone. That's fine, because the form on it holds nothing private: the Server Action that saves the invoice checks who is asking. And the invoice page is one file for every invoice, a dynamic route, so the build can't know which invoices exist. Its layout is made during the build, and the invoice itself streams in.

The data is two tables:

• users: an id, a name, an email that must be unique, and a password hash. Never the password itself.
• invoices: an id, the user who wrote it, the customer, the amount in cents (whole numbers, so money never meets rounding errors), and a status, pending or paid.

And the checks have two places, as in Authorization and the data access layer:

• proxy.ts runs before the pages and sends anyone with no session cookie at all to /sign-in. It's quick, and only a first door.
• lib/dal.ts, the data access layer, is the only code that reads or writes invoices. Every function in it finds out who is asking first, and returns only that user's rows.

Then build it in this order, each part on top of the one before: the data, sign-in and the data access layer, the pages, the form, the cache, streaming, errors, tests and the deploy. Here is what next build printed for the finished app, the same build as the recording above:

Route (app)
┌ ○ /
├ ○ /_not-found
├ ◐ /dashboard
├   /invoices/[id]
│ └ ◐ /invoices/[id]
├ ○ /invoices/new
└ ○ /sign-in

ƒ Proxy (Middleware)

○  (Static)             prerendered as static content
◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

Every page matches the plan: ○ for the three pages that are the same for everyone, ◐ for the two that hold one user's data. /invoices/[id] is listed on its own line with no symbol, and its shell under it. ƒ Proxy (Middleware) is proxy.ts, which runs on the server for each request it matches. Nobody told Next.js which page is which: it worked it out from what each page reads, as Cache Components taught.

The database: two tables in PGlite

The database is Postgres, read and written with Drizzle ORM, as in Connecting a database. For this project it's PGlite: Postgres compiled to WebAssembly, running inside the app, in memory. It needs no database server, so the recordings run anywhere. Install the app's packages, the database, its ORM, jose for signed cookies and Zod for forms:

npm install @electric-sql/pglite drizzle-orm jose zod

next.config.ts is the one from Connecting a database: create-next-app's, with PGlite in serverExternalPackages, so Node.js loads it as it is instead of Next.js bundling it. The tables, described in TypeScript:

1import { index, integer, pgTable, serial, text } from "drizzle-orm/pg-core";2 3export const users = pgTable("users", {4  id: text().primaryKey(),5  name: text().notNull(),6  email: text().notNull().unique(),7  passwordHash: text("password_hash").notNull(),8});9 10export const invoices = pgTable(11  "invoices",12  {13    id: serial().primaryKey(),14    userId: text("user_id").notNull().references(() => users.id),15    customer: text().notNull(),16    amountCents: integer("amount_cents").notNull(),17    status: text({ enum: ["pending", "paid"] }).notNull(),18  },19  (table) => [index("invoices_user_id").on(table.userId)],20);21 

Lines 3 to 8 are the users table. Line 6 makes each email unique: the database itself refuses a second account with the same email, even if two sign-ups arrive at the same moment. Checking for the email first and then inserting can't promise that; the constraint can. Lines 10 to 20 are the invoices. Line 14 says each invoice belongs to one user, and references makes the database refuse an invoice for a user who doesn't exist. Line 16 keeps the amount in cents, and line 19 adds an index on the owner, so "this user's invoices", the question every page asks, stays fast as the table grows.

1import { PGlite } from "@electric-sql/pglite";2import { drizzle } from "drizzle-orm/pglite";3import { seed } from "./seed";4 5// Postgres inside the app, in memory: it starts empty each time the server starts.6// In production, connect to a Postgres server instead.7const client = new PGlite();8export const db = drizzle({ client });9 10await client.exec(`11  CREATE TABLE IF NOT EXISTS users (12    id text PRIMARY KEY,13    name text NOT NULL,14    email text NOT NULL UNIQUE,15    password_hash text NOT NULL16  );17  CREATE TABLE IF NOT EXISTS invoices (18    id serial PRIMARY KEY,19    user_id text NOT NULL REFERENCES users (id),20    customer text NOT NULL,21    amount_cents integer NOT NULL CHECK (amount_cents > 0),22    status text NOT NULL CHECK (status IN ('pending', 'paid'))23  );24  CREATE INDEX IF NOT EXISTS invoices_user_id ON invoices (user_id);25`);26await seed(db);27 

Line 7 starts PGlite in memory, and line 8 hands it to Drizzle. Lines 10 to 25 make the tables with the SQL that matches the schema; on a database server, drizzle-kit would run it once instead. Lines 21 and 22 add two more rules the database keeps: an amount above zero, and a status that is pending or paid. Line 26 adds the first rows from db/seed.ts: Asha and Ben with their password hashes, three invoices for Asha and two for Ben. In memory, the database starts empty every time a server starts, which is why each recording starts from the same five invoices.

Two more small files: lib/users.ts finds a user by email for the sign-in action, and lib/money.ts turns cents into dollars for the pages, so 4550 shows as $45.50.

Who is asking: sign-in and the data access layer

Sign-in is the Authentication lesson's, file for file. lib/password.ts hashes passwords with scrypt at OWASP's cost and compares them in constant time. lib/session.ts signs a session into an httpOnly, secure, sameSite cookie with jose, and reads it back. The sign-in form and its Server Action are the same too; only the action's redirect changed, to redirect("/dashboard").

The project keeps two of that lesson's recording-only fixtures. .env holds a fixed SESSION_SECRET; a real app generates random bytes and gives them to the server when it starts. And the recorded requests send copies of Asha's and Ben's session cookies made ahead of time with that secret, which expire in 2100; a real session cookie lasts the week lib/session.ts sets.

The first check is proxy.ts, as in proxy.ts:

1import { NextResponse, type NextRequest } from "next/server";2 3// Only looks for the cookie. The data access layer checks the session itself.4export function proxy(request: NextRequest) {5  if (!request.cookies.has("session")) {6    return NextResponse.redirect(new URL("/sign-in", request.url));7  }8}9 10export const config = { matcher: ["/dashboard", "/invoices/:path*"] };11 

Line 10 matches the dashboard and every invoice address. Line 5 asks only whether a cookie named session was sent, and line 6 sends anyone without one to /sign-in. In the finished app's recording, open the Network tab and pick /dashboard with no cookie: 307, with location: /sign-in, before any page code ran. A made-up cookie would pass this check. That's why it's only the first door.

The real checks are in the data access layer. Every read and write of invoices goes through this file:

1import "server-only";2import { cache } from "react";3import { redirect } from "next/navigation";4import { cacheLife, cacheTag } from "next/cache";5import { and, desc, eq, sum } from "drizzle-orm";6import { db } from "@/db";7import { invoices, users } from "@/db/schema";8import { readSession } from "./session";9 10// Who is asking. React's cache() runs it once per render pass, however many components ask.11export const getCurrentUser = cache(async () => {12  const session = await readSession();13  if (!session) return null;14  const [user] = await db.select({ id: users.id, name: users.name }).from(users).where(eq(users.id, session.userId));15  return user ?? null;16});17 18// For pages: anyone without a valid session goes to the sign-in page.19export async function verifySession() {20  const user = await getCurrentUser();21  if (!user) redirect("/sign-in");22  return user;23}24 25// Only the fields pages show.26const shown = { id: invoices.id, customer: invoices.customer, amountCents: invoices.amountCents, status: invoices.status };27 28// The signed-in user's invoices, newest first.29export const getMyInvoices = cache(async () => {30  const user = await verifySession();31  return db.select(shown).from(invoices).where(eq(invoices.userId, user.id)).orderBy(desc(invoices.id));32});33 34// One invoice, for its owner only. Anyone else gets null, as if it didn't exist.35export async function getInvoice(id: string) {36  if (!/^\d{1,9}$/.test(id)) return null;37  const user = await verifySession();38  const [invoice] = await db39    .select(shown)40    .from(invoices)41    .where(and(eq(invoices.id, Number(id)), eq(invoices.userId, user.id)));42  return invoice ?? null;43}44 45// The whole team's total, for anyone signed in.46export async function getTeamTotal() {47  await verifySession();48  return teamTotal();49}50 51// Not exported, so nothing skips the check above. It takes no user and returns52// nobody's own data, so one cached entry can serve everyone.53async function teamTotal() {54  "use cache";55  cacheLife("hours");56  cacheTag("team-total");57  console.log("team total: read from the database");58  const [row] = await db.select({ cents: sum(invoices.amountCents) }).from(invoices);59  return Number(row.cents ?? 0);60}61 62export type NewInvoice = { customer: string; amountCents: number; status: "pending" | "paid" };63 64// The owner comes from the session, never from the form.65export async function createInvoice(invoice: NewInvoice) {66  const user = await getCurrentUser();67  if (!user) return null;68  const [row] = await db.insert(invoices).values({ ...invoice, userId: user.id }).returning({ id: invoices.id });69  return row.id;70}71 

1. Lines 11 to 16, getCurrentUser, read the session (line 12 checks the cookie's signature and expiry) and find the user. Line 14 asks only for the id and the name. React's cache() runs it once per render pass, however many components on the page ask.
2. Lines 19 to 23, verifySession, are for pages: without a valid session, line 21 redirects to /sign-in.
3. Line 26 lists the only fields pages get: the id, the customer, the amount and the status. That's the DTO, the data transfer object, from the Authorization lesson. Nothing else from a row can reach a page, or the payload sent to the browser.
4. Lines 29 to 32, getMyInvoices, read the signed-in user's invoices. Line 31 filters by user.id, which comes from the session, never from the page.
5. Lines 35 to 43, getInvoice, find one invoice. Line 36 refuses an id that isn't a number. Line 41 asks for the invoice with this id and this owner, so Ben's invoice never comes back for Asha: she gets null, the same answer as for an invoice that doesn't exist.
6. Lines 65 to 70, createInvoice, save an invoice. Line 68 sets the owner from the session too.

Lines 45 to 60 hold the team's total, the one cached value in the app. Every query here runs after the session is read, which only exists when a request comes in, so none of them runs during the build.

In the recording's Steps, the step Click Sign in starts with POST /sign-in, answered 200 with text/x-component. That's the Server Action, called by the form with JavaScript running: one request that returns the redirect and the next page's RSC payload together, and the router moves to /dashboard. The requests after it are the router prefetching the dashboard's links.

The pages and their titles

The root layout gives every page its navigation, and every title its ending, with the Metadata API:

1import Link from "next/link";2import type { Metadata } from "next";3import HydrationMarker from "./hydration-marker";4 5export const metadata: Metadata = {6  title: { template: "%s | Tea invoices", default: "Tea invoices" },7};8 9export default function RootLayout({ children }: LayoutProps<"/">) {10  return (11    <html lang="en">12      <body>13        <nav>14          <Link href="/dashboard">Dashboard</Link> <Link href="/invoices/new">New invoice</Link>15        </nav>16        {children}17        <HydrationMarker />18      </body>19    </html>20  );21}22 

Line 6 is a title template, from The Metadata API: a page whose title is Dashboard gets Dashboard | Tea invoices, and a page with no title of its own gets the default. Line 14 links the two pages a seller uses. Line 17 is HydrationMarker, from End-to-end testing: an Effect that marks the page once React has hydrated it, which the browser tests below wait for.

The invoice page is the dynamic route:

1import { Suspense } from "react";2import type { Metadata } from "next";3import { notFound } from "next/navigation";4import { getInvoice } from "@/lib/dal";5import { dollars } from "@/lib/money";6 7export async function generateMetadata({ params }: PageProps<"/invoices/[id]">): Promise<Metadata> {8  const { id } = await params;9  return { title: `Invoice ${id}` };10}11 12async function Invoice({ params }: Pick<PageProps<"/invoices/[id]">, "params">) {13  const { id } = await params;14  const invoice = await getInvoice(id);15  if (!invoice) notFound();16  return (17    <>18      <h1>Invoice {invoice.id}</h1>19      <p>20        {invoice.customer}: {dollars(invoice.amountCents)}, {invoice.status}21      </p>22    </>23  );24}25 26export default function InvoicePage({ params }: PageProps<"/invoices/[id]">) {27  return (28    <main>29      <Suspense fallback={<p>Loading the invoice…</p>}>30        <Invoice params={params} />31      </Suspense>32    </main>33  );34}35 

Lines 7 to 10 give each invoice its own title from the address alone, without reading the database: Invoice 4 | Tea invoices in the recording. Invoice, on lines 12 to 24, waits for params and asks getInvoice on line 14. When that returns null, line 15 calls notFound(), and Next.js shows app/invoices/[id]/not-found.tsx: Invoice not found, with It doesn't exist, or it isn't yours. One answer for both cases means the page never tells Asha whether invoice 4 exists. Line 29 is the Suspense boundary that lets the layout go out first.

The new-invoice page is the plainest: a heading, a metadata title, and the form.

Creating an invoice with a Server Action

Saving an invoice is a Server Action, checked with Zod as in Forms:

1"use server";2 3import { updateTag } from "next/cache";4import { redirect } from "next/navigation";5import { z } from "zod";6import { createInvoice } from "@/lib/dal";7 8const newInvoice = z.object({9  customer: z.string().trim().min(2, "Write the customer's name."),10  amount: z11    .string()12    .trim()13    .regex(/^\d{1,5}(\.\d{2})?$/, "Write an amount like 45 or 45.50.")14    .transform((text) => {15      const [dollars, cents = "00"] = text.split(".");16      return Number(dollars) * 100 + Number(cents);17    })18    .refine((cents) => cents > 0, "An invoice is for more than $0."),19  status: z.enum(["pending", "paid"], "Pick pending or paid."),20});21 22export type InvoiceState = {23  message: string;24  errors: { customer?: string[]; amount?: string[]; status?: string[] };25  values: { customer: string; amount: string; status: string };26};27 28export async function addInvoice(previous: InvoiceState, formData: FormData): Promise<InvoiceState> {29  const values = {30    customer: String(formData.get("customer") ?? ""),31    amount: String(formData.get("amount") ?? ""),32    status: String(formData.get("status") ?? ""),33  };34  const result = newInvoice.safeParse(values);35  if (!result.success) {36    return { message: "Check the fields above.", errors: z.flattenError(result.error).fieldErrors, values };37  }38  const { customer, amount, status } = result.data;39  const id = await createInvoice({ customer, amountCents: amount, status });40  if (id === null) return { message: "Sign in again to save this invoice.", errors: {}, values };41  updateTag("team-total");42  redirect(`/invoices/${id}`);43}44 

1. Lines 8 to 20 describe a good form. The customer needs two letters or more. The amount must look like 45 or 45.50 (line 13), and lines 14 to 17 turn it into cents: 12.50 becomes 1250. Line 18 refuses zero. The status must be one of the two the database allows.
2. Lines 29 to 33 read the three fields as text. Line 34 checks them, and on any mistake line 36 returns a message for each field and the values as they were typed.
3. Line 39 saves through createInvoice, which takes the owner from the session. If the session has ended, it returns null, and line 40 says so.
4. Line 41 expires the cached team total, and line 42 opens the new invoice. redirect throws to stop the action, so updateTag must come first.

Zod checks the shape of what arrives; the data access layer decides whose it is. An action is a public endpoint, as Securing Server Actions showed, so it needs both. Next.js adds an Origin check of its own: in 16.4.3, a request whose Origin doesn't match the host is refused, but one with no Origin only logs a warning and runs. It adds to the checks above; it never replaces them. The form is a Client Component, because it calls useActionState:

1"use client";2 3import { useActionState } from "react";4import { addInvoice, type InvoiceState } from "./actions";5 6const empty: InvoiceState = { message: "", errors: {}, values: { customer: "", amount: "", status: "pending" } };7 8export default function InvoiceForm() {9  const [state, formAction, isPending] = useActionState(addInvoice, empty);10  return (11    <form action={formAction}>12      <label htmlFor="customer">Customer</label>13      <input id="customer" name="customer" defaultValue={state.values.customer} aria-describedby="customer-error" />14      <p id="customer-error">{state.errors.customer?.[0]}</p>15 16      <label htmlFor="amount">Amount in dollars</label>17      <input id="amount" name="amount" inputMode="decimal" defaultValue={state.values.amount} aria-describedby="amount-error" />18      <p id="amount-error">{state.errors.amount?.[0]}</p>19 20      <label htmlFor="status">Status</label>21      <select id="status" name="status" defaultValue={state.values.status}>22        <option value="pending">Pending</option>23        <option value="paid">Paid</option>24      </select>25 26      <button disabled={isPending}>{isPending ? "Saving…" : "Save invoice"}</button>27      <p aria-live="polite">{state.message}</p>28    </form>29  );30}31 

Line 9 gets three values from useActionState: the state the action returned last, the formAction the form posts to, and isPending, true while the action runs. Line 13 fills the box with what was typed: React resets a form after its action finishes without throwing, and the reset puts each box back to its defaultValue, which is now the typed value. Line 14 shows the field's message, and line 26 disables the button while the action runs.

Both ways of sending the form are in the recording. Before the JavaScript loads, the browser posts the form itself: in the Network tab, pick /invoices/new Save invoice with two mistakes. The server answered with the whole page, 200, showing Write the customer's name. and Write an amount like 45 or 45.50., and the boxes still hold L and 12.5. With JavaScript, in the Steps tab, the step that clicks Save invoice after typing 12.5 made one request, POST /invoices/new, answered 200 with text/x-component, and only the amount's message showed. After 12.50, the next click sent the same kind of request, and the router opened /invoices/6. A save posted without JavaScript gets a 303 to the invoice instead.

One shared total, and nothing personal in a cache

A shared cache keeps one copy of a result for everyone who asks with the same key. This app sets itself a strict rule, a choice of its own and not something Next.js requires: only data that is the same for everyone who may see it goes into a shared cache. Each row is one piece of the app's data:

Only the team's total passes. It's one number for the whole team, with nobody's own rows in it, and this team wants it on every seller's dashboard. (This app is one company: a team total would need a team id in a multi-company app.) Lines 45 to 60 of lib/dal.ts handle it in two functions:

• getTeamTotal, on lines 46 to 49, is exported. It checks the session first, like every function in the file, then asks teamTotal.
• teamTotal, on lines 53 to 60, is the cached one. Line 54, "use cache", keeps its result (The 'use cache' directive). Line 55, cacheLife("hours"), lets the entry live for hours, and line 56 tags it team-total (Cache lifetimes and tags). It isn't exported, so no page can skip the check. It takes no arguments, so its key holds nothing about the visitor.

Line 57 prints a line each time the total is really read from the database. In the finished app's recording, open the Terminal tab: under $ next start, team total: read from the database appears twice. The first is Asha's first dashboard. Ben's dashboard came next and printed nothing: it got the same cached total, $339.50. The second line came after Asha saved invoice 6, because line 41 of the action had expired the entry.

By that rule, everything personal stays out of shared caches. getMyInvoices and getInvoice read the database for each request, inside Suspense. Other apps choose differently: the Authentication lesson caches each user's orders with plain "use cache", keyed by the verified user id. That's a valid pattern; it keeps per-user data in the server's shared cache, which is fine where that storage is allowed. Where a policy forbids it, use "use cache: private", which keeps a result for one visitor only (Private and remote caches), or don't cache. Next.js also stops the most direct mistake: with "use cache" on getMyInvoices, the build stops, because cookies() can't be read inside it.

Now the tag. Both versions below are the whole app; only the action changes. Chrome signed in as Asha, saved one invoice, and went back to the dashboard. Before you pick, guess: which cards change without updateTag?

1"use server";2 3import { updateTag } from "next/cache";4import { redirect } from "next/navigation";5import { z } from "zod";6import { createInvoice } from "@/lib/dal";7 8const newInvoice = z.object({9  customer: z.string().trim().min(2, "Write the customer's name."),10  amount: z11    .string()12    .trim()13    .regex(/^\d{1,5}(\.\d{2})?$/, "Write an amount like 45 or 45.50.")14    .transform((text) => {15      const [dollars, cents = "00"] = text.split(".");16      return Number(dollars) * 100 + Number(cents);17    })18    .refine((cents) => cents > 0, "An invoice is for more than $0."),19  status: z.enum(["pending", "paid"], "Pick pending or paid."),20});21 22export type InvoiceState = {23  message: string;24  errors: { customer?: string[]; amount?: string[]; status?: string[] };25  values: { customer: string; amount: string; status: string };26};27 28export async function addInvoice(previous: InvoiceState, formData: FormData): Promise<InvoiceState> {29  const values = {30    customer: String(formData.get("customer") ?? ""),31    amount: String(formData.get("amount") ?? ""),32    status: String(formData.get("status") ?? ""),33  };34  const result = newInvoice.safeParse(values);35  if (!result.success) {36    return { message: "Check the fields above.", errors: z.flattenError(result.error).fieldErrors, values };37  }38  const { customer, amount, status } = result.data;39  const id = await createInvoice({ customer, amountCents: amount, status });40  if (id === null) return { message: "Sign in again to save this invoice.", errors: {}, values };41  updateTag("team-total");42  redirect(`/invoices/${id}`);43}

Without updateTag, Asha's Pending card went from $125.50 to $138.00, because her invoices are read for each request, and the table lists Invoice 6. The Whole team card still said $339.50: the cached entry had hours to live, and nothing told Next.js it was out of date. With it, the action expired the tag before redirecting, the next render read the database again, and the card said $352.00. That's reading your own write, from Updating the UI after a mutation.

Streaming the dashboard without a jump

The dashboard has a heading that is the same for everyone, and two parts that belong to one seller. That's the shape Streaming with Suspense taught: a Suspense boundary around each part that waits.

1import { Suspense } from "react";2import type { Metadata } from "next";3import { Totals, TotalsSkeleton } from "./totals";4import { InvoiceTable, InvoiceTableSkeleton } from "./invoice-table";5 6export const metadata: Metadata = { title: "Dashboard" };7 8export default function DashboardPage() {9  return (10    <main>11      <h1>Dashboard</h1>12      <Suspense fallback={<TotalsSkeleton />}>13        <Totals />14      </Suspense>15      <Suspense fallback={<InvoiceTableSkeleton />}>16        <InvoiceTable />17      </Suspense>18    </main>19  );20}21 

Line 11, the heading, needs nothing, so next build puts it in the static shell, the part of a ◐ page made during the build (Partial Prerendering). Lines 12 and 15 are two boundaries, so the totals and the table stream in on their own, each when its data is ready. Their fallbacks are in the shell too. Both parts ask getMyInvoices, and React's cache() answers the second one from the first, within the render.

1import { getMyInvoices, getTeamTotal } from "@/lib/dal";2import { dollars } from "@/lib/money";3import styles from "./dashboard.module.css";4 5function Card({ title, value }: { title: string; value: string }) {6  return (7    <section className={styles.card}>8      <h2>{title}</h2>9      <p>{value}</p>10    </section>11  );12}13 14export async function Totals() {15  const [invoices, teamTotal] = await Promise.all([getMyInvoices(), getTeamTotal()]);16  const total = (status: string) =>17    invoices.filter((invoice) => invoice.status === status).reduce((sum, invoice) => sum + invoice.amountCents, 0);18  return (19    <div className={styles.cards}>20      <Card title="Paid" value={dollars(total("paid"))} />21      <Card title="Pending" value={dollars(total("pending"))} />22      <Card title="Whole team" value={dollars(teamTotal)} />23    </div>24  );25}26 27export function TotalsSkeleton() {28  return (29    <div className={styles.cards} aria-busy="true">30      <Card title="Paid" value="…" />31      <Card title="Pending" value="…" />32      <Card title="Whole team" value="…" />33    </div>34  );35}36 

Line 15 asks for Asha's invoices and the team's total at the same time, with Promise.all, from Parallel and sequential fetching. Lines 20 to 22 draw three cards. Lines 27 to 35 are the skeleton: the same three Cards, with … for each value. A skeleton is a fallback shaped like what replaces it.

1.cards {2  display: grid;3  grid-template-columns: repeat(3, 1fr);4  gap: 12px;5}6 7.card {8  height: 96px;9  padding: 12px;10  border: 1px solid #d9d4c7;11  border-radius: 8px;12}13 14.card h2 {15  margin: 0;16  font-size: 14px;17}18 19.card p {20  margin: 8px 0 0;21  font-size: 28px;22}23 24.tableBox {25  min-height: 240px;26  margin-top: 24px;27}28 

Line 8 makes every card 96 pixels tall, skeleton or not. Line 25 keeps 240 pixels for the table, so its skeleton, Loading your invoices…, takes the table's space. When the real parts arrive, nothing under them moves. Content that moves while you look at it is what CLS measures, from Core Web Vitals.

Here is the dashboard drawn by real Chrome, with its CSS. The first recorded response is the page as Asha sees it. The second was taken with JavaScript turned off, so the streamed parts never replaced the fallbacks: it shows the static shell as it first arrives. Switch between them in the Browser tab:

The dashboard, before and after its parts stream inNext.js

app/dashboard/dashboard.module.csserror.tsxinvoice-table.tsxpage.tsxtotals.tsxinvoices/[id]/not-found.tsxpage.tsxnew/actions.tsinvoice-form.tsxpage.tsxsign-in/actions.tspage.tsxsign-in-form.tsxhydration-marker.tsxlayout.tsxpage.tsxdb/index.tsschema.tsseed.tslib/dal.tsmoney.tspassword.tssession.tsusers.tspublic/robots.txt.env.gitignorenext.config.tspackage.jsonproxy.tstsconfig.jsoncreate-next-app

app/dashboard/dashboard.module.css

1.cards {2  display: grid;3  grid-template-columns: repeat(3, 1fr);4  gap: 12px;5}6 7.card {8  height: 96px;9  padding: 12px;10  border: 1px solid #d9d4c7;11  border-radius: 8px;12}13 14.card h2 {15  margin: 0;16  font-size: 14px;17}18 19.card p {20  margin: 8px 0 0;21  font-size: 28px;22}23 24.tableBox {25  min-height: 240px;26  margin-top: 24px;27}

BrowserTerminalNetwork

Recorded from Next.js 16.4.3

/dashboardwith Asha's session cookie/dashboardwith Asha's session cookie, JavaScript off

localhost:3000/dashboardDashboard | Tea invoices

Sent with cookie: session=eyJhbGciOiJIUzI1NiJ9.eyJ1c2VySWQiOiJ1MSIsImlhdCI6MTc5MzMxODQwMCwiZXhwIjo0MTAyNDQ0ODAwfQ.sY9GVxj1-v3mOJvS4ev9s8MSmkxEorTL7e01C0TNkVQ. A picture of the page in real Chrome, in a window 800 px wide, taken once the page had loaded with its styles. Open it full size

The cards and the table's box are in the same places in both pictures. The Network tab says the same in text: the HTML that arrived first holds Paid, … and Loading your invoices…, and the parts streamed after it hold $120.00, $125.50, $339.50 and the three invoices.

When something fails

Two things can go wrong on the dashboard and the invoice page: the database can fail, and an invoice can be missing or not yours. Each has its own file, from Error handling and Not found, forbidden and unauthorized.

app/dashboard/error.tsx is a Client Component with a heading, a sentence and a Try again button that calls retry(). To see it, this version of the app has a database that is down: getMyInvoices throws The invoices table did not answer., a stand-in written for this recording.

1"use client";2 3export default function DashboardError({ retry }: { error: unknown; retry: () => void }) {4  return (5    <main>6      <h1>Your dashboard did not load</h1>7      <p>Something went wrong on our side.</p>8      <button onClick={() => retry()}>Try again</button>9    </main>10  );11}

In Steps, Chrome shows Your dashboard did not load in place of the page, under the layout's navigation. The message the browser got is Minified React error #441: React leaves the real one out in production. The real message is in the server's log: open the Terminal tab and find ⨯ Error: The invoices table did not answer., with a digest, the short code that ties the two together.

The missing invoice is in the first recording. In its Steps, the last step opens /invoices/4 as Asha, and Chrome shows Invoice not found. Now open its Network tab and pick /invoices/4 Ben's invoice, with Asha's session cookie. The status is 200, not 404, and the HTML holds Loading the invoice… and <meta name="robots" content="noindex">. The static shell had already gone out with 200 when notFound() ran inside Suspense, so Next.js added the noindex tag, and React drew not-found.tsx in the browser. Search engines never sign in, so they never see these pages anyway; what matters is that Asha sees nothing of Ben's.

Testing the action and the whole app

Two kinds of test, as in Testing components and End-to-end testing. A unit test runs one piece of code on its own, fast. An end-to-end test drives a real browser against the built app. The action is worth a unit test: it decides what gets saved.

1import { beforeEach, expect, test, vi } from "vitest";2import { updateTag } from "next/cache";3import { redirect } from "next/navigation";4import { createInvoice } from "@/lib/dal";5import { addInvoice, type InvoiceState } from "./actions";6 7vi.mock("@/lib/dal", () => ({ createInvoice: vi.fn() }));8vi.mock("next/cache", () => ({ updateTag: vi.fn() }));9vi.mock("next/navigation", () => ({ redirect: vi.fn() }));10 11const empty: InvoiceState = { message: "", errors: {}, values: { customer: "", amount: "", status: "pending" } };12 13function invoiceForm(customer: string, amount: string) {14  const formData = new FormData();15  formData.set("customer", customer);16  formData.set("amount", amount);17  formData.set("status", "pending");18  return formData;19}20 21beforeEach(() => {22  vi.clearAllMocks();23});24 25test("explains each mistake and saves nothing", async () => {26  const state = await addInvoice(empty, invoiceForm("L", "12.5"));27  expect(state.errors).toEqual({28    customer: ["Write the customer's name."],29    amount: ["Write an amount like 45 or 45.50."],30  });31  expect(state.values.customer).toBe("L");32  expect(createInvoice).not.toHaveBeenCalled();33});34 35test("saves cents, refreshes the team total and opens the invoice", async () => {36  vi.mocked(createInvoice).mockResolvedValue(6);37  await addInvoice(empty, invoiceForm("Lake Café", "12.50"));38  expect(createInvoice).toHaveBeenCalledWith({ customer: "Lake Café", amountCents: 1250, status: "pending" });39  expect(updateTag).toHaveBeenCalledWith("team-total");40  expect(redirect).toHaveBeenCalledWith("/invoices/6");41});42 43test("asks someone whose session ended to sign in again", async () => {44  vi.mocked(createInvoice).mockResolvedValue(null);45  const state = await addInvoice(empty, invoiceForm("Lake Café", "12.50"));46  expect(state.message).toBe("Sign in again to save this invoice.");47  expect(updateTag).not.toHaveBeenCalled();48});

$ npx vitest run --reporter=verbose RUN  v5.0.5 /my-app  ✓ app/invoices/new/actions.test.ts > explains each mistake and saves nothing ✓ app/invoices/new/actions.test.ts > saves cents, refreshes the team total and opens the invoice ✓ app/invoices/new/actions.test.ts > asks someone whose session ended to sign in again  Test Files  1 passed (1)      Tests  3 passed (3) $ next build▲ Next.js 16.4.3 (Turbopack)- Environments: .env- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (7/7)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ◐ /dashboard├   /invoices/[id]│ └ ◐ /invoices/[id]├ ○ /invoices/new└ ○ /sign-in ƒ Proxy (Middleware) ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

In app/invoices/new/actions.test.ts, lines 7 to 9 replace three modules with stand-ins: the data access layer, and updateTag and redirect from Next.js. A test calls the action directly, outside the request Next.js opens for a Server Action, where the real updateTag throws; the mocks also record what the action asked for. Then each test calls addInvoice with a form. The first sends L and 12.5 and expects both messages and no save. The second sends 12.50 and expects createInvoice to get 1250 cents, then updateTag("team-total") and redirect("/invoices/6"). The third has createInvoice return null, as for an ended session. The Terminal tab shows what npx vitest run printed: three tests passed.

The end-to-end test signs in through the real form and uses the app as Asha does:

1import { expect, test } from "@playwright/test";2import { waitForHydration } from "./hydration";3 4test.beforeEach(async ({ page }) => {5  await page.goto("/sign-in");6  await waitForHydration(page);7  await page.getByLabel("Email").fill("asha@example.com");8  // Asha's password in the seeded users table: a test fixture, never a real account's.9  await page.getByLabel("Password").fill("green-tea-123");10  await page.getByRole("button", { name: "Sign in" }).click();11  await expect(page.getByRole("heading", { name: "Dashboard" })).toBeVisible();12});13 14test("saves an invoice after fixing a mistake", async ({ page }) => {15  await page.getByRole("link", { name: "New invoice" }).click();16  await page.getByLabel("Customer").fill("Lake Café");17  await page.getByLabel("Amount in dollars").fill("12.5");18  await page.getByRole("button", { name: "Save invoice" }).click();19  await expect(page.getByText("Write an amount like 45 or 45.50.")).toBeVisible();20  await page.getByLabel("Amount in dollars").fill("12.50");21  await page.getByRole("button", { name: "Save invoice" }).click();22  await expect(page).toHaveURL(/\/invoices\/\d+$/);23  await expect(page.getByText("Lake Café: $12.50, pending")).toBeVisible();24});25 26test("can't open another user's invoice", async ({ page }) => {27  await page.goto("/invoices/4");28  await expect(page.getByRole("heading", { name: "Invoice not found" })).toBeVisible();29  await expect(page.getByText("Station Café")).toBeHidden();30});

$ npx playwright testRunning 2 tests using 1 worker   ✓  1 [chrome] › e2e/invoices.spec.ts:14:5 › saves an invoice after fixing a mistake  ✓  2 [chrome] › e2e/invoices.spec.ts:26:5 › can't open another user's invoice   2 passed $ next build▲ Next.js 16.4.3 (Turbopack)- Environments: .env- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (7/7)  Finalizing page optimization ... Route (app)┌ ○ /├ ○ /_not-found├ ◐ /dashboard├   /invoices/[id]│ └ ◐ /invoices/[id]├ ○ /invoices/new└ ○ /sign-in ƒ Proxy (Middleware) ○  (Static)             prerendered as static content◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content

In e2e/invoices.spec.ts, lines 4 to 12 sign in before each test. Line 6 waits for hydration first: Playwright waits for the email box to exist, not for React, and before hydration a click would post the form without the Server Action's JavaScript. The first test makes the mistake, fixes it and saves; line 22 checks the address with a pattern, not a fixed id, so a retry that saves a second invoice still passes. The second test opens Ben's invoice and expects Invoice not found, and never Station Café. playwright.config.ts builds and starts the app itself. The Terminal shows npx playwright test: two tests passed, with one worker, as on a CI server. The project's .gitignore keeps .env and Playwright's results out of git.

Deploying it

For a server of your own, Self-hosting builds a standalone folder: the server and only the packages it needs. One line in next.config.ts turns it on, output: "standalone", and three commands build it, copy the files the server sends as they are, and start it:

npm run build
cp -r public .next/standalone/ && cp -r .next/static .next/standalone/.next/
node .next/standalone/server.js

The recording below ran exactly that, twice, from one build: two instances, copies of the same server, as a load balancer would run them. Then it asked instance 1 for the dashboard, saved an invoice there without JavaScript, and asked both instances for Asha's dashboard.

1import type { NextConfig } from "next";2 3const nextConfig: NextConfig = {4  /* config options here */5  cacheComponents: true,6  partialPrefetching: true,7  output: "standalone",8  serverExternalPackages: ["@electric-sql/pglite"],9};10 11export default nextConfig;

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="stylesheet" href="/_next/static/chunks/20vm6th768-j-.css" data-precedence="next">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/1x6obpmlu1_c2.js">
    <script src="/_next/static/chunks/06bs-nf19b2js.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/0yuq46kwp2ick.js" async=""></script>
    <script src="/_next/static/chunks/2gsxhio73malr.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-2c3mg3r-05n1w.js" async=""></script>
    <script src="/_next/static/chunks/3lpb-5n2j6tj6.js" async=""></script>
    <script src="/_next/static/chunks/22cnum47sjw92.js" async=""></script>
    <title>Dashboard | Tea invoices</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <nav><a href="/dashboard">Dashboard</a> <a href="/invoices/new">New invoice</a></nav>
    <!--&-->
    <!--&-->
    <main>
      <h1>Dashboard</h1>
      <!--$?-->
      <template id="B:0"></template>
      <div class="Gx_nyq_cards" aria-busy="true">
        <section class="Gx_nyq_card">
          <h2>Paid</h2>
          <p>…</p>
        </section>
        <section class="Gx_nyq_card">
          <h2>Pending</h2>
          <p>…</p>
        </section>
        <section class="Gx_nyq_card">
          <h2>Whole team</h2>
          <p>…</p>
        </section>
      </div>
      <!--/$-->
      <!--$?-->
      <template id="B:1"></template>
      <div class="Gx_nyq_tableBox" aria-busy="true">
        <p>Loading your invoices…</p>
      </div>
      <!--/$-->
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <!--/&-->
    <script>…</script>
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/1x6obpmlu1_c2.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
    <div hidden="" id="S:1">
      <div class="Gx_nyq_tableBox">
        <table>
          <thead>
            <tr>
              <th>Invoice</th>
              <th>Customer</th>
              <th>Amount</th>
              <th>Status</th>
            </tr>
          </thead>
          <tbody>
            <tr>
              <td><a href="/invoices/3">Invoice <!-- -->3</a></td>
              <td>River Books</td>
              <td>$80.00</td>
              <td>pending</td>
            </tr>
            <tr>
              <td><a href="/invoices/2">Invoice <!-- -->2</a></td>
              <td>Hill Bakery</td>
              <td>$45.50</td>
              <td>pending</td>
            </tr>
            <tr>
              <td><a href="/invoices/1">Invoice <!-- -->1</a></td>
              <td>Lake Café</td>
              <td>$120.00</td>
              <td>paid</td>
            </tr>
          </tbody>
        </table>
      </div>
    </div>
    <script>…</script>
    <div hidden="" id="S:0">
      <div class="Gx_nyq_cards">
        <section class="Gx_nyq_card">
          <h2>Paid</h2>
          <p>$120.00</p>
        </section>
        <section class="Gx_nyq_card">
          <h2>Pending</h2>
          <p>$125.50</p>
        </section>
        <section class="Gx_nyq_card">
          <h2>Whole team</h2>
          <p>$339.50</p>
        </section>
      </div>
    </div>
    <script>…</script>
    <script>…</script>
  </body>
</html>

In the Network tab, /robots.txt answered 200 from public, copied in by the second command. Save invoice, on instance 1 answered 303 with location: /invoices/6: the form post without JavaScript. Instance 1's dashboard then said Pending $138.00 and Whole team $352.00, with Invoice 6 in the table. Instance 2's said $125.50 and $339.50, with no Invoice 6. Each instance had started its own PGlite, in its own memory.

That's the line between this project and production. Each row is one thing this project does for its recordings, and what a real deployment does instead:

For the database, only db/index.ts changes, to a pool of connections to one Postgres server:

import { drizzle } from "drizzle-orm/node-postgres";
import { Pool } from "pg";

// Every instance of the app connects to the same database.
const pool = new Pool({ connectionString: process.env.DATABASE_URL, max: 10 });

export const db = drizzle({ client: pool });

Line 5 opens up to ten connections to the server in DATABASE_URL, shared by every query this instance sends, as Connecting a database showed. The session secret leaves .env: Self-hosting showed that the build copies the env files it loads into the standalone folder, so a real secret is given to the server when it starts, from a secret store. The Dockerfile, a CDN in front, and a cache handler shared by every instance, so that updateTag on one reaches all of them, are in that lesson too. Before launch, go through The production checklist; Deploying Next.js compares the other ways to run it.

Which part does each job?

The app works because each job has one home. When you add a feature, the first question is where each part of it goes. Sort these jobs into the file that does them in this app:

For a bigger app, Structuring a large app shows how the same homes grow into feature folders: each feature with its own pages, actions and data access, and the same rules inside.

Common mix-ups

• "proxy.ts protects the invoices." No. It only checks that a cookie named session was sent. A made-up cookie passes it; getCurrentUser is what stops it.
• "A page only sellers use must be made for each request." No. /invoices/new holds nothing private, so the build made it once (○). The Server Action checks who saves.
• "Anything slow should go in "use cache"." No. A shared cache gives one copy to everyone with the same key. In this app only the team's total is the same for everyone; by its own policy, each seller's invoices stream in instead.
• "notFound() always answers 404." Only before the response starts. Inside Suspense, the shell had gone out with 200, so Next.js added a noindex tag instead.
• "Zod checks that the invoice is yours." No. Zod checks the shape of the form. The data access layer decides whose data it is.
• "Playwright waits for React." No. It waits for elements. A test that clicks a JavaScript form waits for hydration first.
• "Two instances of the server share the database." Not with PGlite in memory: each server has its own. Production uses one Postgres server and one cache store for every instance.

Practice exercises

These exercises are about the invoices app, which can't run inside this page. Answer first, then use the hints.

// One invoice, for its owner only. Anyone else gets null, as if it didn't exist.
export async function getInvoice(id: string) {
  if (!/^\d{1,9}$/.test(id)) return null;
  const user = await verifySession();
  const [invoice] = await db
    .select(shown)
    .from(invoices)
    .where(eq(invoices.id, Number(id)));
  return invoice ?? null;
}

    .where(and(eq(invoices.id, Number(id)), eq(invoices.userId, user.id)));

// The signed-in user's invoices, newest first.
export async function getMyInvoices() {
  "use cache";
  const user = await verifySession();
  return db.select(shown).from(invoices).where(eq(invoices.userId, user.id)).orderBy(desc(invoices.id));
}

import { Suspense } from "react";
import type { Metadata } from "next";
import { notFound } from "next/navigation";
import { getInvoice } from "@/lib/dal";
import { dollars } from "@/lib/money";

export async function generateMetadata({ params }: PageProps<"/invoices/[id]">): Promise<Metadata> {
  const { id } = await params;
  return { title: `Invoice ${id}` };
}

async function Invoice({ params }: Pick<PageProps<"/invoices/[id]">, "params">) {
  const { id } = await params;
  const invoice = await getInvoice(id);
  if (!invoice) notFound();
  return (
    <>
      <h1>Invoice {invoice.id}</h1>
      <p>
        {invoice.customer}: {dollars(invoice.amountCents)}, {invoice.status}
      </p>
    </>
  );
}

export default function InvoicePage({ params }: PageProps<"/invoices/[id]">) {
  return (
    <main>
      <Suspense fallback={<p>Loading the invoice…</p>}>
        <Invoice params={params} />
      </Suspense>
    </main>
  );
}

// lib/dal.ts
// Marks one of the signed-in user's invoices as paid. False when it isn't theirs.
export async function markInvoicePaid(id: number) {
  const user = await getCurrentUser();
  if (!user) return false;
  const rows = await db
    .update(invoices)
    .set({ status: "paid" })
    .where(and(eq(invoices.id, id), eq(invoices.userId, user.id)))
    .returning({ id: invoices.id });
  return rows.length === 1;
}

// app/invoices/[id]/actions.ts
"use server";

import { refresh } from "next/cache";
import { z } from "zod";
import { markInvoicePaid } from "@/lib/dal";

// The id comes from the page, and anyone can post another one. Zod checks its shape:
// a whole number from 1 to the largest id a Postgres integer holds.
const invoiceId = z.number().int().positive().max(2_147_483_647);

export async function markPaid(id: unknown) {
  const result = invoiceId.safeParse(id);
  if (!result.success) return;
  // markInvoicePaid checks the owner.
  if (await markInvoicePaid(result.data)) refresh();
}

// app/invoices/[id]/page.tsx, under the <p>
{invoice.status === "pending" && (
  <form action={markPaid.bind(null, invoice.id)}>
    <button>Mark as paid</button>
  </form>
)}

Check your understanding

For each question, think about who is asking, and whether the answer is the same for everyone.

Key takeaways

• Plan first: the pages and who may open each one, the tables, and where each check lives.
• Let the database keep the rules it can: a unique email, an owner for every invoice, amounts in cents above zero.
• proxy.ts is a quick first door. The data access layer is the real check: it finds who is asking, puts the owner into every query, and returns only the fields pages show.
• A Server Action checks the form's shape with Zod, saves through the data access layer, calls updateTag, then redirects.
• This app caches only what is the same for everyone, like the team's total, and streams each user's own data. That's its policy: plain "use cache" keyed by a verified user id is fine where storing per-user data is allowed.
• Give each Suspense boundary a skeleton the size of what replaces it, and an error.tsx and a not-found.tsx for when things fail.
• Test the action with Vitest and the app with Playwright, waiting for hydration. Deploy with one shared database and cache.

Coming next: Pages Router basics. Many existing Next.js apps are built with the older pages folder; the next lesson teaches enough of it to work in one.