The React you need for Next.js

A Next.js page is React you already know

Every page, layout and button in a Next.js app is a React component. Next.js adds files, folders and a server around them, but the code inside is React. This lesson is a quick refresher on the React that Next.js code uses every day, and on the few places where Next.js changes how it behaves. It doesn't teach React from the start: each section links to the React lessons that do.

Here is one page of the tea shop from Why Next.js?, as a real Next.js 16.4.3 project. It was built with next build, run with next start, and what it sent back was recorded. Click a file in the tree to read it.

1import { getTeas } from "./teas";2import TeaCard from "./tea-card";3 4export default async function Home() {5  const teas = await getTeas();6  return (7    <main>8      <h1>Tea shop</h1>9      {teas.map((tea) => (10        <TeaCard key={tea.id} name={tea.name} price={tea.price} />11      ))}12    </main>13  );14}

Almost every line is React:

• Home, on line 4 of app/page.tsx, is a component: a function that returns markup.
• Line 5 waits for getTeas(), because Home is an async Server Component. It runs only on the server.
• Line 10 makes a TeaCard for each tea with map and a key, and hands it two props: name and price.
• In app/tea-card.tsx, line 6 keeps a count in state, and line 11 changes it in an event handler.
• Line 1 of app/tea-card.tsx is "use client". That's the one line here that isn't everyday React. It marks where the part of the app that also runs in the browser begins, so the card can keep state and handle clicks.

Open the Network tab: the HTML already holds the heading and the three cards, each with an Add to cart button. Both components ran on the server to make that HTML. Only TeaCard's code also goes to the browser, so the button works there.

If any of these feel new, read its React lesson first. Here they all are, in the order this lesson reminds you of them:

• Your first component
• Props
• State: a component's memory
• Effects
• You might not need an Effect
• Suspense
• The use API
• Server Components
• Server Functions
• Form actions

Components, props and state

Here is the tea card again, this time as a client-rendered React example, like a new Vite app: React draws it in the browser, so it runs right in this page. Click Add to cart on Mint tea twice, then once on Green tea.

1import TeaCard from "./TeaCard.jsx";2 3const teas = [4  { id: "green", name: "Green tea", price: 4 },5  { id: "mint", name: "Mint tea", price: 3 },6  { id: "lemon", name: "Lemon tea", price: 3 },7];8 9export default function App() {10  return (11    <main>12      <h1>Tea shop</h1>13      {teas.map((tea) => (14        <TeaCard key={tea.id} name={tea.name} price={tea.price} />15      ))}16    </main>17  );18}

Mint tea's button says In cart: 2, and Green tea's says In cart: 1. Lemon tea's still says Add to cart. A quick reminder of why:

• A component is a function whose name starts with a capital letter and that returns JSX. App on line 9 is one, and so is TeaCard in the TeaCard.jsx tab.
• Props are the inputs a parent hands a child. Line 14 hands each card a name and a price, and line 3 of TeaCard.jsx takes them out with destructuring. A component never changes its own props.
• State is a component's memory. Line 4 of TeaCard.jsx gives each card its own count, so the three counts don't mix. Calling setCount on line 9 asks React to run the component again with the new value, and React updates the button.
• The key on line 14 tells React which card is which when the list changes (Rendering lists).

What changes in Next.js. The card is the same code, with types and one more line. In the overview's app/tea-card.tsx, line 1 is "use client": state and clicks only work in Client Components. The list itself moved into Home, a Server Component, which hands each card its props. Props that go from a Server Component to a Client Component travel from the server to the browser, so they have to be data: text, numbers, plain objects and arrays. The section on Server Components shows what else can travel. Sharing state and Thinking in React teach where state should live; in Next.js, that place has to be a Client Component.

Effects, and when you don't need one

An Effect is code that React runs after a component is on the screen, to keep it in step with something outside React: a timer, a browser event, a connection. This one keeps a number in step with the size of the window. The result frame is a small window of its own.

1import { useEffect, useState } from "react";2 3export default function WindowWidth() {4  const [width, setWidth] = useState(null);5 6  useEffect(() => {7    function measure() {8      setWidth(window.innerWidth);9    }10    measure();11    window.addEventListener("resize", measure);12    return () => window.removeEventListener("resize", measure);13  }, []);14 15  return <p>{width === null ? "Measuring your window…" : `Your window is ${width} px wide.`}</p>;16}

Line 4 starts width at null. After React has put the paragraph on the screen, it runs the Effect on lines 6 to 13: line 10 measures the window, and line 11 measures it again whenever it's resized. Line 12 returns a cleanup function, which React calls when the component goes away, so the listener doesn't stay behind. The empty array on line 13 says the Effect depends on nothing, so it runs once. The result says Your window is … px wide. with the result frame's width; make your browser window narrower to watch it change.

What changes in Next.js. Effects run only in the browser. Next.js makes a Client Component's HTML on the server without running its Effects, because the server has no screen and no window. Here is the same component in a Next.js page. Open the Browser tab:

1"use client";2 3import { useEffect, useState } from "react";4 5export default function WindowWidth() {6  const [width, setWidth] = useState<number | null>(null);7 8  useEffect(() => {9    function measure() {10      setWidth(window.innerWidth);11    }12    measure();13    window.addEventListener("resize", measure);14    return () => window.removeEventListener("resize", measure);15  }, []);16 17  return <p>{width === null ? "Measuring your window…" : `Your window is ${width} px wide.`}</p>;18}

The recorded page says Measuring your window…: the HTML was made during next build, with width still null from line 6 of app/window-width.tsx, so line 17 chose the first text. In the browser, React runs the Effect after hydration: React matches the Client Components to the HTML that's already on the screen and attaches their event handlers. Then the width appears. A Server Component can't have Effects at all: they need a browser to run in.

Many Effects aren't needed. An Effect that only works out a value from props or state does extra work: React draws the page, runs the Effect, then draws it again with the new value. Work the value out while rendering instead:

1import { useState } from "react";2 3const prices = { green: 4, mint: 3, lemon: 3 };4 5export default function App() {6  const [cart, setCart] = useState(["green", "mint"]);7  const total = cart.reduce((sum, id) => sum + prices[id], 0);8 9  return (10    <>11      <p>12        {cart.length} teas, total ${total}13      </p>14      <button onClick={() => setCart([...cart, "lemon"])}>Add lemon tea</button>15    </>16  );17}

Line 7 adds up the prices each time App runs, so total is always right: 2 teas, total $7, and after a click on Add lemon tea, 3 teas, total $10. This is the version to avoid; it isn't a whole app, so it doesn't run on its own:

// Avoid: an Effect that copies one state into another
const [total, setTotal] = useState(0);
useEffect(() => {
  setTotal(cart.reduce((sum, id) => sum + prices[id], 0));
}, [cart]);

In Next.js there's one more Effect you rarely need: the one that loads a page's data. In a client-rendered React app, a component can start a request in an Effect after it's on the screen (Fetching data shows that, and better ways). In Next.js, an async Server Component waits for the data on the server, like Home in the overview, so the data is already in the HTML. Effects and You might not need an Effect teach both sides in full.

Suspense and the use API

Suspense shows a fallback, like a loading message, while a part of the page waits for something. The use API reads the value of a promise inside a component. If the promise hasn't settled yet, the component waits, and the nearest Suspense shows its fallback. Press Run again on the result to watch it.

1import { Suspense, use } from "react";2import { getTeas } from "./api.js";3 4const teasPromise = getTeas();5 6function TeaList({ teasPromise }) {7  const teas = use(teasPromise);8  return (9    <ul>10      {teas.map((tea) => (11        <li key={tea.id}>{tea.name}</li>12      ))}13    </ul>14  );15}16 17export default function App() {18  return (19    <main>20      <h1>Tea shop</h1>21      <Suspense fallback={<p>Loading teas…</p>}>22        <TeaList teasPromise={teasPromise} />23      </Suspense>24    </main>25  );26}

Line 4 starts the request once, outside any component, and keeps its promise. In the api.js tab, line 9 answers after 600 ms. Line 7 reads the promise with use. For the first 600 ms, the teas aren't there yet, so the Suspense on line 21 shows Loading teas…. The heading on line 20 is outside it, so it shows at once. When the promise settles, React shows the list.

What changes in Next.js. Two things. First, the server can start the request and hand the promise to a Client Component, which reads it with use. Second, the server streams the page: it sends the HTML around the Suspense first, with the fallback, and the waiting part later in the same response. Here, getTeas in app/teas.ts calls connection() on line 5, which waits for a real request, so the teas are read for each visitor instead of during the build.

1import { Suspense } from "react";2import { getTeas } from "./teas";3import TeaList from "./tea-list";4 5export default function Home() {6  const teasPromise = getTeas();7  return (8    <main>9      <h1>Tea shop</h1>10      <Suspense fallback={<p>Loading teas…</p>}>11        <TeaList teasPromise={teasPromise} />12      </Suspense>13    </main>14  );15}

Line 6 of app/page.tsx calls getTeas() without await, and line 11 hands the promise to TeaList. Line 8 of app/tea-list.tsx reads it with use, as in the live example. Open the Terminal tab: ◐ / means prerendered as static HTML with dynamic server-streamed content. Here, the heading and the fallback were made during the build, and the teas are streamed in for each request. The Network tab shows the HTML as it arrived: the fallback Loading teas… near the top, and the teas further down, which React swaps in. The Browser tab shows the page after the swap.

Suspense, The use API and Streaming teach these in full. In Next.js, a loading.tsx file is a Suspense around a whole page; Loading UI shows it.

Server Components and Server Functions

A Server Component is a React component that runs only on the server. It can be async, wait for data, and read things the browser must never see, like a database password. Its code never goes to the browser; only what it rendered does. A Client Component is one whose file starts with "use client", or is imported by such a file. Its HTML is made on the server too, and then its code runs in the browser. In Next.js, components start as Server Components.

A Server Function is an async function in a file that starts with "use server". It runs on the server, but the browser can call it: as a form's action, or from a Client Component. The browser never gets its code, only a reference to it.

Each row is one thing you might want a component to do, and whether each kind of component can do it:

Try it below. Each button is a version of the page's app/page.tsx, built with real Next.js. Before you click, guess which versions build.

1import { getTeas } from "./teas";2import TeaCard from "./tea-card";3 4export default async function Home() {5  const teas = await getTeas();6  return (7    <main>8      <h1>Tea shop</h1>9      {teas.map((tea) => (10        <TeaCard key={tea.id} name={tea.name} price={tea.price} />11      ))}12    </main>13  );14}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /└ ○ /_not-found ○  (Static)  prerendered as static content

The first and last versions build; the middle two don't. A Server Component can wait for data, but it can't keep state. It can hand a Client Component data, but not an ordinary function: a function is code, and a Server Component's code stays on the server. A Server Function is the way through. In the last version, addToCart comes from app/actions.ts, whose line 1 is "use server". Open its Network tab: the page's JavaScript holds the button's code, but not the text addToCart ran on the server from line 4 of app/actions.ts. The function stays on the server, and the button calls it from there.

Server Components and Server Functions teach how React itself does this. Next.js has a whole stage on it, Server and Client Components.

Forms and actions

In React 19, a form's action can be a function. When the form is submitted, React calls it with the form's fields as FormData. When the action finishes without an error, React resets the form's uncontrolled fields: the ones without a value prop, like this box. A controlled field, whose value comes from state, keeps what its state says. useActionState keeps what the action returned, and says whether it's still running. Type Fresh in the box and press Save review.

1import { useActionState } from "react";2import { saveReview } from "./api.js";3 4export default function App() {5  const [message, formAction, isPending] = useActionState(saveReview, "");6  return (7    <form action={formAction}>8      <label>9        Your review <input name="review" />10      </label>11      <button disabled={isPending}>{isPending ? "Saving…" : "Save review"}</button>12      {message && <p>{message}</p>}13    </form>14  );15}

Line 5 calls useActionState with the action, saveReview, and a first message, "". It gives back three things: the latest message, a formAction to give the form on line 7, and isPending. While saveReview waits (600 ms, in the api.js tab), line 11 shows Saving… on a button that can't be pressed. Then line 12 shows Saved: Fresh, and the box is empty again.

What changes in Next.js. The action can be a Server Function, so saving happens on the server. The form is the same code with "use client" on line 1, because useActionState is a hook, and saveReview now comes from app/actions.ts:

1"use client";2 3import { useActionState } from "react";4import { saveReview } from "./actions";5 6export default function ReviewForm() {7  const [message, formAction, isPending] = useActionState(saveReview, "");8  return (9    <form action={formAction}>10      <label>11        Your review <input name="review" />12      </label>13      <button disabled={isPending}>{isPending ? "Saving…" : "Save review"}</button>14      {message && <p>{message}</p>}15    </form>16  );17}

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <link rel="preload" as="script" fetchpriority="low" href="/_next/static/chunks/3cfn99dbrcvvp.js">
    <script src="/_next/static/chunks/2gsxhio73malr.js" async=""></script>
    <script src="/_next/static/chunks/2ki52vdnbo2ft.js" async=""></script>
    <script src="/_next/static/chunks/0ooaq-girjaeh.js" async=""></script>
    <script src="/_next/static/chunks/turbopack-3-ry682tkyiqk.js" async=""></script>
    <script src="/_next/static/chunks/1tq6ppe__m8m-.js" async=""></script>
    <script src="/_next/static/chunks/1v8osnl9wukv9.js" async=""></script>
    <title>Tea shop</title>
    <script src="/_next/static/chunks/0cz1d0mv5g_q7.js" nomodule=""></script>
  </head>
  <body>
    <div hidden="">
      <!--$-->
      <!--/$-->
    </div>
    <!--&-->
    <main>
      <h1>Mint tea</h1>
      <form action="" enctype="multipart/form-data" method="POST"><input type="hidden" name="$ACTION_REF_1"><input type="hidden" name="$ACTION_1:0" value="{&quot;id&quot;:&quot;60bb3a4b6c673488ffcfb081cc3359ac63e6b36614&quot;,&quot;bound&quot;:&quot;$@1&quot;}"><input type="hidden" name="$ACTION_1:1" value="[&quot;&quot;]"><input type="hidden" name="$ACTION_KEY" value="k67721075b722be81e4508015683e29d2"><label>Your review <input name="review"></label><button>Save review</button></form>
    </main>
    <!--$-->
    <!--/$-->
    <!--/&-->
    <script id="_R_">…</script>
    <script src="/_next/static/chunks/3cfn99dbrcvvp.js" async=""></script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
    <script>…</script>
  </body>
</html>

The Network tab shows the form's HTML: <form action="" method="POST">, with hidden fields that hold the action's id. So the form works even before the JavaScript has loaded: the browser posts the fields and the id to the page's own address, and the server runs saveReview. Once React has hydrated the page, it sends the form itself, and isPending shows Saving… as in the live example. The page's JavaScript contains Save review, but not saveReview ran on the server from line 5 of app/actions.ts.

Forms, Form actions and Optimistic UI teach these in full. The course's data stage builds forms that save with Server Functions.

A tea page that uses all of it

Real pages mix all of these. Here is the Mint tea page: the card from the overview, the reviews, which are read for each visitor, and the review form. Read app/page.tsx, then the other files.

1import { Suspense } from "react";2import { getTea } from "./data";3import TeaCard from "./tea-card";4import Reviews from "./reviews";5import ReviewForm from "./review-form";6 7export default async function TeaPage() {8  const tea = await getTea("mint");9  return (10    <main>11      <TeaCard name={tea.name} price={tea.price} />12      <h2>Reviews</h2>13      <Suspense fallback={<p>Loading reviews…</p>}>14        <Reviews teaId={tea.id} />15      </Suspense>16      <ReviewForm />17    </main>18  );19}

• Lines 7 and 8 of app/page.tsx: TeaPage is an async Server Component that waits for the tea.
• Line 11 hands the tea's name and price to TeaCard, the Client Component with the count.
• Lines 13 to 15 put Reviews in a Suspense. Reviews is an async Server Component too, and line 9 of app/data.ts makes it wait for a request, so the server streams it in.
• Line 16 adds ReviewForm, a Client Component whose action is the Server Function saveReview.

The Terminal says ◐ /: a static shell, with the reviews streamed in for each request. In the Network tab, the HTML holds Loading reviews… first, and the reviews from Asha and Ravi further down. The page's JavaScript contains Add to cart and Save review, but not the reviews' text. Reviews is a Server Component, so its code, and the code that loads the reviews, stay on the server. What it rendered, the reviews' text, is sent to the browser in the HTML.

Sort these components: which ones can stay Server Components, and which need "use client"?

Common mix-ups

• "Next.js has its own kind of React." No. It installs React 19.3.0, and pages, layouts and buttons are ordinary React components. Next.js decides where each one runs.
• "A Client Component only runs in the browser." No. Its HTML is made on the server too, like each card's Add to cart in the recorded HTML. Then its code also runs in the browser.
• "Every component needs "use client"." No. Only the ones that need state, event handlers, Effects or browser APIs. The rest stay Server Components, and their code stays on the server.
• "Effects run on the server first." No. Effects run only in the browser. The server's HTML shows the state from before the Effect, like Measuring your window….
• "A Next.js page loads its data in an Effect." It can, in a Client Component, but it usually doesn't need to: an async Server Component waits for the data on the server, and the data is in the HTML.
• "A Server Function's code is sent to the browser." No. The browser gets an id it sends back; the code stays on the server.

Each row is one piece of React: how it behaves in this lesson's client-rendered React examples, and what changes in Next.js.

Practice exercises

The React exercises run in the page: press Edit & run to try your answer. The Next.js ones can't run inside this page.

import TeaCard from "./TeaCard.jsx";

const teas = [
  { id: "green", name: "Green tea", price: 4 },
  { id: "mint", name: "Mint tea", price: 3 },
  { id: "lemon", name: "Lemon tea", price: 3 },
];

export default function App() {
  return (
    <main>
      <h1>Tea shop</h1>
      {teas.map((tea) => (
        <TeaCard key={tea.id} name={tea.name} price={tea.price} />
      ))}
    </main>
  );
}

app/
  actions.ts
  data.ts
  layout.tsx
  page.tsx
  review-form.tsx
  reviews.tsx
  tea-card.tsx

1import { useEffect, useState } from "react";2 3const prices = { green: 4, mint: 3, lemon: 3 };4 5export default function App() {6  const [cart, setCart] = useState(["green", "mint"]);7  const [total, setTotal] = useState(0);8 9  useEffect(() => {10    setTotal(cart.reduce((sum, id) => sum + prices[id], 0));11  }, [cart]);12 13  return (14    <>15      <p>16        {cart.length} teas, total ${total}17      </p>18      <button onClick={() => setCart([...cart, "lemon"])}>Add lemon tea</button>19    </>20  );21}

1import { useState } from "react";2 3const prices = { green: 4, mint: 3, lemon: 3 };4 5export default function App() {6  const [cart, setCart] = useState(["green", "mint"]);7  const total = cart.reduce((sum, id) => sum + prices[id], 0);8 9  return (10    <>11      <p>12        {cart.length} teas, total ${total}13      </p>14      <button onClick={() => setCart([...cart, "lemon"])}>Add lemon tea</button>15    </>16  );17}

1import { use } from "react";2import { getTeas } from "./api.js";3 4const teasPromise = getTeas();5 6function TeaList({ teasPromise }) {7  const teas = use(teasPromise);8  return (9    <ul>10      {teas.map((tea) => (11        <li key={tea.id}>{tea.name}</li>12      ))}13    </ul>14  );15}16 17export default function App() {18  return (19    <main>20      <h1>Tea shop</h1>21      <TeaList teasPromise={teasPromise} />22    </main>23  );24}

1import { Suspense, use } from "react";2import { getTeas } from "./api.js";3 4const teasPromise = getTeas();5 6function TeaList({ teasPromise }) {7  const teas = use(teasPromise);8  return (9    <ul>10      {teas.map((tea) => (11        <li key={tea.id}>{tea.name}</li>12      ))}13    </ul>14  );15}16 17export default function App() {18  return (19    <main>20      <h1>Tea shop</h1>21      <Suspense fallback={<p>Loading teas…</p>}>22        <TeaList teasPromise={teasPromise} />23      </Suspense>24    </main>25  );26}

import AddButton from "./add-button";

export default function Home() {
  return (
    <main>
      <h1>Tea shop</h1>
      <AddButton name="Mint tea" onAdd={(name) => console.log(name)} />
    </main>
  );
}

1import { useActionState } from "react";2import { saveReview } from "./api.js";3 4export default function App() {5  const [message, formAction] = useActionState(saveReview, "");6  return (7    <form action={formAction}>8      <label>9        Your review <input name="review" />10      </label>11      <button>Save review</button>12      {message && <p>{message}</p>}13    </form>14  );15}

1import { useActionState } from "react";2import { saveReview } from "./api.js";3 4export default function App() {5  const [message, formAction, isPending] = useActionState(saveReview, "");6  return (7    <form action={formAction}>8      <label>9        Your review <input name="review" />10      </label>11      <button disabled={isPending}>{isPending ? "Saving…" : "Save review"}</button>12      {message && <p>{message}</p>}13    </form>14  );15}

Check your understanding

For each question, ask where the code runs: on the server, in the browser, or both.

Key takeaways

• Next.js code is React code: pages, layouts and buttons are components with props, state, Effects and Suspense.
• Components start as Server Components. They can be async and wait for data, and their code stays on the server.
• A file that starts with "use client" marks the part that also runs in the browser. State, event handlers and Effects live there.
• Effects run only in the browser. The server's HTML shows the state from before them.
• Suspense shows a fallback while a part waits, and the server streams that part in. A Client Component can read a promise from the server with use.
• A Server Component hands a Client Component data, promises and Server Functions, never ordinary functions. A Server Function runs on the server; the browser only gets a reference to it.
• A form's action can be a Server Function, and the form then works before the JavaScript has loaded.

Coming next: How Next.js works: a first look. It follows one visit to the tea shop, from next build to a click on a link, and shows what travels between the server and the browser.