From ea6c1f1bbef42e150d304bc481aa5cbd8f7fb454 Mon Sep 17 00:00:00 2001
From: clockwork-labs-bot <clockwork-labs-bot@users.noreply.github.com>
Date: Sun, 15 Feb 2026 17:20:57 -0500
Subject: [PATCH] Store auth tokens per server/database in localStorage

Use a localStorage key that includes the server URI and database name
(`${HOST}/${DB_NAME}/auth_token`) so that different servers and modules
don't overwrite each other's tokens.

Applied to all templates (react, vue, svelte, nuxt, nextjs, remix,
tanstack, chat-react) and updated docs (tutorial, quickstarts,
connection reference).

Also fixes withModuleName -> withDatabaseName in nuxt, nextjs, remix,
and tanstack templates.

Closes #3252
---
 .../docs/00100-intro/00200-quickstarts/00155-nuxt.md |  7 ++++---
 .../00100-intro/00200-quickstarts/00180-browser.md   | 12 ++++++++----
 .../00100-intro/00300-tutorials/00100-chat-app.md    | 12 ++++++++----
 .../00600-client-sdk-languages/00300-connection.md   | 12 ++++++++----
 templates/chat-react-ts/src/App.integration.test.tsx |  6 +++++-
 templates/chat-react-ts/src/main.tsx                 |  5 +++--
 templates/nextjs-ts/app/providers.tsx                |  7 ++++---
 templates/nuxt-ts/app.vue                            |  7 ++++---
 templates/react-ts/src/main.tsx                      |  5 +++--
 templates/remix-ts/app/root.tsx                      |  7 ++++---
 templates/svelte-ts/src/Root.svelte                  |  5 +++--
 templates/tanstack-ts/src/router.tsx                 |  7 ++++---
 templates/vue-ts/src/main.ts                         |  5 +++--
 13 files changed, 61 insertions(+), 36 deletions(-)

diff --git a/docs/docs/00100-intro/00200-quickstarts/00155-nuxt.md b/docs/docs/00100-intro/00200-quickstarts/00155-nuxt.md
index 1dc8e7dadf8..dc8065d68fe 100644
--- a/docs/docs/00100-intro/00200-quickstarts/00155-nuxt.md
+++ b/docs/docs/00100-intro/00200-quickstarts/00155-nuxt.md
@@ -185,14 +185,15 @@ import { DbConnection } from './module_bindings';
 
 const HOST = import.meta.env.VITE_SPACETIMEDB_HOST ?? 'ws://localhost:3000';
 const DB_NAME = import.meta.env.VITE_SPACETIMEDB_DB_NAME ?? 'nuxt-ts';
+const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
 
 const connectionBuilder = import.meta.client
   ? DbConnection.builder()
       .withUri(HOST)
-      .withModuleName(DB_NAME)
-      .withToken(localStorage.getItem('auth_token') || undefined)
+      .withDatabaseName(DB_NAME)
+      .withToken(localStorage.getItem(TOKEN_KEY) || undefined)
       .onConnect((_conn, identity, token) => {
-        localStorage.setItem('auth_token', token);
+        localStorage.setItem(TOKEN_KEY, token);
         console.log('Connected:', identity.toHexString());
       })
       .onDisconnect(() => console.log('Disconnected'))
diff --git a/docs/docs/00100-intro/00200-quickstarts/00180-browser.md b/docs/docs/00100-intro/00200-quickstarts/00180-browser.md
index bf46e58012f..649f7e2eaba 100644
--- a/docs/docs/00100-intro/00200-quickstarts/00180-browser.md
+++ b/docs/docs/00100-intro/00200-quickstarts/00180-browser.md
@@ -63,12 +63,16 @@ npm run build
 <script src="dist/bindings.iife.js"></script>
 
 <script>
+  const HOST = 'ws://localhost:3000';
+  const DB_NAME = 'my-spacetime-app';
+  const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
+
   const conn = DbConnection.builder()
-    .withUri('ws://localhost:3000')
-    .withDatabaseName('my-spacetime-app')
-    .withToken(localStorage.getItem('auth_token'))
+    .withUri(HOST)
+    .withDatabaseName(DB_NAME)
+    .withToken(localStorage.getItem(TOKEN_KEY))
     .onConnect((conn, identity, token) => {
-      localStorage.setItem('auth_token', token);
+      localStorage.setItem(TOKEN_KEY, token);
       console.log('Connected:', identity.toHexString());
 
       // Subscribe to tables
diff --git a/docs/docs/00100-intro/00300-tutorials/00100-chat-app.md b/docs/docs/00100-intro/00300-tutorials/00100-chat-app.md
index e97f772cf42..c26dcaecd0b 100644
--- a/docs/docs/00100-intro/00300-tutorials/00100-chat-app.md
+++ b/docs/docs/00100-intro/00300-tutorials/00100-chat-app.md
@@ -1366,8 +1366,12 @@ Now that we've imported the `DbConnection` type, we can use it to connect our ap
 Replace the body of the `main.tsx` file with the following, just below your imports:
 
 ```tsx
+const HOST = 'ws://localhost:3000';
+const DB_NAME = 'quickstart-chat';
+const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
+
 const onConnect = (conn: DbConnection, identity: Identity, token: string) => {
-  localStorage.setItem('auth_token', token);
+  localStorage.setItem(TOKEN_KEY, token);
   console.log(
     'Connected to SpacetimeDB with identity:',
     identity.toHexString()
@@ -1386,9 +1390,9 @@ const onConnectError = (_ctx: ErrorContext, err: Error) => {
 };
 
 const connectionBuilder = DbConnection.builder()
-  .withUri('ws://localhost:3000')
-  .withDatabaseName('quickstart-chat')
-  .withToken(localStorage.getItem('auth_token') || undefined)
+  .withUri(HOST)
+  .withDatabaseName(DB_NAME)
+  .withToken(localStorage.getItem(TOKEN_KEY) || undefined)
   .onConnect(onConnect)
   .onDisconnect(onDisconnect)
   .onConnectError(onConnectError);
diff --git a/docs/docs/00200-core-concepts/00600-client-sdk-languages/00300-connection.md b/docs/docs/00200-core-concepts/00600-client-sdk-languages/00300-connection.md
index e2ab1109e80..73f1005eb7a 100644
--- a/docs/docs/00200-core-concepts/00600-client-sdk-languages/00300-connection.md
+++ b/docs/docs/00200-core-concepts/00600-client-sdk-languages/00300-connection.md
@@ -231,13 +231,17 @@ Register callbacks to observe connection state changes:
 <TabItem value="typescript" label="TypeScript">
 
 ```typescript
+const HOST = "https://maincloud.spacetimedb.com";
+const DB_NAME = "my_database";
+const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
+
 const conn = DbConnection.builder()
-    .withUri("https://maincloud.spacetimedb.com")
-    .withDatabaseName("my_database")
+    .withUri(HOST)
+    .withDatabaseName(DB_NAME)
     .onConnect((conn, identity, token) => {
         console.log(`Connected! Identity: ${identity.toHexString()}`);
-        // Save token for reconnection
-        localStorage.setItem('auth_token', token);
+        // Save token for reconnection — keyed per server/database
+        localStorage.setItem(TOKEN_KEY, token);
     })
     .onConnectError((_ctx, error) => {
         console.error(`Connection failed:`, error);
diff --git a/templates/chat-react-ts/src/App.integration.test.tsx b/templates/chat-react-ts/src/App.integration.test.tsx
index 9087b987fda..6e2bcd7276c 100644
--- a/templates/chat-react-ts/src/App.integration.test.tsx
+++ b/templates/chat-react-ts/src/App.integration.test.tsx
@@ -10,7 +10,11 @@ describe('App Integration Test', () => {
     const connectionBuilder = DbConnection.builder()
       .withUri('ws://localhost:3000')
       .withDatabaseName('quickstart-chat')
-      .withToken(localStorage.getItem('auth_token') || '');
+      .withToken(
+        localStorage.getItem(
+          'ws://localhost:3000/quickstart-chat/auth_token'
+        ) || ''
+      );
     render(
       <SpacetimeDBProvider connectionBuilder={connectionBuilder}>
         <App />
diff --git a/templates/chat-react-ts/src/main.tsx b/templates/chat-react-ts/src/main.tsx
index a3812483586..0ee3d5506d9 100644
--- a/templates/chat-react-ts/src/main.tsx
+++ b/templates/chat-react-ts/src/main.tsx
@@ -8,9 +8,10 @@ import { DbConnection, ErrorContext } from './module_bindings/index.ts';
 
 const HOST = import.meta.env.VITE_SPACETIMEDB_HOST ?? 'ws://localhost:3000';
 const DB_NAME = import.meta.env.VITE_SPACETIMEDB_DB_NAME ?? 'quickstart-chat';
+const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
 
 const onConnect = (conn: DbConnection, identity: Identity, token: string) => {
-  localStorage.setItem('auth_token', token);
+  localStorage.setItem(TOKEN_KEY, token);
   console.log(
     'Connected to SpacetimeDB with identity:',
     identity.toHexString()
@@ -28,7 +29,7 @@ const onConnectError = (_ctx: ErrorContext, err: Error) => {
 const connectionBuilder = DbConnection.builder()
   .withUri(HOST)
   .withDatabaseName(DB_NAME)
-  .withToken(localStorage.getItem('auth_token') || undefined)
+  .withToken(localStorage.getItem(TOKEN_KEY) || undefined)
   .onConnect(onConnect)
   .onDisconnect(onDisconnect)
   .onConnectError(onConnectError);
diff --git a/templates/nextjs-ts/app/providers.tsx b/templates/nextjs-ts/app/providers.tsx
index 1e0c39a191a..05c4eeb9d75 100644
--- a/templates/nextjs-ts/app/providers.tsx
+++ b/templates/nextjs-ts/app/providers.tsx
@@ -8,10 +8,11 @@ import { Identity } from 'spacetimedb';
 const HOST =
   process.env.NEXT_PUBLIC_SPACETIMEDB_HOST ?? 'wss://maincloud.spacetimedb.com';
 const DB_NAME = process.env.NEXT_PUBLIC_SPACETIMEDB_DB_NAME ?? 'nextjs-ts';
+const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
 
 const onConnect = (_conn: DbConnection, identity: Identity, token: string) => {
   if (typeof window !== 'undefined') {
-    localStorage.setItem('auth_token', token);
+    localStorage.setItem(TOKEN_KEY, token);
   }
   console.log(
     'Connected to SpacetimeDB with identity:',
@@ -32,10 +33,10 @@ export function Providers({ children }: { children: React.ReactNode }) {
     () =>
       DbConnection.builder()
         .withUri(HOST)
-        .withModuleName(DB_NAME)
+        .withDatabaseName(DB_NAME)
         .withToken(
           typeof window !== 'undefined'
-            ? localStorage.getItem('auth_token') || undefined
+            ? localStorage.getItem(TOKEN_KEY) || undefined
             : undefined
         )
         .onConnect(onConnect)
diff --git a/templates/nuxt-ts/app.vue b/templates/nuxt-ts/app.vue
index 60d1c11112b..d8f69d91b3e 100644
--- a/templates/nuxt-ts/app.vue
+++ b/templates/nuxt-ts/app.vue
@@ -16,9 +16,10 @@ import { DbConnection, type ErrorContext } from './module_bindings';
 
 const HOST = import.meta.env.VITE_SPACETIMEDB_HOST ?? 'ws://localhost:3000';
 const DB_NAME = import.meta.env.VITE_SPACETIMEDB_DB_NAME ?? 'nuxt-ts';
+const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
 
 const onConnect = (_conn: DbConnection, identity: Identity, token: string) => {
-  localStorage.setItem('auth_token', token);
+  localStorage.setItem(TOKEN_KEY, token);
   console.log(
     'Connected to SpacetimeDB with identity:',
     identity.toHexString()
@@ -36,8 +37,8 @@ const onConnectError = (_ctx: ErrorContext, err: Error) => {
 const connectionBuilder = import.meta.client
   ? DbConnection.builder()
       .withUri(HOST)
-      .withModuleName(DB_NAME)
-      .withToken(localStorage.getItem('auth_token') || undefined)
+      .withDatabaseName(DB_NAME)
+      .withToken(localStorage.getItem(TOKEN_KEY) || undefined)
       .onConnect(onConnect)
       .onDisconnect(onDisconnect)
       .onConnectError(onConnectError)
diff --git a/templates/react-ts/src/main.tsx b/templates/react-ts/src/main.tsx
index 48319340b6a..1e0e606c261 100644
--- a/templates/react-ts/src/main.tsx
+++ b/templates/react-ts/src/main.tsx
@@ -7,9 +7,10 @@ import { DbConnection, ErrorContext } from './module_bindings/index.ts';
 
 const HOST = import.meta.env.VITE_SPACETIMEDB_HOST ?? 'ws://localhost:3000';
 const DB_NAME = import.meta.env.VITE_SPACETIMEDB_DB_NAME ?? 'react-ts';
+const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
 
 const onConnect = (_conn: DbConnection, identity: Identity, token: string) => {
-  localStorage.setItem('auth_token', token);
+  localStorage.setItem(TOKEN_KEY, token);
   console.log(
     'Connected to SpacetimeDB with identity:',
     identity.toHexString()
@@ -27,7 +28,7 @@ const onConnectError = (_ctx: ErrorContext, err: Error) => {
 const connectionBuilder = DbConnection.builder()
   .withUri(HOST)
   .withDatabaseName(DB_NAME)
-  .withToken(localStorage.getItem('auth_token') || undefined)
+  .withToken(localStorage.getItem(TOKEN_KEY) || undefined)
   .onConnect(onConnect)
   .onDisconnect(onDisconnect)
   .onConnectError(onConnectError);
diff --git a/templates/remix-ts/app/root.tsx b/templates/remix-ts/app/root.tsx
index 2ba4a6ef748..ac873cbf9b6 100644
--- a/templates/remix-ts/app/root.tsx
+++ b/templates/remix-ts/app/root.tsx
@@ -14,10 +14,11 @@ import { Identity } from 'spacetimedb';
 const HOST =
   import.meta.env.VITE_SPACETIMEDB_HOST ?? 'wss://maincloud.spacetimedb.com';
 const DB_NAME = import.meta.env.VITE_SPACETIMEDB_DB_NAME ?? 'remix-ts';
+const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
 
 const onConnect = (_conn: DbConnection, identity: Identity, token: string) => {
   if (typeof window !== 'undefined') {
-    localStorage.setItem('auth_token', token);
+    localStorage.setItem(TOKEN_KEY, token);
   }
   console.log(
     'Connected to SpacetimeDB with identity:',
@@ -46,8 +47,8 @@ function Providers({ children }: { children: React.ReactNode }) {
     if (typeof window === 'undefined') return null;
     return DbConnection.builder()
       .withUri(HOST)
-      .withModuleName(DB_NAME)
-      .withToken(localStorage.getItem('auth_token') || undefined)
+      .withDatabaseName(DB_NAME)
+      .withToken(localStorage.getItem(TOKEN_KEY) || undefined)
       .onConnect(onConnect)
       .onDisconnect(onDisconnect)
       .onConnectError(onConnectError);
diff --git a/templates/svelte-ts/src/Root.svelte b/templates/svelte-ts/src/Root.svelte
index 59709c6a910..65cfbf6bcb3 100644
--- a/templates/svelte-ts/src/Root.svelte
+++ b/templates/svelte-ts/src/Root.svelte
@@ -6,9 +6,10 @@ import App from './App.svelte';
 
 const HOST = import.meta.env.VITE_SPACETIMEDB_HOST ?? 'ws://localhost:3000';
 const DB_NAME = import.meta.env.VITE_SPACETIMEDB_DB_NAME ?? 'svelte-ts';
+const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
 
 const onConnect = (_conn: DbConnection, identity: Identity, token: string) => {
-  localStorage.setItem('auth_token', token);
+  localStorage.setItem(TOKEN_KEY, token);
   console.log(
     'Connected to SpacetimeDB with identity:',
     identity.toHexString()
@@ -26,7 +27,7 @@ const onConnectError = (_ctx: ErrorContext, err: Error) => {
 const connectionBuilder = DbConnection.builder()
   .withUri(HOST)
   .withDatabaseName(DB_NAME)
-  .withToken(localStorage.getItem('auth_token') || undefined)
+  .withToken(localStorage.getItem(TOKEN_KEY) || undefined)
   .onConnect(onConnect)
   .onDisconnect(onDisconnect)
   .onConnectError(onConnectError);
diff --git a/templates/tanstack-ts/src/router.tsx b/templates/tanstack-ts/src/router.tsx
index 86fe2a2f7cb..3a8569a1568 100644
--- a/templates/tanstack-ts/src/router.tsx
+++ b/templates/tanstack-ts/src/router.tsx
@@ -11,6 +11,7 @@ import { DbConnection, ErrorContext } from './module_bindings';
 
 const HOST = import.meta.env.VITE_SPACETIMEDB_HOST ?? 'ws://localhost:3000';
 const DB_NAME = import.meta.env.VITE_SPACETIMEDB_DB_NAME ?? 'tanstack-ts';
+const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
 
 const spacetimeDBQueryClient = new SpacetimeDBQueryClient();
 
@@ -29,7 +30,7 @@ spacetimeDBQueryClient.connect(queryClient);
 
 const onConnect = (conn: DbConnection, identity: Identity, token: string) => {
   if (typeof localStorage !== 'undefined') {
-    localStorage.setItem('auth_token', token);
+    localStorage.setItem(TOKEN_KEY, token);
   }
   console.log(
     'Connected to SpacetimeDB with identity:',
@@ -48,10 +49,10 @@ const onConnectError = (_ctx: ErrorContext, err: Error) => {
 
 const connectionBuilder = DbConnection.builder()
   .withUri(HOST)
-  .withModuleName(DB_NAME)
+  .withDatabaseName(DB_NAME)
   .withToken(
     typeof localStorage !== 'undefined'
-      ? (localStorage.getItem('auth_token') ?? undefined)
+      ? (localStorage.getItem(TOKEN_KEY) ?? undefined)
       : undefined
   )
   .onConnect(onConnect)
diff --git a/templates/vue-ts/src/main.ts b/templates/vue-ts/src/main.ts
index 340319997d3..2f825fcbb65 100644
--- a/templates/vue-ts/src/main.ts
+++ b/templates/vue-ts/src/main.ts
@@ -6,9 +6,10 @@ import { DbConnection, ErrorContext } from './module_bindings/index.ts';
 
 const HOST = import.meta.env.VITE_SPACETIMEDB_HOST ?? 'ws://localhost:3000';
 const DB_NAME = import.meta.env.VITE_SPACETIMEDB_DB_NAME ?? 'vue-ts';
+const TOKEN_KEY = `${HOST}/${DB_NAME}/auth_token`;
 
 const onConnect = (_conn: DbConnection, identity: Identity, token: string) => {
-  localStorage.setItem('auth_token', token);
+  localStorage.setItem(TOKEN_KEY, token);
   console.log(
     'Connected to SpacetimeDB with identity:',
     identity.toHexString()
@@ -26,7 +27,7 @@ const onConnectError = (_ctx: ErrorContext, err: Error) => {
 const connectionBuilder = DbConnection.builder()
   .withUri(HOST)
   .withDatabaseName(DB_NAME)
-  .withToken(localStorage.getItem('auth_token') || undefined)
+  .withToken(localStorage.getItem(TOKEN_KEY) || undefined)
   .onConnect(onConnect)
   .onDisconnect(onDisconnect)
   .onConnectError(onConnectError);