---
title: Astro Quickstart
sidebar_label: Astro
slug: /quickstarts/astro
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 Astro 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 Astro client.

      This will start the local SpacetimeDB server, publish your module, generate TypeScript bindings, and start the Astro development server.
    </StepText>
    <StepCode>
```bash
spacetime dev --template astro-ts
```
    </StepCode>
  </Step>

  <Step title="Open your app">
    <StepText>
      Navigate to [http://localhost:4321](http://localhost:4321) to see your app running.

      The Astro app reads `SPACETIMEDB_*` variables on the server and `PUBLIC_SPACETIMEDB_*` variables in the client, so `.env.local` can configure both sides of the app.
    </StepText>
  </Step>

  <Step title="Explore the project structure">
    <StepText>
      Your project contains both server and client code using Astro SSR and a live React island for real-time updates.

      Edit `spacetimedb/src/index.ts` to add tables and reducers. Edit `src/pages/index.astro` and `src/components/PersonList.tsx` to build your UI.
    </StepText>
    <StepCode>
```text
my-astro-app/
├── spacetimedb/              # Your SpacetimeDB module
│   └── src/
│       └── index.ts          # SpacetimeDB module logic
├── src/
│   ├── components/
│   │   ├── PersonList.tsx
│   │   ├── SpacetimeApp.tsx
│   │   └── DeferredPeopleSnapshot.astro
│   ├── lib/
│   │   └── spacetimedb-server.ts
│   ├── module_bindings/      # Auto-generated types
│   ├── layouts/
│   │   └── Layout.astro
│   ├── pages/
│   │   └── index.astro
│   └── styles/
│       └── global.css
└── 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 `sayHello` to greet everyone.

      Tables store your data. Reducers are functions that modify data and are the only way to write to the database.
    </StepText>
    <StepCode>
```typescript
import { schema, table, t } from 'spacetimedb/server';

const spacetimedb = schema({
  person: table(
    { public: true },
    {
      name: t.string(),
    }
  ),
});
export default spacetimedb;

export const add = spacetimedb.reducer(
  { name: t.string() },
  (ctx, { name }) => {
    ctx.db.person.insert({ name });
  }
);

export const sayHello = spacetimedb.reducer(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>
      Open a new terminal and navigate to your project directory. Then use the SpacetimeDB CLI to call reducers and query your data directly.
    </StepText>
    <StepCode>
```bash
cd my-spacetime-app

# Call the add reducer to insert a person
spacetime call add Alice

# Query the person table
spacetime sql "SELECT * FROM person"
 name
---------
 "Alice"

# Call sayHello to greet everyone
spacetime call say_hello

# View the module logs
spacetime logs
2025-01-13T12:00:00.000000Z  INFO: Hello, Alice!
2025-01-13T12:00:00.000000Z  INFO: Hello, World!
```
    </StepCode>
  </Step>

  <Step title="Understand Astro SSR and real-time hydration">
    <StepText>
      The SpacetimeDB SDK works both server-side and client-side. The template uses a hybrid approach:

      - **Astro page** (`src/pages/index.astro`): Fetches initial data on the server for a fast first render
      - **React island** (`src/components/SpacetimeApp.tsx`): Hydrates on the client and provides the SpacetimeDB connection
      - **Live table UI** (`src/components/PersonList.tsx`): Uses `useTable()` and `useReducer()` for real-time updates
    </StepText>
    <StepCode>
```astro
---
import Layout from '../layouts/Layout.astro';
import SpacetimeApp from '../components/SpacetimeApp';
import { fetchPeople } from '../lib/spacetimedb-server';

const initialPeople = await fetchPeople();
---

<Layout title="astro-ts">
  <h1>astro-ts</h1>
  <SpacetimeApp client:load initialPeople={initialPeople} />
</Layout>
```
    </StepCode>
  </Step>

  <Step title="Understand Astro server islands">
    <StepText>
      The template also includes a deferred Astro-only section to demonstrate `server:defer`.

      `src/components/DeferredPeopleSnapshot.astro` fetches its own server-rendered snapshot, and `src/pages/index.astro` renders it as a server island without changing the main real-time client flow.
    </StepText>
    <StepCode>
```astro
<DeferredPeopleSnapshot server:defer>
  <div slot="fallback">Loading deferred people snapshot…</div>
</DeferredPeopleSnapshot>
```
    </StepCode>
  </Step>
</StepByStep>
