fix(dev): proxy subpaths for devProxy rules

[danielroe]

🔗 Linked issue

❓ Type of change

• 📖 Documentation (updates to the documentation, readme, or JSdoc annotations)
• 🐞 Bug fix (a non-breaking change that fixes an issue)
• 👌 Enhancement (improving an existing functionality like performance)
• ✨ New feature (a non-breaking change that adds functionality)
• 🧹 Chore (updates to the build process or auxiliary tools and libraries)
• ⚠️ Breaking change (fix or feature that would cause existing functionality to change)

📚 Description

noticed this when trying to reproduce a bug on nuxt/cli:

on v2 a single devProxy rule proxies the whole prefix, but on v3 only the exact route (and its trailing-slash form) is proxied; every subpath falls through to the app.

 export default defineConfig({
   serverDir: './server',
   devProxy: {
     '/proxy': { target: 'http://localhost:8080' },
   },
 })

hitting /proxy works with v2 (target sees '/') and v3 (target sees '/proxy') but in v3 hitting /proxy/foo/bar?x=1 doesn't work - it 404s...

this is an attempt to resolve but you may have a different approach - or maybe you want to move into routerules (?)

📝 Checklist

• I have linked an issue or discussion.
• I have updated the documentation accordingly.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nitro.build	Ready	Preview, Comment	Jul 25, 2026 9:50am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 6af2ab36-23b5-4c1d-8820-10ab20b8d0f6

📥 Commits

Reviewing files that changed from the base of the PR and between 77b77ff and 6128fca.

📒 Files selected for processing (2)

• src/dev/app.ts
• test/unit/dev-proxy.test.ts

---

📝 Walkthrough

Walkthrough

Dev proxy route handling now normalizes configured prefixes, forwards requests with the matched base removed, restores the original pathname, and adds integration coverage for exact, wildcard, trailing-slash, nested, query-string, and non-matching routes.

Changes

Dev proxy routing

Layer / File(s)	Summary
Normalize proxy route forwarding src/dev/app.ts	Dev proxy handlers use normalized wildcard prefixes, temporarily strip the matched base path, and restore the original pathname after forwarding.
Validate proxy path variants test/unit/dev-proxy.test.ts	Tests verify exact, nested, wildcard, trailing-slash, query-string, and sibling-route behavior against a local target server.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Possibly related PRs

• nitrojs/nitro#4480: Updates the same dev proxy wiring for WebSocket upgrade path matching.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title follows conventional commit format and clearly describes the devProxy subpath fix.
Description check	✅ Passed	The description directly explains the devProxy bug, the observed behavior, and the intended fix.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch fix/devproxy-subpath

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/nitro@4481

commit: 6128fca

[pi0]

I think this is a correct (breaking change) that /proxy matches /proxy while /proxy/** anything nested nitro v2 behavior was consequence of following connect middleware

[danielroe]

so we should tell people to set /proxy/** when they intend to proxy all subpaths?