clockworklabs
diff --git a/‎docs/docs/00100-intro/00200-quickstarts/00155-nuxt.md‎
Lines changed: 242 additions & 0 deletions b/‎docs/docs/00100-intro/00200-quickstarts/00155-nuxt.md‎
Lines changed: 242 additions & 0 deletions
@@ -0,0 +1,242 @@
+---
+title: Nuxt Quickstart
+sidebar_label: Nuxt
+slug: /quickstarts/nuxt
+hide_table_of_contents: true
+---
+
+import { InstallCardLink } from "@site/src/components/InstallCardLink";
+import { StepByStep, Step, StepText, StepCode } from "@site/src/components/Steps";
+
+
+Get a SpacetimeDB Nuxt app running in under 5 minutes.
+
+## Prerequisites
+
+- [Node.js](https://nodejs.org/) 18+ installed
+- [SpacetimeDB CLI](https://spacetimedb.com/install) installed
+
+<InstallCardLink />
+
+---
+
+<StepByStep>
+  <Step title="Create your project">
+    <StepText>
+      Run the `spacetime dev` command to create a new project with a SpacetimeDB module and Nuxt client.
+
+      This will start the local SpacetimeDB server, publish your module, generate TypeScript bindings, and start the Nuxt development server.
+    </StepText>
+    <StepCode>
+```bash
+spacetime dev --template nuxt-ts
+```
+    </StepCode>
+  </Step>
+
+  <Step title="Open your app">
+    <StepText>
+      Navigate to [http://localhost:5173](http://localhost:5173) to see your app running.
+
+      The template includes a basic Nuxt app connected to SpacetimeDB.
+    </StepText>
+  </Step>
+
+  <Step title="Explore the project structure">
+    <StepText>
+      Your project contains both server and client code.
+
+      Edit `spacetimedb/src/index.ts` to add tables and reducers. Edit `components/AppContent.vue` to build your UI, and `app.vue` to configure the SpacetimeDB connection.
+    </StepText>
+    <StepCode>
+```
+my-spacetime-app/
+├── spacetimedb/          # Your SpacetimeDB module
+│   └── src/
+│       └── index.ts      # SpacetimeDB module logic
+├── app.vue               # Root component with provider
+├── components/
+│   └── AppContent.vue    # Main UI component
+├── server/
+│   └── api/
+│       └── people.get.ts # Server-side data fetching
+├── module_bindings/      # Auto-generated types
+├── nuxt.config.ts        # Nuxt configuration
+└── package.json
+```
+    </StepCode>
+  </Step>
+
+  <Step title="Understand tables and reducers">
+    <StepText>
+      Open `spacetimedb/src/index.ts` to see the module code. The template includes a `person` table and two reducers: `add` to insert a person, and `say_hello` to greet everyone.
+
+      Tables store your data. Reducers are functions that modify data — they're the only way to write to the database.
+    </StepText>
+    <StepCode>
+```typescript
+import { schema, table, t } from 'spacetimedb/server';
+
+export const spacetimedb = schema(
+  table(
+    { name: 'person', public: true },
+    {
+      name: t.string(),
+    }
+  )
+);
+
+spacetimedb.reducer('add', { name: t.string() }, (ctx, { name }) => {
+  ctx.db.person.insert({ name });
+});
+
+spacetimedb.reducer('say_hello', (ctx) => {
+  for (const person of ctx.db.person.iter()) {
+    console.info(`Hello, ${person.name}!`);
+  }
+  console.info('Hello, World!');
+});
+```
+    </StepCode>
+  </Step>
+
+  <Step title="Test with the CLI">
+    <StepText>
+      Use the SpacetimeDB CLI to call reducers and query your data directly.
+    </StepText>
+    <StepCode>
+```bash
+# Call the add reducer to insert a person
+spacetime call <database-name> add Alice
+
+# Query the person table
+spacetime sql <database-name> "SELECT * FROM person"
+ name
+---------
+ "Alice"
+
+# Call say_hello to greet everyone
+spacetime call <database-name> say_hello
+
+# View the module logs
+spacetime logs <database-name>
+2025-01-13T12:00:00.000000Z  INFO: Hello, Alice!
+2025-01-13T12:00:00.000000Z  INFO: Hello, World!
+```
+    </StepCode>
+  </Step>
+
+  <Step title="Understand server-side rendering">
+    <StepText>
+      The SpacetimeDB SDK works both server-side and client-side. The template uses a hybrid approach:
+
+      - **Server API route** (`server/api/people.get.ts`): Fetches initial data during SSR for fast page loads
+      - **Client composables**: Maintain a real-time WebSocket connection for live updates
+
+      The server API route connects to SpacetimeDB, subscribes, fetches data, and disconnects.
+    </StepText>
+    <StepCode>
+```typescript
+// server/api/people.get.ts
+import { DbConnection } from '../../module_bindings';
+
+export default defineEventHandler(async () => {
+  return new Promise((resolve, reject) => {
+    DbConnection.builder()
+      .withUri(process.env.SPACETIMEDB_HOST!)
+      .withModuleName(process.env.SPACETIMEDB_DB_NAME!)
+      .onConnect((conn) => {
+        conn.subscriptionBuilder()
+          .onApplied(() => {
+            const people = Array.from(conn.db.person.iter());
+            conn.disconnect();
+            resolve(people);
+          })
+          .subscribe('SELECT * FROM person');
+      })
+      .build();
+  });
+});
+```
+    </StepCode>
+  </Step>
+
+  <Step title="Set up the SpacetimeDB provider">
+    <StepText>
+      The root `app.vue` wraps your app in a `SpacetimeDBProvider` that manages the WebSocket connection. The provider is wrapped in `ClientOnly` so it only runs in the browser, while SSR uses the server API route for initial data.
+    </StepText>
+    <StepCode>
+```vue
+<!-- app.vue -->
+<template>
+  <ClientOnly>
+    <SpacetimeDBProvider :connection-builder="connectionBuilder">
+      <AppContent />
+    </SpacetimeDBProvider>
+    <template #fallback>
+      <AppContent />
+    </template>
+  </ClientOnly>
+</template>
+
+<script setup lang="ts">
+import { SpacetimeDBProvider } from 'spacetimedb/vue';
+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 connectionBuilder = import.meta.client
+  ? DbConnection.builder()
+      .withUri(HOST)
+      .withModuleName(DB_NAME)
+      .withToken(localStorage.getItem('auth_token') || undefined)
+      .onConnect((_conn, identity, token) => {
+        localStorage.setItem('auth_token', token);
+        console.log('Connected:', identity.toHexString());
+      })
+      .onDisconnect(() => console.log('Disconnected'))
+      .onConnectError((_ctx, err) => console.log('Error:', err))
+  : undefined;
+</script>
+```
+    </StepCode>
+  </Step>
+
+  <Step title="Use composables and SSR data together">
+    <StepText>
+      Use `useFetch` to load initial data server-side, then Vue composables for real-time updates on the client. The component displays server-fetched data immediately while the WebSocket connection establishes.
+    </StepText>
+    <StepCode>
+```vue
+<!-- components/AppContent.vue -->
+<script setup lang="ts">
+import { ref, computed } from 'vue';
+import { tables, reducers } from '../module_bindings';
+
+// Fetch initial data server-side for SSR
+const { data: initialPeople } = await useFetch('/api/people');
+
+// On the client, use real-time composables
+let conn, people, addReducer;
+if (import.meta.client) {
+  const { useSpacetimeDB, useTable, useReducer } = await import('spacetimedb/vue');
+  conn = useSpacetimeDB();
+  [people] = useTable(tables.person);
+  addReducer = useReducer(reducers.add);
+}
+
+// Use real-time data once connected, fall back to SSR data
+const displayPeople = computed(() => {
+  if (conn?.isActive && people?.value) return people.value;
+  return initialPeople.value ?? [];
+});
+</script>
+```
+    </StepCode>
+  </Step>
+</StepByStep>
+
+## Next steps
+
+- Read the [TypeScript SDK Reference](/sdks/typescript) for detailed API docs