docs: add Building guide

docs/01-app/01-getting-started/01-installation.mdx

@@ -318,6 +318,8 @@ export default function Page() {
 2. Visit `http://localhost:3000` to view your application.
 3. Edit the <AppOnly>`app/page.tsx`</AppOnly><PagesOnly>`pages/index.tsx`</PagesOnly> file and save it to see the updated result in your browser.
 
+When you're ready for production, run `npm run build` to [build your application](/docs/app/guides/building), then `npm run start` to start the server. Learn more about [deploying](/docs/app/getting-started/deploying).
+
 ## Set up TypeScript
 
 > Minimum TypeScript version: `v5.1.0`

docs/01-app/01-getting-started/17-deploying.mdx

@@ -26,7 +26,7 @@ Next.js can be deployed to any provider that supports Node.js. Ensure your `pack
 }
 ```
 
-Then, run `npm run build` to build your application and `npm run start` to start the Node.js server. This server supports all Next.js features. If needed, you can also eject to a [custom server](/docs/app/guides/custom-server).
+Then, run `npm run build` to [build your application](/docs/app/guides/building) and `npm run start` to start the Node.js server. This server supports all Next.js features. If needed, you can also eject to a [custom server](/docs/app/guides/custom-server).
 
 Node.js deployments support all Next.js features. Learn how to [configure them](/docs/app/guides/self-hosting) for your infrastructure.
 

docs/01-app/02-guides/building.mdx

@@ -0,0 +1,240 @@
+---
+title: Building your application
+description: Learn what happens when you run next build, how to read the build output, and how to fix common prerender errors.
+nav_title: Building
+related:
+  description: Related API references and guides.
+  links:
+    - app/api-reference/cli/next
+    - app/getting-started/caching
+    - app/api-reference/functions/generate-static-params
+    - app/api-reference/config/next-config-js/cacheComponents
+    - app/guides/streaming
+    - app/guides/ci-build-caching
+---
+
+Run `next build` to compile your app for production: optimized bundles, prerendered pages, and a route table that shows how each URL is served (fully static, partial prerender with streaming, or on demand).
+
+## What `next build` does
+
+`next build` runs in these phases:
+
+1. **Setup.** Loads [environment variables](/docs/app/guides/environment-variables) (`.env` files), validates your [`next.config`](/docs/app/api-reference/config/next-config-js), and generates a [build ID](/docs/app/api-reference/config/next-config-js/generateBuildId).
+2. **Route discovery.** Scans `app/` and `pages/` for routes, proxy, and [instrumentation](/docs/app/api-reference/file-conventions/instrumentation) hooks. Generates TypeScript route definitions.
+3. **Compilation.** Bundles client, server, and edge code with [Turbopack](/docs/app/api-reference/turbopack) (or webpack). Transpiles TypeScript and JSX, tree-shakes unused code, and optimizes CSS and fonts. Type checking runs in parallel.
+4. **Static analysis.** Classifies each route for prerendering versus on-demand rendering. Collects [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) output. Checks for [prerender-blocking errors](/docs/messages/blocking-route).
+5. **Prerendering.** Prerenders static pages and PPR shells to HTML. Generates [RSC payloads](/docs/app/getting-started/server-and-client-components#on-the-server) for client-side navigation.
+6. **Output.** Writes the build to `.next/`. For [`output: 'standalone'`](/docs/app/guides/self-hosting), bundles only the files needed at runtime. For [`output: 'export'`](/docs/app/guides/static-exports), generates a full static site. Prints the route table.
+
+## Reading the build output
+
+With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents), Next.js prerenders as much of each route as it can at build time. Request-time data (`params`, `searchParams`, `cookies()`, `headers()`, and similar) is not available during that pass. Wrap that work in [`<Suspense>`](/docs/app/guides/streaming) or [`'use cache'`](/docs/app/api-reference/directives/use-cache), or the build fails with a [prerender-blocking error](/docs/messages/blocking-route).
+
+After a successful build, the route table puts a **symbol on each main route row**. When you use [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params), the dynamic segment gets one labeled row, and each prerendered URL appears indented underneath that row. The legend at the bottom lists only symbols that appeared in the tree.
+
+| Symbol | Name              | Behavior                                                                   |
+| ------ | ----------------- | -------------------------------------------------------------------------- |
+| `○`    | Static            | Fully prerendered at build time. Served from CDN with no server work.      |
+| `◐`    | Partial Prerender | Static shell served from CDN. Dynamic content streams in at request time.  |
+| `●`    | SSG               | Prerendered static HTML (from `generateStaticParams` or `getStaticProps`). |
+| `ƒ`    | Dynamic           | Server-rendered on demand for every request.                               |
+
+With Cache Components, App Router `page` routes show `○` or `◐`. You still see `ƒ` for API routes, [Proxy](/docs/app/api-reference/file-conventions/proxy) routes, dynamic [metadata](/docs/app/api-reference/functions/generate-metadata) (such as `icon` or `opengraph-image`), and other handlers that render on every request. Without Cache Components, or on the Pages Router, prerendered pages can show `●` (SSG) and on-demand pages can show `ƒ` (Dynamic).
+
+[Partial Prerendering](/docs/app/getting-started/caching#how-rendering-works) is the default rendering model with Cache Components. The example below walks through a dynamic segment and shows how its prerendered URLs appear in the route table.
+
+## Example
+
+This example uses a dynamic product page at `/products/[id]` that loads data by id:
+
+```tsx filename="app/products/[id]/page.tsx" switcher
+export default async function Page({ params }) {
+  const { id } = await params
+  const product = await db.product.find(id)
+  return <div>{product.name}</div>
+}
+```
+
+```jsx filename="app/products/[id]/page.js" switcher
+export default async function Page({ params }) {
+  const { id } = await params
+  const product = await db.product.find(id)
+  return <div>{product.name}</div>
+}
+```
+
+`next build` fails with:
+
+```txt filename="Terminal"
+Uncached data, `params`, `searchParams`, or `connection()` was accessed outside of `<Suspense>`.
+This delays the entire page from rendering, resulting in a slow user experience.
+```
+
+Next.js does not know param values at build time, so it cannot prerender this page. Decide how to supply or defer that data. See the [blocking-route error reference](/docs/messages/blocking-route) for triggers and fixes.
+
+### Resolve params with `generateStaticParams`
+
+Export [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) so Next.js knows which param values exist at build time:
+
+```tsx filename="app/products/[id]/page.tsx" switcher
+export async function generateStaticParams() {
+  const products = await db.product.findMany()
+  return products.map((product) => ({ id: product.id }))
+}
+
+export default async function Page({ params }) {
+  const { id } = await params
+  const product = await db.product.find(id)
+  return <div>{product.name}</div>
+}
+```
+
+```jsx filename="app/products/[id]/page.js" switcher
+export async function generateStaticParams() {
+  const products = await db.product.findMany()
+  return products.map((product) => ({ id: product.id }))
+}
+
+export default async function Page({ params }) {
+  const { id } = await params
+  const product = await db.product.find(id)
+  return <div>{product.name}</div>
+}
+```
+
+`next build` succeeds:
+
+```bash filename="Terminal"
+Route (app)
+┌ ○ /
+├ ○ /_not-found
+├ ○ /products/[id]
+│ ├ /products/1
+│ ├ /products/2
+│ └ /products/3
+
+○  (Static)  prerendered as static content
+```
+
+The `○` on `├ ○ /products/[id]` means that whole route is **static prerender** (see the legend). The indented lines name each concrete URL Next.js built for the ids you returned from `generateStaticParams`, such as `/products/1`, `/products/2`, and `/products/3`.
+
+When there are more paths than fit in the preview, Next.js prints a short list and ends with `[+N more paths]`.
+
+> **Good to know**: `generateStaticParams` must return at least one param. An empty array causes a [build error](/docs/messages/empty-generate-static-params).
+
+Routes that use [`cacheLife`](/docs/app/api-reference/functions/cacheLife) also show `Revalidate` and `Expire` columns:
+
+```bash filename="Terminal"
+Route (app)                Revalidate  Expire
+┌ ○ /                             15m      1y
+├ ○ /_not-found
+├ ○ /products/[id]                15m      1y
+│ ├ /products/1                   15m      1y
+│ ├ /products/2                   15m      1y
+│ └ /products/3                   15m      1y
+```
+
+### Stream dynamic content with Suspense
+
+When you cannot list every param ahead of time, or part of the page needs cookies or headers, [stream](/docs/app/guides/streaming) that work inside [`<Suspense>`](https://react.dev/reference/react/Suspense), or add [`loading.js`](/docs/app/api-reference/file-conventions/loading):
+
+```tsx filename="app/products/[id]/page.tsx" switcher
+import { Suspense } from 'react'
+
+export default function Page({ params }) {
+  return (
+    <Suspense fallback={<ProductSkeleton />}>
+      <ProductContent params={params} />
+    </Suspense>
+  )
+}
+
+async function ProductContent({ params }) {
+  const { id } = await params
+  const product = await db.product.find(id)
+  return <div>{product.name}</div>
+}
+```
+
+```jsx filename="app/products/[id]/page.js" switcher
+import { Suspense } from 'react'
+
+export default function Page({ params }) {
+  return (
+    <Suspense fallback={<ProductSkeleton />}>
+      <ProductContent params={params} />
+    </Suspense>
+  )
+}
+
+async function ProductContent({ params }) {
+  const { id } = await params
+  const product = await db.product.find(id)
+  return <div>{product.name}</div>
+}
+```
+
+The fallback becomes part of the static shell. The rest streams in on each request:
+
+```bash filename="Terminal"
+Route (app)
+┌ ○ /
+├ ○ /_not-found
+└ ◐ /products/[id]
+
+○  (Static)             prerendered as static content
+◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content
+```
+
+You can combine `generateStaticParams` for known params with `<Suspense>` for request-specific content on the same page.
+
+### High-cardinality routes
+
+Large or unbounded slug sets (for example, millions of product pages) are not practical to prerender fully at build time.
+
+The experimental [`partialFallbacks`](/docs/app/api-reference/config/next-config-js/partialFallbacks) flag serves a `<Suspense>` shell from the CDN for unknown slugs while data streams in. After the first visit, the page can be cached and treated as static.
+
+```ts filename="next.config.ts"
+import type { NextConfig } from 'next'
+
+const nextConfig: NextConfig = {
+  cacheComponents: true,
+  experimental: {
+    partialFallbacks: true,
+  },
+}
+
+export default nextConfig
+```
+
+Without `partialFallbacks`, unlisted params wait on the server for a full render before the response is sent. With `partialFallbacks`, keep `generateStaticParams` small and let traffic decide which extra pages warm into cache.
+
+## Debugging prerender errors
+
+When the error does not include a clear file and line, run:
+
+```bash filename="Terminal"
+next build --debug-prerender
+```
+
+That disables minification, turns on source maps for server bundles, and prints stack traces that point at the triggering code. The build also continues after the first failure so you can see every issue in one run.
+
+> **Warning**: Do not deploy builds produced with `--debug-prerender`. They skip optimizations you need in production.
+
+### Building specific routes
+
+To iterate faster in a large app, scope the build with `--debug-build-paths`:
+
+```bash filename="Terminal"
+next build --debug-build-paths="app/products/[id]/page.tsx"
+```
+
+Use comma-separated paths or globs. See [`--debug-build-paths`](/docs/app/api-reference/cli/next#building-specific-routes) for syntax.
+
+## Next steps
+
+Next, learn how to:
+
+- [Deploy your application](/docs/app/getting-started/deploying)
+- [Cache data and UI](/docs/app/getting-started/caching)
+- [Configure CI build caching](/docs/app/guides/ci-build-caching)

docs/01-app/03-api-reference/06-cli/next.mdx

@@ -89,6 +89,8 @@ Route (app)
 ƒ  (Dynamic)  server-rendered on demand
 ```
 
+See the [Building guide](/docs/app/guides/building) to learn how to read the output, pre-render dynamic routes, and debug build errors.
+
 The following options are available for the `next build` command:
 
 | Option                             | Description                                                                                                                                                                        |