Getting Started

Prerequisites

Install

Typebase is split into two packages. typebase-io is the core library. It provides the action builder for your server code and the client utilities for your frontend. typebase-io-cli is the CLI tool that handles code generation, schema pushes to your database, and deployment.

npm install typebase-io

Then install the CLI as a dev dependency, since you only need it during development:

npm install -D typebase-io-cli

Add a typebase script to your package.json:

{
  "scripts": {
    "typebase": "typebase-io-cli"
  }
}

This lets you run CLI commands through your package manager (npx typebase-io-cli init, npx typebase-io-cli deploy, etc.) without installing the CLI globally. Any teammate who clones the repo and runs npm install will have access to the same CLI version.

{
  "scripts": {
    "typebase": "typebase-io-cli-cjs"
  }
}

Initialize

Scaffold the typebase/ directory:

npx typebase-io-cli init

This creates your backend directory with example files. If you want the examples to include authentication setup, pass --with-auth. If you'd rather start from scratch without any examples, pass --skip-example.

typebase/
├── tsconfig.json
├── _generated/           ← auto-generated types, do not edit
├── db/
│   ├── schema.ts         ← your database tables
│   └── relations.ts      ← table relationships
└── actions/
    ├── queries/
    │   └── todos.ts
    └── mutations/
        └── todos.ts

Your first action

The init command already created example actions. Open typebase/actions/queries/todos.ts to see what one looks like:

import { ServerError } from 'typebase-io/server';
import { z } from 'zod';

import { action } from '../../_generated/server.ts';

export const getOne = action
  .input(
    z.object({
      id: z.number(),
    })
  )
  .output(
    z.object({
      id: z.number(),
      value: z.string(),
      completed: z.boolean(),
    })
  )
  .handler(async ({ db, input }) => {
    const todo = await db.query.todos.findFirst({
      where: { id: input.id },
    });

    if (!todo) {
      throw new ServerError('NOT_FOUND');
    }

    return {
      id: todo.id,
      value: todo.value,
      completed: todo.completed,
    };
  });

Each exported action with a .handler() becomes a callable endpoint on your client. Feel free to edit these files or add new ones. Run codegen whenever you create or delete a file inside actions/, or when you add or remove auth.ts, db/schema.ts, or db/relations.ts:

npx typebase-io-cli codegen

See Actions to learn everything about writing actions.

Deploy

Deploy your server to the cloud:

npx typebase-io-cli deploy dev

On first run, the CLI will ask you to:

1. Choose a deployment provider (Vercel, Cloudflare Workers, or Deno Deploy)
2. Log in to that provider
3. Set up a PostgreSQL database (via Neon)

After setup, running npx typebase-io-cli deploy dev is a single command. The CLI saves your server URL to .env as TYPEBASE_APP_URL_DEV (deploying prod uses TYPEBASE_APP_URL instead, so both can coexist).

See Deploy for the full deployment reference.

Call it from your frontend

Pick your framework to learn how to set up the client and start calling your actions with full type safety: