feat: rewrite redirects sent through the proxy

[mattmess1221]

🔗 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

Rewrite redirects if for some reason an API uses them.

• Absolute and same-origin locations will be rewritten.
  • Locations to outside the endpoint's URL path are unsupported and will cause a Server Error.
• Relative and cross-origin locations will not be rewritten.

Also moves the config template typing to a static .d.ts file with module declarations, as it was the best way to add typing for server templates.

📝 Checklist

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

[Copilot]

Pull request overview

This PR adds support for rewriting redirect responses when proxying API requests, ensuring redirects are properly handled in both SSR and client-side contexts. The feature is controlled by a new experimental configuration option rewriteProxyRedirects (enabled by default).

Key changes:

• Implements redirect rewriting logic for proxied requests, handling relative, absolute, and same-origin redirects
• Adds configuration option to enable/disable the feature
• Includes test coverage for various redirect scenarios

Reviewed changes

Copilot reviewed 8 out of 9 changed files in this pull request and generated 3 comments.

Show a summary per file

File	Description
src/runtime/server/proxyHandler.ts	Core implementation of redirect rewriting logic with helper functions
src/module.ts	Adds configuration option and server template for the feature
test/fixture/server/api/redirect.get.ts	Test fixture for various redirect scenarios
test/e2e-proxy.test.ts	E2E tests validating redirect rewriting behavior
src/runtime/server/handler.ts	Adds header to track redirected responses
playground/server/api/custom/redirect.ts	Playground endpoint for testing redirects
playground/server/api/custom/echo.ts	Playground endpoint for testing requests
playground/nuxt.config.ts	Adds custom endpoint to playground configuration

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[mattmess1221]

Turns out addTemplate forces write = true when the filename ends in .d.ts lol

[johannschopplich]

Hey! Thanks so much for putting this PR together and thinking about edge cases in the proxy behavior. I really appreciate the effort you've put into this. 🙏

I've been thinking about the PR… and I'm questioning whether it adds enough value to justify the added complexity. Redirect rewriting for API responses is solving an uncommon edge case and inflates the scope of the module. Users who need custom redirect handling can already implement it using the existing Nitro server hooks api-party:response (which was a great PR by you, by the way!).

I'd rather not bake this this behavior into into the module. If there's strong demand or compelling use cases I'm missing, I'm happy to reconsider. What do you think?

[mattmess1221]

I can try to reduce the scope to only allow setting redirect: 'manual' | 'error' | 'follow' or only support non-absolute redirects. Though I think the former is still possible via hooks. I'll have to think about which one is more beneficial.

[mattmess1221]

I managed to implement this as a plugin.

Since response.headers is readonly, I had to workaround the location header being overwritten by manually setting the status code then call event.node.res.end().

I'll probably make a docs PR later to add my solution as an example on how to handle redirects.

[johannschopplich]

Thank you!

[mattmess1221]

I've shared the plugin implementation as a discussion #142