Quickstart nextjs (#4097)

# Description of Changes

Adds a new Next.js quickstart template and documentation.

**New Template (`templates/nextjs-ts/`):**
- Next.js 15 App Router with TypeScript SpacetimeDB module
- Pre-configured `SpacetimeDBProvider` with client-side connection
handling
- Environment variable support (`NEXT_PUBLIC_SPACETIMEDB_HOST`,
`NEXT_PUBLIC_SPACETIMEDB_DB_NAME`)
- SSR-safe implementation with `"use client"` directives
- Example page demonstrating `useTable` and `useReducer` hooks
- Dev server runs on port 3001 to avoid conflict with SpacetimeDB on
port 3000
- Pre-generated module bindings included

**New Documentation (`docs/.../00200-nextjs.md`):**
- 8-step quickstart consistent with other quickstarts (React,
TypeScript, Rust, C#)
- Covers: project creation, structure, tables/reducers, CLI testing
- Next.js-specific: provider pattern, SSR considerations, env var
configuration, React hooks usage

**Updated `templates-list.json`:**
- Added `nextjs-ts` to highlights and templates list

# API and ABI breaking changes

None.

# Expected complexity level and risk

1 - Adds a new template and docs without modifying existing
functionality.

# Testing

- [ ] Run `spacetime dev --template nextjs-ts my-test-app` and verify
the app starts
- [ ] Navigate to http://localhost:3001 and confirm the UI loads and
connects
- [ ] Add a person via the UI and verify it appears in the list
- [ ] Verify env vars work: set `NEXT_PUBLIC_SPACETIMEDB_URI` and
`NEXT_PUBLIC_SPACETIMEDB_MODULE`
- [ ] Verify the quickstart doc renders correctly in the docs site
- [ ] Confirm Next.js appears in the sidebar after React

Author: bradleyshep

docs/docs/00100-intro/00200-quickstarts/00150-nextjs.md

@@ -0,0 +1,210 @@
+---
+title: Next.js Quickstart
+sidebar_label: Next.js
+slug: /quickstarts/nextjs
+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 Next.js 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 Next.js client.
+
+      This will start the local SpacetimeDB server, publish your module, generate TypeScript bindings, and start the Next.js development server.
+    </StepText>
+    <StepCode>
+```bash
+spacetime dev --template nextjs-ts my-nextjs-app
+```
+    </StepCode>
+  </Step>
+
+  <Step title="Open your app">
+    <StepText>
+      Navigate to [http://localhost:3000](http://localhost:3000) to see your app running.
+
+      The `spacetime dev` command automatically configures your app to connect to SpacetimeDB via environment variables in `.env.local`.
+    </StepText>
+  </Step>
+
+  <Step title="Explore the project structure">
+    <StepText>
+      Your project contains both server and client code using the Next.js App Router.
+
+      Edit `spacetimedb/src/index.ts` to add tables and reducers. Edit `app/page.tsx` and `app/PersonList.tsx` to build your UI.
+    </StepText>
+    <StepCode>
+```
+my-nextjs-app/
+├── spacetimedb/          # Your SpacetimeDB module
+│   └── src/
+│       └── index.ts      # SpacetimeDB module logic
+├── app/                  # Next.js App Router
+│   ├── layout.tsx        # Root layout with providers
+│   ├── page.tsx          # Server Component (fetches initial data)
+│   ├── PersonList.tsx    # Client Component (real-time updates)
+│   └── providers.tsx     # SpacetimeDB provider for real-time
+├── lib/
+│   └── spacetimedb-server.ts  # Server-side data fetching
+├── src/
+│   └── module_bindings/  # Auto-generated types
+└── 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 my-nextjs-app add Alice
+
+# Query the person table
+spacetime sql my-nextjs-app "SELECT * FROM person"
+ name
+---------
+ "Alice"
+
+# Call say_hello to greet everyone
+spacetime call my-nextjs-app say_hello
+
+# View the module logs
+spacetime logs my-nextjs-app
+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 Component** (`page.tsx`): Fetches initial data during SSR for fast page loads
+      - **Client Component** (`PersonList.tsx`): Maintains a real-time WebSocket connection for live updates
+
+      The `lib/spacetimedb-server.ts` file provides a utility for server-side data fetching.
+    </StepText>
+    <StepCode>
+```tsx
+// lib/spacetimedb-server.ts
+import { DbConnection } from '../src/module_bindings';
+
+export async function fetchPeople() {
+  return new Promise((resolve, reject) => {
+    const connection = 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="Use React hooks for real-time data">
+    <StepText>
+      In client components, use `useTable` to subscribe to table data and `useReducer` to call reducers. The Server Component passes initial data as props for instant rendering.
+    </StepText>
+    <StepCode>
+```tsx
+// app/page.tsx (Server Component)
+import { PersonList } from './PersonList';
+import { fetchPeople } from '../lib/spacetimedb-server';
+
+export default async function Home() {
+  const initialPeople = await fetchPeople();
+  return <PersonList initialPeople={initialPeople} />;
+}
+```
+
+```tsx
+// app/PersonList.tsx (Client Component)
+'use client';
+
+import { tables, reducers } from '../src/module_bindings';
+import { useTable, useReducer } from 'spacetimedb/react';
+
+export function PersonList({ initialPeople }) {
+  // Real-time data from WebSocket subscription
+  const [people, isLoading] = useTable(tables.person);
+  const addPerson = useReducer(reducers.add);
+
+  // Use server data until client is connected
+  const displayPeople = isLoading ? initialPeople : people;
+
+  return (
+    <ul>
+      {displayPeople.map((person, i) => <li key={i}>{person.name}</li>)}
+    </ul>
+  );
+}
+```
+    </StepCode>
+  </Step>
+</StepByStep>
+
+## Next steps
+
+- See the [Chat App Tutorial](/tutorials/chat-app) for a complete example
+- Read the [TypeScript SDK Reference](/sdks/typescript) for detailed API docs

templates/nextjs-ts/.template.json

@@ -0,0 +1,5 @@
+{
+  "description": "Next.js App Router with TypeScript server",
+  "client_lang": "typescript",
+  "server_lang": "typescript"
+}

templates/nextjs-ts/LICENSE

@@ -0,0 +1 @@
+../../licenses/apache2.txt

templates/nextjs-ts/app/PersonList.tsx

@@ -0,0 +1,85 @@
+'use client';
+
+import { useState, useEffect } from 'react';
+import { tables, reducers } from '../src/module_bindings';
+import { useSpacetimeDB, useTable, useReducer } from 'spacetimedb/react';
+import type { PersonData } from '../lib/spacetimedb-server';
+
+interface PersonListProps {
+  initialPeople: PersonData[];
+}
+
+export function PersonList({ initialPeople }: PersonListProps) {
+  const [name, setName] = useState('');
+  const [isHydrated, setIsHydrated] = useState(false);
+
+  const conn = useSpacetimeDB();
+  const { isActive: connected } = conn;
+
+  // Subscribe to all people in the database
+  // useTable returns [rows, isLoading] tuple
+  const [people, isLoading] = useTable(tables.person);
+
+  const addReducer = useReducer(reducers.add);
+
+  // Once connected and loaded, we're hydrated with real-time data
+  useEffect(() => {
+    if (connected && !isLoading) {
+      setIsHydrated(true);
+    }
+  }, [connected, isLoading]);
+
+  // Use server-rendered data until client is hydrated with real-time data
+  const displayPeople = isHydrated ? people : initialPeople;
+
+  const addPerson = (e: React.FormEvent) => {
+    e.preventDefault();
+    if (!name.trim() || !connected) return;
+
+    // Call the add reducer with object syntax
+    addReducer({ name: name });
+    setName('');
+  };
+
+  return (
+    <>
+      <div style={{ marginBottom: '1rem' }}>
+        Status:{' '}
+        <strong style={{ color: connected ? 'green' : 'red' }}>
+          {connected ? 'Connected' : 'Connecting...'}
+        </strong>
+      </div>
+
+      <form onSubmit={addPerson} style={{ marginBottom: '2rem' }}>
+        <input
+          type="text"
+          placeholder="Enter name"
+          value={name}
+          onChange={e => setName(e.target.value)}
+          style={{ padding: '0.5rem', marginRight: '0.5rem' }}
+          disabled={!connected}
+        />
+        <button
+          type="submit"
+          style={{ padding: '0.5rem 1rem' }}
+          disabled={!connected}
+        >
+          Add Person
+        </button>
+      </form>
+
+      <div>
+        <h2>People ({displayPeople.length})</h2>
+        {displayPeople.length === 0 ? (
+          <p>No people yet. Add someone above!</p>
+        ) : (
+          <ul>
+            {displayPeople.map((person, index) => (
+              <li key={index}>{person.name}</li>
+            ))}
+          </ul>
+        )}
+      </div>
+    </>
+  );
+}

templates/nextjs-ts/app/globals.css

@@ -0,0 +1,28 @@
+* {
+  box-sizing: border-box;
+  padding: 0;
+  margin: 0;
+}
+
+html,
+body {
+  max-width: 100vw;
+  overflow-x: hidden;
+}
+
+body {
+  color: #333;
+  background: #fafafa;
+}
+
+a {
+  color: inherit;
+  text-decoration: none;
+}
+
+@media (prefers-color-scheme: dark) {
+  body {
+    color: #eee;
+    background: #111;
+  }
+}

templates/nextjs-ts/app/layout.tsx

@@ -0,0 +1,22 @@
+import type { Metadata } from 'next';
+import { Providers } from './providers';
+import './globals.css';
+
+export const metadata: Metadata = {
+  title: 'SpacetimeDB Next.js App',
+  description: 'A Next.js app powered by SpacetimeDB',
+};
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}

templates/nextjs-ts/app/page.tsx

@@ -0,0 +1,22 @@
+import { PersonList } from './PersonList';
+import { fetchPeople } from '../lib/spacetimedb-server';
+
+export default async function Home() {
+  // Fetch initial data on the server
+  let initialPeople: Awaited<ReturnType<typeof fetchPeople>> = [];
+
+  try {
+    initialPeople = await fetchPeople();
+  } catch (error) {
+    // If server-side fetch fails, the client will still work
+    // This can happen if the database is not yet published
+    console.error('Failed to fetch initial data:', error);
+  }
+
+  return (
+    <main style={{ padding: '2rem', fontFamily: 'system-ui, sans-serif' }}>
+      <h1>SpacetimeDB Next.js App</h1>
+      <PersonList initialPeople={initialPeople} />
+    </main>
+  );
+}