feat: improve vercel query param handling

[Alex--C]

🔗 Linked issue

#1880

❓ 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

When using ISR on Vercel, you can define which query params should be considered for the cache using the allowQuery key in the .prerender-config.json files. This is documented in the Build API docs:

List of query string parameter names that will be cached independently. If an empty array, query values are not considered for caching. If undefined each unique query value is cached independently

Nitro by default sets this to ["url"] for catch-all routes (/**). This PR allows defining a custom allowQuery configuration for each routeRule. It ensures that "url" is always allowed for catch-all routes, except when the route explicitly sets allowQuery to undefined to allow all params.

Additionally, we add support for Vercel's passQuery param.

When true, the query string will be present on the request argument passed to the invoked function. The allowQuery filter still applies.

This is especially useful for cacheable server routes that need to access the request's query params.

As an example, this configuration would ensure that each query parameter is cached independently on all routes, and allows the API endpoint to access the query params.

  routeRules: {
    '/**': {
      isr: true,
      allowQuery: undefined
    },
    '/api/test-endpoint': {
      isr: true,
      passQuery: true
    }
  },

If you consider merging this change, I will happily add some documentation for it in the vercel section. Let me know what you think.

📝 Checklist

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

[pi0]

Since this is a vercel-specific route rule, we might need to namespace them to as vercel?: {}

[pi0]

Are there any docs that mention url is conventional or has a specific use case to be supported by default?

[Alex--C]

As far as I understand (the url default was there before my change and I'm pretty new to this Vercel stuff), this is necessary for catch-all routes to work at all. Otherwise each route that ends up in the catch-all would return the same cached html. The url param is set here:

nitro/src/presets/vercel.ts

Line 238 in 3a69dd7

: generateEndpoint(key) + "?url=$url",

In that sense I would say that this is not "conventional", but rather a nitro-specific thing to make catch-all routes work.