fix: reuse session ID in external storage example (#1333)

* fix: fix logto configs url

* fix: reuse session ID in external storage example

The previous example generated a new UUID on every wrap() call.
This breaks RSC environments where cookies cannot be updated,
causing session loss when the cookie still contains the old ID.

Updated the MemorySessionWrapper example to store and reuse the
session ID from unwrap(), ensuring the cookie value remains stable
while external storage data can be updated.

* docs: clarify RSC token caching limitation with solutions

Expanded the tip about RSC not being able to persist refreshed tokens.
Added clear solutions: using client components with Server Actions,
or using external session storage with sessionWrapper.

Author: wangsijie

docs/quick-starts/framework/next-app-router/README.mdx

@@ -69,9 +69,14 @@ export default async function Home() {
 }
 ```
 
-:::tip
+:::tip[RSC token caching limitation]
+
+React Server Components cannot write cookies (Next.js limitation). While `getAccessTokenRSC` will still refresh expired tokens using the refresh token, the new access token won't be persisted to the session cookie. This means every RSC request may trigger a token refresh if the cached token has expired.
 
-HTTP does not allow setting cookies after streaming starts, `getAccessTokenRSC` cannot update the cookie value, so if the access token is refreshed, it won't be persisted in the session. It is recommended to use `getAccessToken` function in client side or route handlers.
+**Solutions:**
+
+1. **Use client components with Server Actions** - Call `getAccessToken` from a client component via Server Actions, which can update cookies.
+2. **Use external session storage** - Configure a `sessionWrapper` with Redis/KV storage. The cookie stores only a fixed session ID while token data lives in external storage, allowing RSC to persist refreshed tokens. See [Use external session storage](#use-external-session-storage) below.
 
 :::
 
@@ -96,9 +101,9 @@ export default async function Home() {
 }
 ```
 
-:::tip
+:::tip[RSC token caching limitation]
 
-HTTP does not allow setting cookies after streaming starts, `getOrganizationTokenRSC` cannot update the cookie value, so if the access token is refreshed, it won't be persisted in the session. It is recommended to use `getOrganizationToken` function in client side or route handlers.
+Same as `getAccessTokenRSC`, the refreshed organization token won't be persisted in RSC. See [solutions above](#fetch-access-token-for-the-api-resource).
 
 :::
 

docs/quick-starts/framework/next/_external-storage.mdx

@@ -18,9 +18,14 @@ import { type SessionWrapper, type SessionData } from '@logto/next';
 
 export class MemorySessionWrapper implements SessionWrapper {
   private readonly storage = new Map<string, unknown>();
+  private currentSessionId?: string;
 
   async wrap(data: unknown, _key: string): Promise<string> {
-    const sessionId = randomUUID();
+    // Reuse existing session ID if available, only generate new one for first-time users.
+    // This is important for environments where cookies cannot be updated (e.g. React Server Components),
+    // as the session ID in the cookie must remain stable while the data in external storage can be updated.
+    const sessionId = this.currentSessionId ?? randomUUID();
+    this.currentSessionId = sessionId;
     this.storage.set(sessionId, data);
     return sessionId;
   }
@@ -30,6 +35,8 @@ export class MemorySessionWrapper implements SessionWrapper {
       return {};
     }
 
+    // Store the session ID for potential reuse in wrap()
+    this.currentSessionId = value;
     const data = this.storage.get(value);
     return data ?? {};
   }