EXPLAINER

Next.js

Next.js is a React framework that adds routing, server rendering, and server-side code next to the UI. Use it for full web apps. Use plain React when you only need a widget inside someone else's page.

Short answer: Next.js is a framework around React: file-based routes, server and client components, and a place to run secrets on the server. It is a good home for an app that calls model APIs. It is more than you need for a single SPFx web part.

What it is

Next.js is a framework built around React and Node.js. It gives you file-based routing, a production build, and a split between code that runs on the server and code that runs in the browser. The App Router model uses React Server Components: some components render only on the server, can read secrets and databases, and send the result to the client. Client components ("use client") handle state and clicks. Route handlers are server endpoints living beside the UI.

Next.js is not React itself. You can use React without it (see React). It is also not required for SPFx. It is one way to build a standalone web application, often deployed on Node or a host that supports its server runtime.

Why and when it is used

Choose Next.js when you are building a whole site or app: URLs, authenticated pages, a server that must hide API keys, and React on the screen. It fits an internal tool or a product UI that calls model APIs without exposing the key. The Vercel AI SDK examples assume this shape, which is convenience, not a requirement.

Choose plain React or Vite when you are shipping a widget, a design prototype, or an SPFx part. Choose a different server framework (Express, a Python API) when the UI is not React or the team does not want Node. Do not put a Next.js app inside a SharePoint page and also reimplement SharePoint. Decide where the product lives.

How it works

A route is a folder with a page file. The server renders it, fetching data directly if you wrote server code. Client components hydrate in the browser so clicks work. A mutation can be a server action or a call to a route handler. Environment variables that are not prefixed for the browser stay on the server. That is the feature you want for model keys. If you prefix a secret so the client bundle can see it, you published the secret.

Static rendering builds HTML ahead of time. Dynamic rendering runs per request. Pick dynamic when the page depends on the signed-in user. Caching in Next.js is powerful and has surprised teams who saw stale data. Know whether a fetch is cached before you debug "why is production wrong".

Technologies and dependencies

Node.js, React, and the Next.js package. TypeScript should be on. Deployment needs a Node-compatible host or the framework's own platform. A database or a model API is your choice. Frontend and Backend explains the split this framework is trying to make convenient. You still own auth: Next.js does not magically know your users.

How to get started

  1. Create a TypeScript Next.js app with the official scaffold. Run it locally and see the default page.
  2. Add a server-only route or page that reads a non-public environment variable and returns its length, not its value.
  3. Add a client component with a button that calls that route and displays the answer.
  4. Confirm in the browser network panel that the secret never appears in a downloaded JS file.
  5. Add one real URL with a dynamic segment and load data for it on the server.
  6. Turn on a production build (next build) before you celebrate. Dev mode hides issues.

Do not start by installing an authentication library, a CSS kit, an ORM and an AI SDK together. Get the server/client line bright first.

Cautions and trade-offs

The server/client boundary is the whole design. Importing a server module into a client component fails the build or, worse, leaks. Caching can serve one user's data to another if you cache a personalised fetch by accident. Treat cache keys as a security feature.

Next.js versions move. Pin them and read upgrade notes before you copy a blog that uses the old pages router and the new app router in one breath. Server components are not faster by magic if your database is slow. And a framework this large is the wrong tool for a four-file internal script. Use it when you want a product surface, and keep the domain logic in functions you can test without booting the framework.