Getting Started

Prerequisites

Using an AI coding agent

Typebase ships an AI Skill: a single SKILL.md that teaches your agent (Claude Code, Cursor, and others) the whole mental model, file layout, CLI commands, and common pitfalls. With it installed, the agent can scaffold actions, edit the schema, wire up auth, and deploy without re-reading the docs each time.

Install it with the skills CLI from skills.sh:

npx skills add typebase-io/monorepo

Then just tell your agent what to build. See the AI Skill page for manual installation and more detail. The rest of this guide is the manual path.

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, e.g. npm run typebase init. The script is optional: because the CLI is installed as a local dev dependency, npx typebase-io-cli <command> works without it (that's the form used throughout these docs). Either way, any teammate who clones the repo and runs npm install gets 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.

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

Read the Client overview for a quick tour of what the client offers, or jump straight to your framework's integration guide for full setup: