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,188 @@
+---
+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 will show you 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.
+
+## Prerendering with Cache Components
+
+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()`) can't be resolved ahead of time. Next.js requires you to explicitly handle these with [`<Suspense>`](/docs/app/guides/streaming) or [`'use cache'`](/docs/app/api-reference/directives/use-cache). If you don't, the build fails with a [prerender-blocking error](/docs/messages/blocking-route).
+
+Every route in the build output is either fully static (`○`) or partially prerendered (`◐`). [Partial Prerendering](/docs/app/getting-started/caching#how-rendering-works) is the default rendering model. The static parts are served instantly from a CDN. The dynamic parts stream in at request time.
+
+## Example
+
+As an example, we'll work with a product catalog. We have a dynamic 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>
+}
+```
+
+If we run `next build`, this 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 not known at build time, so Next.js can't prerender the page. We 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.
+
+#### Debugging prerender errors
+
+If the error doesn't 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.
+
+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.
+
+### Step 1: 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 and prints the route table:
+
+```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
+```
+
+Each symbol tells you how a route is served:
+
+| 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. |
+
+The listed params are resolved ahead of time. Each one shows its own symbol — `○` if the page is fully static, or `◐` if it contains 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).
+
+### Step 2: Stream dynamic content with Suspense
+
+Sometimes you can't provide all param values ahead of time, or the page has 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/1
+│ ├ ◐ /products/2
+│ └ ◐ [+4 more paths]
+```
+
+The routes now show `◐` (Partial Prerender) because each page has a static shell with dynamic content that streams in at request time.
+
+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
+```
+
+This means you can keep `generateStaticParams` small and let traffic determine which additional pages get cached.
+
+### Next steps
+
+You now know how to read the build output, pre-render dynamic routes, and fix prerender errors.
+
+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                                                                                                                                                                        |