Draft
Conversation
New guide covering next build output, generateStaticParams, and prerender error debugging (--debug-prerender). Consolidates context scattered across API references and error pages into a single progressive walkthrough. Ref: DOC-4946 Made-with: Cursor
nextjs-bot
added
created-by: Next.js DevEx team
Contributor
|
Hi there 👋 It looks like this PR introduces broken links to the docs, please take a moment to fix them before merging:
Thank you 🙏 |
Remove ƒ (Dynamic) from symbols table since Cache Components always produces ○ or ◐. Use actual error message text and explain the blocking behavior using language from the blocking-route error page. Made-with: Cursor
icyJoseph
reviewed
Apr 8, 2026
Extend Step 2 with guidance on experimental.partialFallbacks for sites that can't pre-render every slug. Covers instant fallback shells for unknown slugs and automatic upgrade after first visit. Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Better fit as a focused guide rather than a getting-started page. Restores deploying/upgrading to their original numbering (17/18). Made-with: Cursor
…guide Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
aurorascharff
changed the title
Made-with: Cursor
Made-with: Cursor
Flip the flow: start with the base case that fails, fix with generateStaticParams (Step 1), then fix with Suspense (Step 2). Build output symbols are introduced naturally when the build succeeds. Made-with: Cursor
Explains why the build fails before showing the error, so readers have context. Removes duplicate explanation from Step 1. Made-with: Cursor
Made-with: Cursor
Link from the caching getting-started page (build output mention) and the CLI reference (next build section). Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
Made-with: Cursor
aurorascharff
commented
Apr 8, 2026
aurorascharff
commented
Apr 8, 2026
|
|
||
| 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. |
Contributor
There was a problem hiding this comment.
Pull request overview
Adds a new App Router guide documenting what happens during next build, how to interpret route output symbols (especially with Cache Components / PPR), and how to debug common prerender failures. It also adds cross-links from existing CLI and getting-started docs to direct readers to the new guide.
Changes:
- Add a new “Building your application” guide covering build phases, output interpretation, and prerender error debugging.
- Link to the new guide from the
next buildCLI reference and from getting-started “Installation” and “Deploying” pages.
Reviewed changes
Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
| docs/01-app/03-api-reference/06-cli/next.mdx | Links next build readers to the new Building guide for deeper output/debugging details. |
| docs/01-app/02-guides/building.mdx | New guide explaining next build phases, output symbols, generateStaticParams, Suspense/PPR, and debugging flags. |
| docs/01-app/01-getting-started/17-deploying.mdx | Adds a contextual link from build/start instructions to the Building guide. |
| docs/01-app/01-getting-started/01-installation.mdx | Adds a “ready for production” note linking to the Building guide and Deploying docs. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
icyJoseph
reviewed
Apr 8, 2026
Co-authored-by: Joseph <joseph.chamochumbi@vercel.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds a new Building guide (
docs/01-app/02-guides/building.mdx) that covers what happens when you runnext buildand how to work with the output.Sections
next builddoes — high-level overview of the build phases (setup, route discovery, compilation, static analysis, prerendering, output)○Static,◐Partial Prerender) and what they mean with Cache ComponentsgenerateStaticParams, how listed/unlisted params behave, andpartialFallbacksfor high-cardinality sites<Suspense>/loading.jsfix,--debug-prerenderfor stack traces,--debug-build-pathsfor building specific routesRelated: #92382
Closes: https://linear.app/vercel/issue/DOC-4946/getting-started-building