feat(nuxt): Parametrize SSR routes #16843

s1gr1d · 2025-07-08T14:01:14Z

Adds route parametrization to SSR server routes.

The parametrized route data is gathered during build time and saved in a virtual file (added with addTemplate) which can hand-over the data to be accessed during runtime.

The nuxt-3-min test (Nuxt 3.7) shows that the route parametrization does not work yet with this version. From Nuxt 3.9 onwards, it works. This is fine, as most people are on a more recent version anyways.

part of #16684

s1gr1d · 2025-07-08T15:29:14Z

I still need to look into why this is failing in nuxt-3-min. The pages:extend hook should already be available in version 3.7, but the hook is not called 🤔

packages/nuxt/src/runtime/plugins/route-detector.server.ts

AbhiPrasad · 2025-07-08T18:41:38Z

packages/nuxt/src/runtime/plugins/route-detector.server.ts

+      }
+
+      const method = ssrContext?.event?._method || 'GET';
+      const parametrizedTransactionName = `${method.toUpperCase()} ${routeInfo.parametrizedRoute}`;


m: We create the parametrizedTransactionName but don't update the span name?

oh that's left from before the last commit 😅
was using updateSpanName before, but I only need to set 'http.route': routeInfo.parametrizedRoute to update the name.

AbhiPrasad · 2025-07-08T18:42:04Z

packages/nuxt/src/runtime/utils/route-extraction.ts

+ * An array of NuxtPage objects representing the build-time pages data.
+ * Example: [{ name: 'some-path', path: '/some/path' }, { name: 'user-userId', path: '/user/:userId()' }]
+ */
+export function extractParametrizedRouteFromContext(


l: should we memoize this function?

Yeah the function is quite expensive as the lookup is hard :/

I added some general, small optimizations for the function.

Using the currentUrl is not possible as it includes the parameters and that would blow up.
And the only way to memoize the result is using the ssrContextModules as key (which is quite complex as this can be a large Set) and this Set has a different reference, every time a request is sent. So the key has to be created on every request, as I cannot use the Set itself as a key.

However, as I think the key generation regardless its overhead still makes sense, I added it now.

AbhiPrasad · 2025-07-08T18:49:45Z

packages/nuxt/src/module.ts

+    });
+
+    nuxt.hooks.hook('pages:extend', pages => {
+      pagesDataTemplate.getContents = () => `export default ${JSON.stringify(pages, null, 2)};`;


m: So stringifying all of the pages can get pretty big from what I can see in the NuxtPage type.

Perhaps we should just save a subset? We really only need the file and the path from looking at extractParametrizedRouteFromContext.

Good catch, I also filtered for only dynamic pages.

# Conflicts: # dev-packages/e2e-tests/test-applications/nuxt-3-dynamic-import/tests/tracing.test.ts # dev-packages/e2e-tests/test-applications/nuxt-3-min/tests/tracing.test.ts # dev-packages/e2e-tests/test-applications/nuxt-3-top-level-import/tests/tracing.test.ts # dev-packages/e2e-tests/test-applications/nuxt-3/tests/tracing.test.ts # dev-packages/e2e-tests/test-applications/nuxt-4/tests/tracing.test.ts

Lms24

Great work! Had some questions about our matching algorithm. IIUC we need a similar logic in Next and possibly other frameworks at some point. Might make sense to think about extracing this in the future because matching routes is far from trivial. But obviously this is a something to follow up on later :)

Lms24 · 2025-07-09T12:58:05Z

packages/nuxt/test/runtime/utils/route-extraction.ts

+            file: '/app/pages/test-param/[param].vue',
+          }),
+        ],
+        expected: { parametrizedRoute: '/test-param/:param()' },


l/q: what's the reason for the brackets in the parameters (:param_()_)? Is this a Nuxt routing covention/something users are used to?

This is how Nuxt lists parametrized routes - I would leave it like it is to not stumble into edge cases when modifying the route. But the convention is to use brackets [param] in the filename.

I think it's fine since we don't have a standard around how we format parameter path segments. I just haven't seen this in other frameworks before. thx for explaining

Lms24 · 2025-07-09T13:02:03Z

packages/nuxt/test/runtime/utils/route-extraction.ts

+  });
+
+  describe('multiple routes matching', () => {
+    it('should find the correct route when multiple routes exist', () => {


sticking with this example: If I have two routes,

file: '/app/pages/test-param/user/[userId].vue', file: '/app/pages/test-param/user/abc.vue',

do we still correctly identify the respective routes for urls /test-param/user/123 and /test-param/user/abc?

(Sorry in case I missed such an example in already existing tests. If not, it might be a good test case)

Related but not also rather a question: Does this handle catch-all routes?

Both of that should work - I would add those two cases in another PR as I don't have tests for that yet and that would blow up the PR :D

Test follow-up for this PR: #16843 Re-organizes the unit tests a bit to be less repetitive with default data that is aligned to real-world examples. --- Adds unit tests for cases mentioned [here](#16843 (comment)): - differentiate dynamic vs static route on the same path (`users/:id` vs `users/settings`) - cases for catch-all routes

s1gr1d added 3 commits July 8, 2025 16:05

add test for distributed client-side API request

e740361

Standardize test case

3b4a57c

feat(nuxt): Parametrize SSR routes

8492c82

s1gr1d force-pushed the sig/param-routes-nuxt-ssr branch from ea09c04 to 8492c82 Compare July 8, 2025 14:06

s1gr1d requested review from mydea, Lms24, chargome, andreiborza and AbhiPrasad July 8, 2025 14:07

fix tests

a215c8c

This comment was marked as outdated.

Sign in to view

remove updateSpanName

6999a67

This comment was marked as outdated.

Sign in to view

AbhiPrasad reviewed Jul 8, 2025

View reviewed changes

s1gr1d added 4 commits July 9, 2025 09:19

review suggestions

b13dfdb

refactor to make it better readable

ef90f2a

filter for dynamic params during build

b3bbf0c

s1gr1d force-pushed the sig/param-routes-nuxt-ssr branch from 9aff99a to b3bbf0c Compare July 9, 2025 10:32

This comment was marked as outdated.

Sign in to view

s1gr1d added 4 commits July 9, 2025 12:45

modify tests for nuxt-3-min

5614e30

add cache mechanism

02d60e1

move and rename test file

d392ec5

add/remove logs

8bf9820

Lms24 reviewed Jul 9, 2025

View reviewed changes

s1gr1d requested review from AbhiPrasad and Lms24 July 9, 2025 14:25

Lms24 approved these changes Jul 9, 2025

View reviewed changes

s1gr1d merged commit 5534ba9 into develop Jul 10, 2025
324 of 329 checks passed

s1gr1d deleted the sig/param-routes-nuxt-ssr branch July 10, 2025 08:23

This was referenced Jul 10, 2025

Implement parametrized routes for Nuxt server #16684

Closed

test(nuxt): Add unit tests for catch-all routes #16891

Merged

Uh oh!

feat(nuxt): Parametrize SSR routes #16843

feat(nuxt): Parametrize SSR routes #16843

Uh oh!

Conversation

s1gr1d commented Jul 8, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment was marked as outdated.

Uh oh!

This comment was marked as outdated.

Uh oh!

s1gr1d commented Jul 8, 2025

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

s1gr1d Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

Lms24 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Lms24 Jul 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

s1gr1d commented Jul 8, 2025 •

edited

Loading

s1gr1d Jul 9, 2025 •

edited

Loading

Lms24 Jul 9, 2025 •

edited

Loading