Local Development

Run DeltaBase locally for faster iteration, safe experimentation, and offline work. Takes about 5 minutes to set up.

What you need

• Node.js 16+
• A terminal
• 5 minutes

What you’ll get

• Local DeltaBase API server at http://localhost:8787
• Studio UI for visualization at http://localhost:3000
• SQLite storage (no external database needed)

---

Start DeltaBase locally

npm

npx @delta-base/cli dev

yarn

yarn dlx @delta-base/cli dev

pnpm

pnpx @delta-base/cli dev

bun

bunx @delta-base/cli dev

deno

deno run -A npm:@delta-base/cli dev

You should see:

┌────────────────────────────────────────────────────────────────────────────┐
│                                                                            │
│  ┌──────────────────────────────────────────────────────────────────────┐  │
│  │██████╗ ███████╗██╗  ████████╗ █████╗ ██████╗  █████╗ ███████╗███████╗│  │
│  │██╔══██╗██╔════╝██║  ╚══██╔══╝██╔══██╗██╔══██╗██╔══██╗██╔════╝██╔════╝│  │
│  │██║  ██║█████╗  ██║     ██║   ███████║██████╔╝███████║███████╗█████╗  │  │
│  │██║  ██║██╔══╝  ██║     ██║   ██╔══██║██╔══██╗██╔══██║╚════██║██╔══╝  │  │
│  │██████╔╝███████╗███████╗██║   ██║  ██║██████╔╝██║  ██║███████║███████╗│  │
│  │╚═════╝ ╚══════╝╚══════╝╚═╝   ╚═╝  ╚═╝╚═════╝ ╚═╝  ╚═╝╚══════╝╚══════╝│  │
│  └──────────────────────────────────────────────────────────────────────┘  │
│                                                                            │
│  Deltabase development environment is ready!                               │
│                                                                            │
│  API Server: http://localhost:8787                                         │
│  Studio UI:  http://localhost:3000                                         │
│                                                                            │
└────────────────────────────────────────────────────────────────────────────┘

Open the Studio at http://localhost:3000 - this is where you’ll visualize your events.

---

Create your project

In a new terminal (keep DeltaBase running), create your project:

npm

mkdir deltabase-quickstart
cd deltabase-quickstart
npm init -y
npm install @delta-base/server

yarn

mkdir deltabase-quickstart
cd deltabase-quickstart
yarn init -y
yarn add @delta-base/server

pnpm

mkdir deltabase-quickstart
cd deltabase-quickstart
pnpm init
pnpm add @delta-base/server

bun

mkdir deltabase-quickstart
cd deltabase-quickstart
bun init -y
bun add @delta-base/server

deno

mkdir deltabase-quickstart
cd deltabase-quickstart
deno init
deno add @delta-base/server

---

Create an event store

Before storing events, we need to create an event store. Create setup.ts:

import { DeltaBase } from '@delta-base/server';

const deltabase = new DeltaBase({
  baseUrl: 'http://localhost:8787'  // Local DeltaBase - no API key needed
});

const managementClient = deltabase.getManagementClient();

async function setupEventStore() {
  try {
    // Create an event store called 'bank'
    const eventStore = await managementClient.createEventStore({
      name: 'bank',
      description: 'Banking events for tutorial'
    });

    console.log('Event store created:', eventStore.name);
    console.log('Check it out in Studio: http://localhost:3000');
  } catch (error: any) {
    if (error.message?.includes('already exists')) {
      console.log('Event store already exists');
    } else {
      console.error('Failed to create event store:', error.message);
    }
  }
}

setupEventStore();

Run the setup:

npm

npx tsx setup.ts

yarn

yarn dlx tsx setup.ts

pnpm

pnpm dlx tsx setup.ts

bun

bun run setup.ts

deno

deno run --allow-net setup.ts

Now check the Studio - you should see your new event store.

---

Store some events

Create index.ts:

import { DeltaBase } from '@delta-base/server';

const deltabase = new DeltaBase({
  baseUrl: 'http://localhost:8787'  // Local DeltaBase
});

const eventStore = deltabase.getEventStore('bank');

async function main() {
  const accountId = 'account-123';

  console.log('Making some transactions...');

  // Store a deposit event
  await eventStore.appendToStream(accountId, [{
    type: 'money.deposited',
    data: { amount: 100 }
  }]);

  // Store a withdrawal event
  await eventStore.appendToStream(accountId, [{
    type: 'money.withdrawn',
    data: { amount: 30 }
  }]);

  console.log('Reading transaction history...');

  // Read all events back
  const result = await eventStore.readStream(accountId);
  console.log('Transaction events:', result.events);

  // Calculate current balance from events
  let balance = 0;
  for (const event of result.events) {
    if (event.type === 'money.deposited') {
      balance += event.data.amount;
    } else if (event.type === 'money.withdrawn') {
      balance -= event.data.amount;
    }
  }

  console.log(`Current balance: $${balance}`);
  console.log('You just did event sourcing!');
  console.log('View your events in Studio: http://localhost:3000');
}

main().catch(console.error);

---

Run it

npm

npx tsx index.ts

yarn

yarn dlx tsx index.ts

pnpm

pnpm dlx tsx index.ts

bun

bun run index.ts

deno

deno run --allow-net --allow-env index.ts

You should see:

Making some transactions...
Reading transaction history...
Transaction events: [
  {
    type: 'money.deposited',
    data: { amount: 100 },
    streamId: 'account-123',
    // ... other metadata
  },
  {
    type: 'money.withdrawn',
    data: { amount: 30 },
    streamId: 'account-123',
    // ... other metadata
  }
]
Current balance: $70
You just did event sourcing!
View your events in Studio: http://localhost:3000

Now go to the Studio! Open http://localhost:3000 and:

1. Select your ‘bank’ event store
2. Click on “Events” in the sidebar
3. See your events visualized in a beautiful table
4. Click on “Streams” to see your ‘account-123’ stream

---

What just happened?

1. You stored events - Facts about what happened (deposit $100, withdraw $30)
2. You read them back - Perfect transaction history, permanently recorded
3. You calculated state - Current balance ($70) comes from replaying all events

That’s event sourcing. Instead of storing current balance, you store what happened. The balance is calculated from the events.

---

Why this is powerful

• Perfect audit trail - You can see every transaction that ever happened (check the Studio!)
• Time travel - Calculate balance at any point in history
• Never lose data - Events are immutable facts, they never get overwritten
• Bank-grade reliability - Every penny is accounted for
• Beautiful visualization - The Studio shows you exactly what’s happening

Try this - add another transaction and run it again. You’ll see the history grow in both your terminal and the Studio.

---

Local vs Production

The code is identical. Only the baseUrl changes:

// Local development
const localClient = new DeltaBase({
  baseUrl: 'http://localhost:8787'  // No API key needed
});

// Production
const prodClient = new DeltaBase({
  apiKey: process.env.DELTABASE_API_KEY,
  baseUrl: 'https://api.delta-base.com'
});

When you’re ready to deploy, just swap the config. Everything else stays the same.

---

What’s next?

You’ve got local development running. Now build something real:

• Banking system - Account management with proper commands
• Shopping cart - Inventory, orders, and handling conflicts

Or deploy to production:

• Send your first event to production - Same code, real infrastructure

Event sourcing isn’t complicated. Events go in, state comes out. Everything else is just details.