feat: add client-only load strategy (#443)

Co-authored-by: Sébastien Chopin <seb@nuxt.com>
Co-authored-by: autofix-ci[bot] <114827586+autofix-ci[bot]@users.noreply.github.com>
Co-authored-by: Sébastien Chopin <atinux@gmail.com>

Author: 3 people

README.md

@@ -600,6 +600,18 @@ This is because the user session is stored in a secure cookie and cannot be acce
 
 **This means that you should not rely on the user session during prerendering.**
 
+You may also choose to instruct Nuxt AUth Utils to fetch the user session only on the client side, with the `loadStrategy` option in your `nuxt.config.ts`:
+
+```ts
+export default defineNuxtConfig({
+  auth: {
+    loadStrategy: 'client-only'
+  }
+})
+```
+
+When using the `client-only` load strategy, the user session can still be manually fetched on the server side by calling `fetch` from the `useUserSession` composable.
+
 ### `<AuthState>` component
 
 You can use the `<AuthState>` component to safely display auth-related data in your components without worrying about the rendering mode.
@@ -617,7 +629,7 @@ One common use case if the Login button in the header:
 </template>
 ```
 
-If the page is cached or prerendered, nothing will be rendered until the user session is fetched on the client-side.
+If the page is cached or prerendered or the load strategy set as `client-only`, nothing will be rendered until the user session is fetched on the client-side.
 
 You can use the `placeholder` slot to show a placeholder on server-side and while the user session is being fetched on client-side for the prerendered pages:
 

playground/nuxt.config.ts

@@ -1,7 +1,7 @@
 export default defineNuxtConfig({
   // ssr: false,
   extends: ['@nuxt/ui-pro'],
-  modules: ['nuxt-auth-utils', '@nuxt/ui', '@vueuse/nuxt'],
+  modules: ['../src/module', '@nuxt/ui', '@vueuse/nuxt'],
   imports: {
     autoImport: true,
   },
@@ -26,6 +26,7 @@ export default defineNuxtConfig({
   auth: {
     webAuthn: true,
     atproto: true,
+    // loadStrategy: 'client-only'
   },
   icon: {
     customCollections: [{

playground/package.json

@@ -17,8 +17,5 @@
     "nuxt": "^3.15.4",
     "nuxt-auth-utils": "latest",
     "zod": "^3.24.1"
-  },
-  "devDependencies": {
-    "better-sqlite3": "^11.8.1"
   }
 }

pnpm-lock.yaml

@@ -1,3 +1,3 @@
 packages:
-  - "playground"
-  - "./"
+  - ./
+  - ./playground

pnpm-workspace.yaml

@@ -39,6 +39,11 @@ export interface ModuleOptions {
      */
     scrypt?: ScryptConfig
   }
+  /**
+   * Session load strategy
+   * @default 'server-first'
+   */
+  loadStrategy?: 'server-first' | 'client-only'
 }
 
 declare module 'nuxt/schema' {
@@ -51,6 +56,12 @@ declare module 'nuxt/schema' {
      */
     session: SessionConfig
   }
+
+  interface PublicRuntimeConfig {
+    auth: {
+      loadStrategy: 'server-first' | 'client-only'
+    }
+  }
 }
 
 export default defineNuxtModule<ModuleOptions>({
@@ -65,6 +76,7 @@ export default defineNuxtModule<ModuleOptions>({
     hash: {
       scrypt: {},
     },
+    loadStrategy: 'server-first',
   },
   async setup(options, nuxt) {
     const resolver = createResolver(import.meta.url)
@@ -122,8 +134,11 @@ export default defineNuxtModule<ModuleOptions>({
     })
     // Set node:crypto as unenv external
     nuxt.options.nitro.unenv ||= {}
+    // @ts-expect-error we can use external as array
     nuxt.options.nitro.unenv.external ||= []
+    // @ts-expect-error see comment above
     if (!nuxt.options.nitro.unenv.external.includes('node:crypto')) {
+    // @ts-expect-error see comment above
       nuxt.options.nitro.unenv.external.push('node:crypto')
     }
 
@@ -162,6 +177,11 @@ export default defineNuxtModule<ModuleOptions>({
       }
     }
 
+    // Load strategy
+    runtimeConfig.public.auth = defu(runtimeConfig.public.auth, {
+      loadStrategy: options.loadStrategy ?? 'server-first',
+    })
+
     // WebAuthn settings
     runtimeConfig.webauthn = defu(runtimeConfig.webauthn, {
       register: {},

src/module.ts

@@ -6,7 +6,9 @@ export default defineNuxtPlugin(async (nuxtApp) => {
   if (!nuxtApp.payload.serverRendered) {
     await useUserSession().fetch()
   }
-  else if (Boolean(nuxtApp.payload.prerenderedAt) || Boolean(nuxtApp.payload.isCached)) {
+  else if (Boolean(nuxtApp.payload.prerenderedAt) || Boolean(nuxtApp.payload.isCached)
+    || nuxtApp.$config.public.auth.loadStrategy === 'client-only'
+  ) {
     // To avoid hydration mismatch
     nuxtApp.hook('app:mounted', async () => {
       await useUserSession().fetch()

src/runtime/app/plugins/session.client.ts

@@ -8,7 +8,9 @@ export default defineNuxtPlugin({
   async setup(nuxtApp) {
     // Flag if request is cached
     nuxtApp.payload.isCached = Boolean(useRequestEvent()?.context.cache)
-    if (nuxtApp.payload.serverRendered && !nuxtApp.payload.prerenderedAt && !nuxtApp.payload.isCached) {
+    if (nuxtApp.payload.serverRendered && !nuxtApp.payload.prerenderedAt && !nuxtApp.payload.isCached
+      && nuxtApp.$config.public.auth.loadStrategy !== 'client-only'
+    ) {
       await useUserSession().fetch()
     }
   },

src/runtime/app/plugins/session.server.ts

@@ -27,7 +27,7 @@ export interface OAuthAuthentikConfig {
    * Redirect URL to allow overriding for situations like prod failing to determine public hostname
    * @default process.env.NUXT_OAUTH_AUTHENTIK_REDIRECT_URL or current URL
    */
-  redirectURL?: string,
+  redirectURL?: string
 
   /**
    * Authentik Scope

src/runtime/server/lib/oauth/authentik.ts

@@ -31,7 +31,7 @@ export async function getUserSession(event: UseSessionEvent): Promise<UserSessio
   const session = await _useSession(event)
   return {
     ...session.data,
-    id: session.id,
+    id: session.id!,
   }
 }
 /**