Skip to content
delta-base docs

Installation

Add DeltaBase to your project

Add DeltaBase to an existing project. Install packages. Start building.

Which packages do I need?

Section titled “Which packages do I need?”
You want to…Install
Send events to DeltaBase Cloud@delta-base/server
Run DeltaBase locally for development@delta-base/server + @delta-base/cli
Use the Decider Pattern, projections, or testing utilities@delta-base/toolkit
Manage DeltaBase resources from alchemy.run.ts@delta-base/alchemy + alchemy

Most projects: Start with @delta-base/server. Add others as needed.

DeltaBase packages

Section titled “DeltaBase packages”
  • @delta-base/server - Core SDK for interacting with event stores
  • @delta-base/cli - Local development server and deployment tools
  • @delta-base/toolkit - Application-level patterns (Decider, projections, testing)
  • @delta-base/alchemy - Alchemy.run resources for event stores and webhook subscriptions

Add to existing project

Section titled “Add to existing project”
Terminal window
# Core SDK (always needed)
npm install @delta-base/server


# Local development (optional)
npm install -D @delta-base/cli


# Application patterns (optional)
npm install @delta-base/toolkit


# Alchemy resources (optional)
npm install @delta-base/alchemy alchemy

Basic usage

Section titled “Basic usage”

Production (DeltaBase Cloud)

Section titled “Production (DeltaBase Cloud)”
import { DeltaBase } from '@delta-base/server';


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


const eventStore = client.getEventStore('my-store');


// Append events
await eventStore.appendToStream('user-123', [{
  type: 'user.signed_up',
  data: { email: 'hello@example.com' }
}]);


// Read events
const { events } = await eventStore.readStream('user-123');

Local development

Section titled “Local development”
import { DeltaBase } from '@delta-base/server';


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


const eventStore = client.getEventStore('my-store');
// Same API as production

The code is identical. Only the config changes.

If you’re already using Alchemy for the rest of your infrastructure, read DeltaBase with Alchemy next.

Start local development

Section titled “Start local development”

If you installed @delta-base/cli:

Terminal window
npx @delta-base/cli dev

This starts:

  • Local event store API at http://localhost:8787
  • Studio UI at http://localhost:3000
  • SQLite storage (no external database needed)

Events stored locally. No cloud, no API keys, no setup.

Framework integration

Section titled “Framework integration”
Section titled “Hono (recommended)”

Works great with Hono for universal deployment:

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


const app = new Hono();


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


const eventStore = client.getEventStore('banking');


app.post('/accounts/:id/deposit', async (c) => {
  const { amount } = await c.req.json();


  await eventStore.appendToStream(c.req.param('id'), [{
    type: 'money.deposited',
    data: { amount }
  }]);


  return c.json({ success: true });
});


export default app;

Next.js

Section titled “Next.js”
app/api/deposit/route.ts
import { DeltaBase } from '@delta-base/server';


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


const eventStore = client.getEventStore('banking');


export async function POST(request: Request) {
  const { accountId, amount } = await request.json();


  await eventStore.appendToStream(accountId, [{
    type: 'money.deposited',
    data: { amount }
  }]);


  return Response.json({ success: true });
}

Express.js

Section titled “Express.js”
import express from 'express';
import { DeltaBase } from '@delta-base/server';


const app = express();
app.use(express.json());


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


const eventStore = client.getEventStore('banking');


app.post('/deposit', async (req, res) => {
  const { accountId, amount } = req.body;


  await eventStore.appendToStream(accountId, [{
    type: 'money.deposited',
    data: { amount }
  }]);


  res.json({ success: true });
});


app.listen(3000);

TypeScript support

Section titled “TypeScript support”

Define your event types for full type safety:

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


// Define your events
type BankingEvent =
  | { type: 'money.deposited'; data: { amount: number } }
  | { type: 'money.withdrawn'; data: { amount: number } };


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


const eventStore = client.getEventStore('banking');


// Type-safe event appending
await eventStore.appendToStream<BankingEvent>('account-123', [{
  type: 'money.deposited',
  data: { amount: 100 }
}]);


// Type-safe event reading
const { events } = await eventStore.readStream<BankingEvent>('account-123');
events.forEach(event => {
  if (event.type === 'money.deposited') {
    console.log(`Deposited: $${event.data.amount}`);
  }
});

Environment variables

Section titled “Environment variables”

Set up your environment for production:

.env
DELTABASE_API_KEY=your-api-key-here

Load with your preferred method (dotenv, framework built-in, etc.):

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


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

Deployment

Section titled “Deployment”

Same code runs everywhere:

  • Cloudflare Workers - Edge deployment, global by default
  • Vercel Edge Functions - Serverless at the edge
  • AWS Lambda - Traditional serverless
  • Node.js servers - Express, Fastify, Hono
  • Docker containers - Any container runtime
  • Deno Deploy - Deno-native hosting

No code changes needed. Just deploy your app and it works.

What’s next?

Section titled “What’s next?”