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,199 @@
+---
+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/api-reference/functions/generate-static-params
+    - app/api-reference/config/next-config-js/cacheComponents
+    - app/guides/streaming
+    - app/guides/public-static-pages
+    - app/guides/ci-build-caching
+---
+
+When your application is ready for production, `next build` compiles it into optimized bundles and prerendered pages. The build output shows how each route will be served: fully static or partially prerendered.
+
+This guide covers how to read the build output, pre-render dynamic routes, and fix common build errors.
+
+## What `next build` does
+
+Running `next build` goes through 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/` directories for routes, middleware, 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 as static or partially prerendered. 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 final 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 possible at build time. Components that depend on request-time data (such as `params`, `searchParams`, `cookies()`, or `headers()`) cannot be resolved ahead of time. You need to explicitly handle these with [`<Suspense>`](/docs/app/guides/streaming) or [`'use cache'`](/docs/app/api-reference/directives/use-cache), otherwise the build fails with a [prerender-blocking error](/docs/messages/blocking-route).
+
+After a successful build, the route table shows a symbol next to each route:
+
+| 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. |
+| `ƒ`    | Dynamic           | Server-rendered on demand for every request.                              |
+
+With [Cache Components](/docs/app/api-reference/config/next-config-js/cacheComponents), pages are always `○` or `◐`. The `ƒ` symbol appears 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 projects without Cache Components.
+
+[Partial Prerendering](/docs/app/getting-started/caching#how-rendering-works) is the default rendering model. For dynamic routes with [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params), each listed param shows its own symbol: `○` if the page is fully static, or `◐` if it contains streamed content.
+
+## Example
+
+We have a dynamic product detail page at `/products/[id]` that fetches product data:
+
+```tsx filename="app/products/[id]/page.tsx"
+export default async function Page({ params }) {
+  const { id } = await params
+  const product = await db.product.find(id)
+  return <div>{product.name}</div>
+}
+```
+
+Running `next build` fails:
+
+```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.
+```
+
+The param values are unknown at build time, so Next.js cannot prerender the page. You need to tell it how to handle the dynamic data. See the [blocking-route error reference](/docs/messages/blocking-route) for a full list of triggers and fixes.
+
+### Resolve params with `generateStaticParams`
+
+The most direct fix is telling Next.js which param values exist. Export [`generateStaticParams`](/docs/app/api-reference/functions/generate-static-params) to resolve them at build time:
+
+```tsx filename="app/products/[id]/page.tsx"
+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>
+}
+```
+
+Now `next build` succeeds:
+
+```bash filename="Terminal"
+Route (app)
+┌ ○ /
+├ ○ /_not-found
+├ /products/[id]
+│ ├ ○ /products/1
+│ ├ ○ /products/2
+│ └ ○ [+4 more paths]
+
+○  (Static)             prerendered as static content
+◐  (Partial Prerender)  prerendered as static HTML with dynamic server-streamed content
+```
+
+Unlisted params (for example, `/products/99`) are server-rendered on the first request and the page has to resolve entirely without a fallback. After the first visit, the result is cached.
+
+> **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]
+│ ├ ○ /products/1                 15m      1y
+│ ├ ○ /products/2                 15m      1y
+│ └ ○ [+4 more paths]
+```
+
+### Stream dynamic content with Suspense
+
+You may not have all param values ahead of time, or the page may have content that depends on the request (cookies, headers). In these cases, [stream](/docs/app/guides/streaming) the dynamic content with [`<Suspense>`](https://react.dev/reference/react/Suspense), or add a [`loading.js`](/docs/app/api-reference/file-conventions/loading) file:
+
+```tsx filename="app/products/[id]/page.tsx"
+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 is prerendered into the static shell. The content streams in at request time:
+
+```bash filename="Terminal"
+Route (app)
+┌ ○ /
+├ ○ /_not-found
+├ ◐ /products/[id]
+│ └ ◐ /products/[id]
+```
+
+You can combine both approaches: use `generateStaticParams` for known params and `<Suspense>` for dynamic content within the page.
+
+### High-cardinality routes
+
+For sites with many possible slugs (e-commerce with millions of products, user-generated content), pre-rendering every page at build time is not practical.
+
+The experimental [`partialFallbacks`](/docs/app/api-reference/config/next-config-js/partialFallbacks) flag serves an instant `<Suspense>` shell from CDN for unknown slugs while the dynamic data streams in. After the first visit, the page is cached and upgraded to a fully static version.
+
+```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 block until the server finishes rendering. With `partialFallbacks`, you can keep `generateStaticParams` small and let traffic determine which additional pages get cached.
+
+## Debugging prerender errors
+
+If the error does not point to the exact line, use `--debug-prerender`:
+
+```bash filename="Terminal"
+next build --debug-prerender
+```
+
+This disables minification and enables source maps for server bundles, producing readable stack traces that show which function triggered the error. It also continues past the first error so you can see all issues at once.
+
+> **Warning:** Do not deploy builds generated with `--debug-prerender`. It disables optimizations needed for production performance.
+
+### Building specific routes
+
+In large applications, you can build only specific routes using `--debug-build-paths` to speed up debugging:
+
+```bash filename="Terminal"
+next build --debug-build-paths="app/products/[id]/page.tsx"
+```
+
+This accepts comma-separated file paths and glob patterns. See [`--debug-build-paths`](/docs/app/api-reference/cli/next#building-specific-routes) for more details.
+
+## 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                                                                                                                                                                        |