apply code review suggestions

Author: alexisintech

docs/_partials/metadata-callout.mdx

@@ -1,4 +1,4 @@
 > [!WARNING]
 > Metadata is limited to **8KB** maximum. If you're storing metadata as a custom claim in the session token, it's highly recommended to keep it under **1.2KB**. [Learn more about the session token size limitations](/docs/backend-requests/resources/session-tokens#size-limitations).
 >
-> If you use Clerk metadata and modify it server-side, the changes won't appear in the session token until the next refresh. To avoid race conditions, either force a JWT refresh after metadata changes or handle the delay in your application logic.
+> If you use Clerk metadata and modify it server-side, the changes won't appear in the session token until the next refresh. To avoid race conditions, either [force a JWT refresh](/docs/guides/force-token-refresh) after metadata changes or handle the delay in your application logic.

docs/_partials/token-size-callout.mdx

@@ -1,2 +1,2 @@
 > [!CAUTION]
-> **It's recommended to keep the total size of custom claims in the session token under 1.2KB.** Exceeding this size can have adverse effects, such as possible infinite redirect loops in Next.js applications. It's recommended to move particularly large claims out of the JWT and fetch these using a separate API call from your backend. [Learn more](/docs/backend-requests/resources/session-tokens#size-limitations).
+> Clerk stores the session token in a cookie, and most browsers cap cookie size at [**4KB**](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). After accounting for the size of Clerk's default claims, the cookie can support **up to 1.2KB** of custom claims. Exceeding this limit will cause the cookie to not be set, which will break your app as Clerk depends on cookies to work properly. [Learn more](/docs/backend-requests/resources/session-tokens#size-limitations).

docs/backend-requests/custom-session-token.mdx

@@ -17,22 +17,20 @@ This guide will show you how to customize a session token to include additional
   1. In the Clerk Dashboard, navigate to the [**Sessions**](https://dashboard.clerk.com/last-active?path=sessions) page.
   1. Under **Customize session token**, in the **Claims** editor, you can add any claim to your session token that you need and select **Save**.
 
-  The following example adds the `metadata` claim to the session token.
+  The following example adds the `fullName` and `primaryEmail` claims to the session token.
 
   ![Clerk Dashboard showing the custom claim modal](/docs/images/custom-session-token/example.png)
 
   ## Use the custom claims in your application
 
   The [`Auth`](/docs/references/backend/types/auth-object) object includes a `sessionClaims` property that contains the custom claims you added to your session token. Accessing the `Auth` object differs depending on the framework you are using. See the [reference doc](/docs/references/backend/types/auth-object) for more information.
 
-  The following example demonstrates how to access the `metadata` claim that was added to the session token in the last step.
+  The following example demonstrates how to access the `fullName` and `primaryEmail` claims that were added to the session token in the last step.
 
   <Tabs items={["Next.js", "Astro", "Express", "Go", "React Router", "Remix", "Tanstack React Start"]}>
     <Tab>
       For Next.js, the `Auth` object is accessed using the `auth()` helper in App Router apps and the `getAuth()` function in Pages Router apps. [Learn more about using these helpers](/docs/references/nextjs/read-session-data#server-side).
 
-      Use the following tabs to see examples of how to use these helpers to access the user's ID in your App Router or Pages Router app.
-
       <CodeBlockTabs options={["App Router", "Pages Router"]}>
         ```tsx {{ filename: 'app/api/example/route.tsx' }}
         import { auth } from '@clerk/nextjs/server'
@@ -41,9 +39,11 @@ This guide will show you how to customize a session token to include additional
         export async function GET() {
           const { sessionClaims } = await auth()
 
-          const metadata = sessionClaims?.metadata
+          const fullName = sessionClaims.fullName
+
+          const primaryEmail = sessionClaims.primaryEmail
 
-          return NextResponse.json({ metadata })
+          return NextResponse.json({ fullName, primaryEmail })
         }
         ```
 
@@ -55,9 +55,11 @@ This guide will show you how to customize a session token to include additional
           // Use `getAuth()` to get the user's ID and session claims
           const { sessionClaims } = getAuth(req)
 
-          const metadata = sessionClaims.metadata
+          const fullName = sessionClaims.fullName
 
-          return res.status(200).json({ metadata })
+          const primaryEmail = sessionClaims.primaryEmail
+
+          return res.status(200).json({ fullName, primaryEmail })
         }
         ```
       </CodeBlockTabs>
@@ -78,9 +80,11 @@ This guide will show you how to customize a session token to include additional
           return new Response('Unauthorized', { status: 401 })
         }
 
-        const metadata = sessionClaims.metadata
+        const fullName = sessionClaims.fullName
+
+        const primaryEmail = sessionClaims.primaryEmail
 
-        return new Response(JSON.stringify({ metadata }))
+        return new Response(JSON.stringify({ fullName, primaryEmail }))
       }
       ```
     </Tab>
@@ -102,9 +106,11 @@ This guide will show you how to customize a session token to include additional
       const getSessionClaims = (req, res, next) => {
         const { sessionClaims } = getAuth(req)
 
-        const metadata = sessionClaims.metadata
+        const fullName = sessionClaims.fullName
 
-        return res.status(200).json({ metadata })
+        const primaryEmail = sessionClaims.primaryEmail
+
+        return res.status(200).json({ fullName, primaryEmail })
       }
 
       app.get('/profile', requireAuth(), getSessionClaims)
@@ -133,7 +139,8 @@ This guide will show you how to customize a session token to include additional
       )
 
       type CustomSessionClaims struct {
-         metadata string  `json:"metadata"`
+         FullName string  `json:"fullName"`
+         PrimaryEmail string `json:"primaryEmail"`
       }
 
       func customClaimsConstructor(ctx context.Context) any {
@@ -172,7 +179,7 @@ This guide will show you how to customize a session token to include additional
         if !ok {
           // Handle the error how you see fit
         } else {
-          fmt.Fprintf(w, `{"public_metadata": "%s"}`, customClaims.metadata)
+          fmt.Fprintf(w, `{"full_name": "%s", "primary_email": "%s"}`, customClaims.FullName, customClaims.PrimaryEmail)
         }
       }
       ```
@@ -196,19 +203,21 @@ This guide will show you how to customize a session token to include additional
           return redirect('/sign-in?redirect_url=' + args.request.url)
         }
 
-        const metadata = sessionClaims.metadata
+        const fullName = sessionClaims.fullName
+
+        const primaryEmail = sessionClaims.primaryEmail
 
         return {
-          metadata,
+          fullName: JSON.stringify(fullName),
+          primaryEmail: JSON.stringify(primaryEmail),
         }
       }
 
       export default function Profile({ loaderData }: Route.ComponentProps) {
         return (
           <div>
-            <p>
-              Welcome {userId}, your public metadata is {loaderData.metadata}
-            </p>
+            <p>Welcome {loaderData.fullName}</p>
+            <p>Your email is {loaderData.primaryEmail}</p>
           </div>
         )
       }
@@ -232,9 +241,11 @@ This guide will show you how to customize a session token to include additional
           return redirect('/sign-in?redirect_url=' + args.request.url)
         }
 
-        const metadata = sessionClaims.metadata
+        const fullName = sessionClaims.fullName
 
-        return { metadata }
+        const primaryEmail = sessionClaims.primaryEmail
+
+        return { fullName, primaryEmail }
       }
       ```
     </Tab>
@@ -257,9 +268,11 @@ This guide will show you how to customize a session token to include additional
             return json({ error: 'Unauthorized' }, { status: 401 })
           }
 
-          const metadata = sessionClaims.metadata
+          const fullName = sessionClaims.fullName
+
+          const primaryEmail = sessionClaims.primaryEmail
 
-          return json({ metadata })
+          return json({ fullName, primaryEmail })
         },
       })
       ```
@@ -275,14 +288,15 @@ This guide will show you how to customize a session token to include additional
   1. Create the `CustomJwtSessionClaims` interface and declare it globally.
   1. Add the custom claims to the `CustomJwtSessionClaims` interface.
 
-  The following example demonstrates how to add the `metadata` claim to the `CustomJwtSessionClaims` interface.
+  The following example demonstrates how to add the `fullName` and `primaryEmail` claims to the `CustomJwtSessionClaims` interface.
 
   ```tsx {{ filename: 'types/globals.d.ts' }}
   export {}
 
   declare global {
     interface CustomJwtSessionClaims {
-      metadata: string
+      fullName?: string
+      primaryEmail?: string
     }
   }
   ```

docs/backend-requests/resources/session-tokens.mdx

@@ -98,9 +98,9 @@ You can also create custom tokens using a [JWT template](/docs/backend-requests/
 
 ## Size limitations
 
-The Clerk session token is stored in a cookie. All modern browsers [limit the maximum size of a cookie to **4KB**](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). Exceeding this limit can have adverse effects, such as possible infinite redirect loops in Next.js applications.
+Clerk stores the session token in a cookie, and [**most browsers limit cookie size to 4KB**](https://datatracker.ietf.org/doc/html/rfc2109#section-6.3). Exceeding this limit will cause the cookie to not be set, which will break your app as Clerk depends on cookies to work properly.
 
-A session token with the [default session claims](#default-claims) won't run into this issue, as this configuration produces a cookie significantly smaller than 4KB. However, this limitation becomes relevant when implementing a [custom session token](/docs/backend-requests/custom-session-token). **It's recommended to keep the total size of custom claims in the session token under 1.2KB.**
+A session token with the [default session claims](#default-claims) won't run into this issue, as this configuration produces a cookie significantly smaller than 4KB. However, you must consider this limit when implementing a [custom session token](/docs/backend-requests/custom-session-token). After accounting for the size of Clerk's default claims, the cookie can support **up to 1.2KB** of custom claims.
 
 Claims to monitor for size limits:
 
@@ -110,14 +110,14 @@ Claims to monitor for size limits:
 - `org.public_metadata`
 - `org_membership.public_metadata`
 
-If you add any of these custom claims in your token, use caution to ensure the stored data doesn't exceed the size limit. It's recommended to [move particularly large claims like these out of the token](#example) and fetch them using a separate API call from your backend.
+If you add any of these custom claims in your token, use caution to ensure the stored data doesn't exceed the size limit. It's highly recommended to [store the extra data in your own database](/docs/webhooks/sync-data#storing-extra-user-data) instead of storing it in metadata in the session token. If this isn't an option, you can [move particularly large claims like these out of the token](#example) and fetch them using a separate API call from your backend.
 
 > [!NOTE]
 > If your application encounters this issue, the Clerk Dashboard will display a warning: **"Some users are exceeding cookie size limits"**. To resolve this, update your [custom session token](/docs/backend-requests/custom-session-token).
 
 ### Example
 
-It's recommended to keep the total size of custom claims in the session token under 1.2KB. Move particularly large claims out of the session token and fetch them using a separate API call from your backend.
+It's recommended to keep the total size of custom claims in the session token under 1.2KB. The following example shows how to move particularly large claims out of the session token and fetch them using a separate API call from your backend. The limitations of this approach are that if you make this call to Clerk's Backend API frequently, you risk hitting [rate limits](/docs/backend-requests/resources/rate-limits) and it's also slower than making a database query. We highly recommend [storing the extra data in your own database](/docs/webhooks/sync-data#storing-extra-user-data) instead of storing it in metadata in the session token.
 
 For example, if you were storing several fields in `user.public_metadata`, like this:
 
@@ -343,8 +343,6 @@ If you need to access the other fields, you can fetch them using a separate API
   </Tab>
 </Tabs>
 
-However, if you make this call to Clerk's Backend API frequently, you risk hitting [rate limits](/docs/backend-requests/resources/rate-limits) and it's also slower than making a database query. So it's recommended to [store the extra data in your own database](/docs/webhooks/sync-data#storing-extra-user-data) instead of storing it in metadata in the session token.
-
 ## Validate session tokens
 
 If you're using the middleware provided by our Clerk SDKs, validating session tokens is handled automatically in every request. If you're not using the middleware, you can still use the respective helpers provided by the SDKs to validate the tokens.