docs(cli): clarify that --debug-build-paths requires route group folders in paths (#92618)

<!-- CURSOR_AGENT_PR_BODY_BEGIN -->
### What?

Adds a note to the `--debug-build-paths` section of the CLI docs
clarifying that [route
groups](https://nextjs.org/docs/app/building-your-application/routing/route-groups)
must be included in file paths.

### Why?

When using `--debug-build-paths`, users need to include route group
folders (e.g., `(marketing)`) in the file paths they pass. This isn't
obvious from the existing documentation — route groups are stripped from
URLs at runtime but must be present in file paths for this CLI option to
work correctly.

Addresses feedback from a docs comment noting that "Route groups are
also necessary, should be inferred from file paths, but it is not
straightforward from reading this."

### How?

Added a "Good to know" callout with an example showing how to reference
a page inside a route group:

```bash
next build --debug-build-paths="app/(marketing)/about/page.tsx"
```

<!-- NEXT_JS_LLM_PR -->
<!-- CURSOR_AGENT_PR_BODY_END -->

[Slack
Thread](https://vercel.slack.com/archives/C07ND110MMF/p1775828588791049?thread_ts=1775828588.791049&cid=C07ND110MMF)

<div><a
href="https://cursor.com/agents/bc-3a58eac7-35a3-56ab-aff2-f4cf2dd1ca9b"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-web-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-web-light.png"><img
alt="Open in Web" width="114" height="28"
src="https://cursor.com/assets/images/open-in-web-dark.png"></picture></a>&nbsp;<a
href="https://cursor.com/background-agent?bcId=bc-3a58eac7-35a3-56ab-aff2-f4cf2dd1ca9b"><picture><source
media="(prefers-color-scheme: dark)"
srcset="https://cursor.com/assets/images/open-in-cursor-dark.png"><source
media="(prefers-color-scheme: light)"
srcset="https://cursor.com/assets/images/open-in-cursor-light.png"><img
alt="Open in Cursor" width="131" height="28"
src="https://cursor.com/assets/images/open-in-cursor-dark.png"></picture></a>&nbsp;</div>

---------

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: Joseph <[email protected]>
This commit is contained in:
Joseph
2026-04-12 14:13:46 +02:00
committed by GitHub
co-authored by Cursor Agent Joseph
parent cd07aa37ba
commit db0fdc30f6
@@ -308,6 +308,9 @@ next build --debug-build-paths="app/page.tsx"
# Build more than one route
next build --debug-build-paths="app/page.tsx,pages/index.tsx"
# Include route group folders in the path
next build --debug-build-paths="app/(marketing)/about/page.tsx"
# Use glob patterns
next build --debug-build-paths="app/**/page.tsx"
next build --debug-build-paths="pages/*.tsx"