feat: opt routes out of the SSR user write via routeRules

[frederikprijck]

Summary

Adds a per-route (and global) opt-out for the SSR user write, addressing point 3 of #52 ("config to disable / route-scope the global middleware").

This lets a consumer opt a route (or pattern, or everything) out of the SSR user write:

// nuxt.config.ts
routeRules: {
  '/public/**': { auth0: { ssrUser: false } }, // per route / pattern
  // '/**': { auth0: { ssrUser: false } },      // global
}

On a route with auth0: { ssrUser: false }, the middleware skips the user write even when the route is not shared-cacheable; the user is hydrated client-side from the profile endpoint instead (same path the cache guard already uses).

Why this design

• Middleware stays global: true, so it always runs and always sees the route rules; only the write is gated. (Notably, Nuxt's native appMiddleware: { auth0: false } route rule does not work here — appMiddleware can only remove named middleware, not a global one. An e2e test was written that demonstrated this, which is why the opt-out is implemented as an explicit rule the middleware reads.)
• No fragile codegen. NitroRouteConfig is a closed interface, so a custom route-rule key needs a type augmentation. We ship an internal .d.ts so this repo's sources/fixtures typecheck, and document a copy-paste augmentation snippet for consumers who type-check their nuxt.config — rather than generating types at build time.

Tests

• Middleware unit tests: skips the write on ssrUser: false, writes on ssrUser: true.
• e2e (caching.test.ts): a non-cacheable /opted-out route with auth0: { ssrUser: false } renders anonymous SSR HTML (no sub/email in the payload), proving the opt-out works independently of the cache guard.
• Full unit suite (66) + lint + build green.

Merge order

Based on issue-52 because it builds on that branch's client-hydration plugin and profile endpoint.

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: f527e56f-51ae-4ba8-bcca-e77dd02b143a

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/disable-ssr-middleware

---

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.}