Betterbase

The AI-Native Backend-as-a-Service Platform

Betterbase is an open-source alternative to Supabase, built with Bun for blazing-fast performance. It provides database, authentication, realtime subscriptions, storage, and serverless functions with sub-100ms local dev using Bun + SQLite.

Last Updated: 2026-03-21

Why Betterbase?

Traditional backend development is slow. You spend weeks setting up databases, authentication, APIs, and infrastructure before writing business logic. Betterbase changes that.

┌─────────────────────────────────────────────────────────────────────────┐
│                         BETTERBASE ARCHITECTURE                         │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│   ┌──────────────┐       ┌──────────────┐       ┌──────────────┐       │
│   │   Frontend   │──────▶│   Betterbase │──────▶│   Database   │       │
│   │   (React,    │       │     Core     │       │  (SQLite,    │       │
│   │    Vue,      │       │              │       │   Postgres,  │       │
│   │    Mobile)   │       │  ┌────────┐  │       │   MySQL,     │       │
│   └──────────────┘       │  │ Auth   │  │       │   Neon...)   │       │
│                          │  ├────────┤  │       └──────────────┘       │
│   ┌──────────────┐       │  │ Realtime│  │                               │
│   │  Serverless  │──────▶│  ├────────┤  │       ┌──────────────┐       │
│   │  Functions   │       │  │ Storage │  │       │  S3 Storage  │       │
│   └──────────────┘       │  ├────────┤  │       │  (R2, B2,    │       │
│                          │  │GraphQL │  │       │   MinIO...)   │       │
│   ┌──────────────┐       │  ├────────┤  │       └──────────────┘       │
│   │   Webhooks   │──────▶│  │  RLS   │  │                               │
│   └──────────────┘       │  ├────────┤  │       ┌──────────────┐       │
│                          │  │ Vector │  │       │   External   │       │
│   ┌──────────────┐       │  ├────────┤  │       │   Services   │       │
│   │    Logger    │──────▶│  │ Branch │  │       │  (AI APIs,   │       │
│   └──────────────┘       │  ├────────┤  │       │   OAuth...)   │       │
│                          │  │ Logger │  │       └──────────────┘       │
│                          │  └────────┘  │                               │
│                          └──────────────┘                               │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

Features

Betterbase provides a complete backend solution with enterprise-grade features:

Feature	Description
AI Context Generation	Automatic `.betterbase-context.json` generation for AI-assisted development
Sub-100ms Startup	Lightning-fast local development with `bun:sqlite`
Docker-less Dev	Run everything locally without containerization overhead
TypeScript First	Full type inference and strict mode throughout
BetterAuth Integration	Production-ready authentication out of the box
Realtime Subscriptions	WebSocket-based live data updates
Multi-Provider Support	PostgreSQL, MySQL (Planetscale), SQLite (Turso), Neon, Supabase
RLS (Row Level Security)	Built-in policy engine for fine-grained access control
Serverless Functions	Deploy custom API functions
Storage API	S3-compatible object storage
Image Transformations	On-the-fly image resizing, cropping, and format conversion
Webhooks	Event-driven architecture with signed payloads
Vector Search	pgvector-powered similarity search with embeddings support
Branching/Preview Environments	Create isolated development environments for each branch
Auto-REST	Automatic CRUD route generation from Drizzle schema
GraphQL	GraphQL API with schema generation and subscriptions
Magic Link Auth	Passwordless authentication via email magic links
MFA	Multi-factor authentication support
Phone Auth	Phone number verification via SMS/OTP
Project Templates	Base and Auth templates for quick project initialization
Request Logging	Built-in request logging with file transport

Quick Start

Installation

Install the Betterbase CLI globally:

bun install -g @betterbase/cli

Verify installation:

bb --version

Initialize a New Project

Create a new Betterbase project:

bb init my-project
cd my-project

This creates the following structure:

my-project/
├── betterbase.config.ts
├── drizzle.config.ts
├── src/
│   ├── db/
│   │   ├── schema.ts
│   │   └── migrate.ts
│   ├── functions/
│   ├── auth/
│   └── routes/
└── package.json

Configure Your Database

Edit betterbase.config.ts:

import { defineConfig } from '@betterbase/core'

export default defineConfig({
  database: {
    provider: 'sqlite', // or 'postgres', 'mysql', 'neon', 'turso', 'planetscale'
    connectionString: process.env.DATABASE_URL || 'file:./dev.db'
  },
  auth: {
    providers: ['email', 'github', 'google'],
    sessionExpiry: 7 * 24 * 60 * 60 * 1000 // 7 days
  },
  storage: {
    provider: 'local', // or 's3'
    bucket: 'uploads'
  },
  graphql: {
    enabled: true,
    playground: true
  }
})

Define Your Schema

Edit src/db/schema.ts:

import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core'
import { relations } from 'drizzle-orm'

export const users = sqliteTable('users', {
  id: text('id').primaryKey(),
  name: text('name').notNull(),
  email: text('email').notNull().unique(),
  createdAt: integer('created_at', { mode: 'timestamp' }).default(new Date())
})

export const posts = sqliteTable('posts', {
  id: text('id').primaryKey(),
  title: text('title').notNull(),
  content: text('content'),
  userId: text('user_id').references(() => users.id),
  createdAt: integer('created_at', { mode: 'timestamp' }).default(new Date())
})

export const usersRelations = relations(users, ({ many }) => ({
  posts: many(posts)
}))

export const postsRelations = relations(posts, ({ one }) => ({
  user: one(users, {
    fields: [posts.userId],
    references: [users.id]
  })
}))

Run the Development Server

bb dev

Your backend is now running at http://localhost:3000:

Endpoint	Description
`http://localhost:3000`	API root
`http://localhost:3000/rest/v1/*`	REST API
`http://localhost:3000/graphql`	GraphQL playground
`http://localhost:3000/api/auth/*`	Authentication endpoints
`http://localhost:3000/storage/*`	Storage endpoints
`http://localhost:3000/realtime/*`	Realtime subscriptions

Templates

BetterBase provides project templates for quick project initialization:

Base Template

The base template includes essential project structure:

bb init my-project --template base

Includes:

Basic Hono server setup
Database schema with users table
Authentication middleware
Storage routes
Health check endpoint

Auth Template

The authentication template includes full BetterAuth integration:

bb init my-project --template auth

Includes:

Pre-configured BetterAuth setup
Email/password authentication
Social OAuth providers (configurable)
Session management
Auth middleware examples

Architecture Overview

System Design

┌─────────────────────────────────────────────────────────────────────────┐
│                          CLIENT LAYER                                    │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐    │
│  │   Web SDK   │  │  React Hooks│  │   Mobile    │  │   GraphQL   │    │
│  │  @betterbase│  │   @betterbase│  │  SDK        │  │   Client    │    │
│  │   /client   │  │   /client   │  │             │  │             │    │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘    │
└─────────┼────────────────┼────────────────┼────────────────┼──────────┘
          │                │                │                │
          ▼                ▼                ▼                ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                          API GATEWAY (Hono)                             │
│  ┌─────────────────────────────────────────────────────────────────┐   │
│  │  REST API  │  GraphQL  │  Auth  │  Storage  │  Realtime  │  Webhooks│   │
│  └─────────────────────────────────────────────────────────────────┘   │
└─────────────────────────────────────────────────────────────────────────┘
          │
          ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      CORE SERVICES LAYER                                │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │  Query   │  │  Auth    │  │ Realtime │  │ Storage  │  │Function │  │
│  │  Engine  │  │ Service  │  │ Service  │  │ Service  │  │Runtime  │  │
│  │ (Drizzle)│  │(BetterAuth│  │(WebSocket)│ │  (S3)   │  │ (Bun)   │  │
│  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  └────┬─────┘  │
│       │            │            │            │            │         │
│       └────────────┴────────────┴────────────┴────────────┘         │
│                              │                                         │
└──────────────────────────────┼────────────────────────────────────────┘
                               ▼
┌─────────────────────────────────────────────────────────────────────────┐
│                      DATA LAYER                                         │
│  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐  │
│  │ SQLite   │  │PostgreSQL│  │  MySQL   │  │  Neon    │  │  Turso   │  │
│  │(dev)     │  │          │  │          │  │(serverless│  │(libSQL)  │  │
│  └──────────┘  └──────────┘  └──────────┘  └──────────┘  └──────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

Package Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                        TURBOREPO MONOREPO                              │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                     @betterbase/cli                              │   │
│  │  CLI tool with 17 commands for development and deployment       │   │
│  │  init, dev, migrate, auth, auth add-provider, generate,          │   │
│  │  function, graphql, login, rls, rls test, storage,              │   │
│  │  webhook, branch                                                 │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                     @betterbase/client                           │   │
│  │  TypeScript SDK for frontend integration                         │   │
│  │  Auth, Query Builder, Realtime, Storage, Errors                 │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                     @betterbase/core                             │   │
│  │  Core backend engine with all server-side functionality         │   │
│  │  Database, Auth, GraphQL, RLS, Storage, Webhooks, Functions,     │   │
│  │  Vector Search, Branching, Auto-REST, Logger, Realtime          │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                     @betterbase/shared                           │   │
│  │  Shared utilities, types, and constants across all packages      │   │
│  │  Types, Errors, Constants, Utils                                 │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                         │
│  ┌──────────────────────────────────────────────────────────────────┐   │
│  │                     templates/                                   │   │
│  │  Project templates for quick initialization                      │   │
│  │  base, auth                                                     │   │
│  └──────────────────────────────────────────────────────────────────┘   │
│                                                                         │
└─────────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────────┐ │ TURBOREPO MONOREPO │ ├─────────────────────────────────────────────────────────────────────────┤ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ @betterbase/cli │ │ │ │ CLI tool with 12 commands for development and deployment │ │ │ │ init, dev, migrate, auth, generate, function, graphql, login, │ │ │ │ rls, storage, webhook, branch │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ @betterbase/client │ │ │ │ TypeScript SDK for frontend integration │ │ │ │ Auth, Query Builder, Realtime, Storage │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │ │ │ @betterbase/core │ │ │ │ Core backend engine with all server-side functionality │ │ │ │ Database, Auth, GraphQL, RLS, Storage, Webhooks, Functions │ │ │ └──────────────────────────────────────────────────────────────────┘ │ │ │ │ ┌──────────────────────────────────────────────────────────────────┐ │

│ │ └─────────────────────────────────────────────────────────────────────────┘


---

## Technology Stack

| Technology | Purpose | Why |
|------------|---------|-----|
| **Bun** | Runtime | 3x faster than Node.js, native TypeScript support, built-in bundler |
| **Hono** | Web Framework | Fast, lightweight, works on any runtime (Cloudflare Workers, Deno, Bun) |
| **Drizzle ORM** | Database | Type-safe, lightweight, SQL-like syntax, migrations built-in |
| **BetterAuth** | Authentication | Extensible, secure, 30+ providers, session management |
| **Pothos + graphql-yoga** | GraphQL | Type-safe GraphQL schema builder with modern features |
| **Turborepo** | Monorepo | Efficient caching, parallel builds, remote caching |
| **AWS S3 SDK** | Storage | Industry-standard object storage compatibility |
| **Zod** | Validation | TypeScript-first schema validation |

### Configuration Options

BetterBase can be configured using `betterbase.config.ts`:

```typescript
import { defineConfig } from '@betterbase/core';

export default defineConfig({
  // Auto-REST: Automatic CRUD route generation
  autoRest: {
    enabled: true,
    excludeTables: ['internal_logs', 'migrations'],
  },
  
  // Storage policies for access control
  storage: {
    policies: [
      {
        bucket: 'avatars',
        operation: 'upload',
        expression: 'auth.uid() != null', // Allow authenticated users
      },
      {
        bucket: 'avatars',
        operation: 'download',
        expression: 'true', // Allow public read
      },
    ],
  },
  
  // Branching: Preview Environments configuration
  branching: {
    enabled: true,
    maxPreviews: 10,
    defaultSleepTimeout: 3600, // seconds
  },
  
  // Vector search configuration
  vector: {
    enabled: true,
    provider: 'openai',
    model: 'text-embedding-3-small',
    dimensions: 1536,
  },
});

Environment Variables

Variable	Description	Default
`PORT`	Server port	`3000`
`NODE_ENV`	Environment (development/production)	`development`
`DB_PATH`	SQLite database path	`local.db`
`DATABASE_URL`	PostgreSQL/MySQL connection string	—
`STORAGE_PROVIDER`	Storage provider (s3, r2, backblaze, minio)	`s3`
`STORAGE_BUCKET`	Default storage bucket name	`storage`
`STORAGE_ALLOWED_MIME_TYPES`	Comma-separated allowed MIME types	—
`STORAGE_MAX_FILE_SIZE`	Maximum file size in bytes	10485760
`SMTP_HOST`	SMTP server host	—
`SMTP_PORT`	SMTP server port	587
`SMTP_USER`	SMTP username	—
`SMTP_PASS`	SMTP password	—
`SMTP_FROM`	SMTP from email address	—
`TWILIO_ACCOUNT_SID`	Twilio Account SID	—
`TWILIO_AUTH_TOKEN`	Twilio Auth Token	—
`TWILIO_PHONE_NUMBER`	Twilio phone number	—

CLI Reference

The Betterbase CLI (bb) provides 17 commands for development and deployment:

Core Commands

`bb init [name]`

Initialize a new Betterbase project.

# Create in current directory
bb init

# Create in specific directory
bb init my-project

# With template
bb init my-project --template auth

`bb dev`

Start the development server with hot reload.

# Default port (3000)
bb dev

# Custom port
bb dev --port 8080

# With specific config
bb dev --config production.config.ts

`bb migrate`

Run database migrations.

# Generate migration from schema changes
bb migrate generate my-migration

# Apply pending migrations
bb migrate up

# Rollback last migration
bb migrate down

# Reset database (warning: destructive)
bb migrate reset

# Preview migration changes
bb migrate preview

# Run in production mode
bb migrate production

Authentication

`bb auth setup`

Setup and configure BetterAuth.

# Setup authentication
bb auth setup

`bb auth add-provider`

Add OAuth provider to your project.

# Add OAuth provider
bb auth add-provider github

# Available providers: google, github, discord, apple, microsoft, twitter, facebook
bb auth add-provider google
bb auth add-provider discord

Code Generation

`bb generate`

Generate types, CRUD operations, and more.

# Generate TypeScript types
bb generate types

# Generate CRUD operations
bb generate crud

# Generate everything
bb generate all

GraphQL

`bb graphql`

GraphQL schema management.

# Generate GraphQL schema from database
bb graphql generate

# Open GraphQL Playground
bb graphql playground

# Export schema as SDL
bb graphql export

RLS (Row Level Security)

`bb rls`

Manage Row Level Security policies.

# Create new RLS policy
bb rls create --table posts --name users-own-posts --command SELECT

# List all RLS policies
bb rls list

# Disable RLS for a table
bb rls disable --table posts

# Enable RLS for a table
bb rls enable --table posts

# Test RLS policies
bb rls test --table posts

Storage

`bb storage`

Manage file storage.

# Initialize storage
bb storage init

# List buckets
bb storage list

# List objects in bucket
bb storage buckets avatars

# Upload file
bb storage upload avatars avatar.png

Webhooks

`bb webhook`

Manage webhooks.

# Create webhook
bb webhook create --url https://example.com/hook --events "insert,update,delete"

# List webhooks
bb webhook list

# Test webhook
bb webhook test my-webhook

# View webhook logs
bb webhook logs my-webhook

Serverless Functions

`bb function`

Manage serverless functions.

# Create new function
bb function create my-function

# Run function in development mode
bb function dev my-function

# Build function
bb function build my-function

# Deploy function
bb function deploy my-function

# List all functions
bb function list

# View function logs
bb function logs my-function

Branching (Preview Environments)

`bb branch`

Manage preview environments (branches) for isolated development.

# Create a new preview environment
bb branch create my-feature

# List all preview environments
bb branch list

# Delete a preview environment
bb branch delete my-feature

# Check branch status
bb branch status my-feature

# Wake a sleeping preview
bb branch wake my-feature

# Sleep a preview to save resources
bb branch sleep my-feature

Authentication (User Management)

`bb login`

Manage user authentication.

# Login user
bb login --email user@example.com

# Logout user
bb logout

# Get current session
bb login status

Client SDK

Install the client SDK:

bun add @betterbase/client

Initialization

import { createClient } from '@betterbase/client'

const client = createClient({
  baseUrl: 'http://localhost:3000',
  auth: {
    persistSession: true,
    autoRefreshToken: true
  }
})

Authentication

Sign Up

const { data, error } = await client.auth.signUp({
  email: 'user@example.com',
  password: 'secure-password',
  name: 'John Doe'
})

if (error) {
  console.error('Signup failed:', error.message)
} else {
  console.log('User created:', data.user)
}

Sign In

const { data, error } = await client.auth.signInWithPassword({
  email: 'user@example.com',
  password: 'secure-password'
})

if (error) {
  console.error('Login failed:', error.message)
} else {
  console.log('Logged in:', data.session)
}

Sign In with Provider

// GitHub OAuth
const { data, error } = await client.auth.signInWithOAuth({
  provider: 'github'
})

// Google OAuth
const { data, error } = await client.auth.signInWithOAuth({
  provider: 'google'
})

Sign Out

await client.auth.signOut()

Get Current User

const { data: { user }, error } = await client.auth.getUser()

if (user) {
  console.log('Current user:', user)
}

Query Builder

Select

// Get all posts
const { data: posts, error } = await client
  .from('posts')
  .select()

// Select with filters
const { data: posts, error } = await client
  .from('posts')
  .select('id, title, content, user:users(name)')
  .eq('published', true)
  .order('createdAt', { ascending: false })
  .limit(10)

// Single record
const { data: post, error } = await client
  .from('posts')
  .select()
  .eq('id', 'post-123')
  .single()

Insert

const { data, error } = await client
  .from('posts')
  .insert({
    title: 'My New Post',
    content: 'Post content here',
    userId: 'user-123'
  })

Update

const { data, error } = await client
  .from('posts')
  .update({
    title: 'Updated Title'
  })
  .eq('id', 'post-123')

Realtime Subscriptions

// Subscribe to table changes
const channel = client.channel('public:posts')

channel
  .on('postgres_changes', { event: 'INSERT', schema: 'public', table: 'posts' }, 
    (payload) => {
      console.log('New post:', payload.new)
    }
  )
  .on('postgres_changes', { event: 'UPDATE', schema: 'public', table: 'posts' },
    (payload) => {
      console.log('Updated post:', payload.new)
    }
  )
  .on('postgres_changes', { event: 'DELETE', schema: 'public', table: 'posts' },
    (payload) => {
      console.log('Deleted post:', payload.old)
    }
  )
  .subscribe()

// Unsubscribe when done
channel.unsubscribe()

Storage

Upload File

const { data, error } = await client
  .storage
  .upload('avatars', 'user-avatar.png', file)

Download File

const { data, error } = await client
  .storage
  .download('avatars', 'user-avatar.png')

Get Public URL

const { data: { url } } = client
  .storage
  .getPublicUrl('avatars', 'user-avatar.png')

Delete File

await client
  .storage
  .remove('avatars', 'user-avatar.png')

Deployment Options

Local Development

The easiest way to get started:

bb init my-project
cd my-project
bb dev

Uses SQLite by default for zero-configuration development.

Method	Endpoint	Description
`POST`	`/api/auth/signup`	Register new user
`POST`	`/api/auth/signin`	Sign in user
`POST`	`/api/auth/signout`	Sign out user
`GET`	`/api/auth/session`	Get current session
`POST`	`/api/auth/refresh`	Refresh session
`POST`	`/api/auth/magic-link`	Send magic link email
`GET`	`/api/auth/magic-link/verify`	Verify magic link
`POST`	`/api/auth/otp/send`	Send OTP
`POST`	`/api/auth/otp/verify`	Verify OTP
`POST`	`/api/auth/mfa/enable`	Enable MFA
`POST`	`/api/auth/mfa/verify`	Verify MFA
`POST`	`/api/auth/mfa/disable`	Disable MFA
`POST`	`/api/auth/mfa/challenge`	MFA challenge
`POST`	`/api/auth/phone/send`	Send SMS verification
`POST`	`/api/auth/phone/verify`	Verify SMS code

Auto-REST (Automatic CRUD)

Method	Endpoint	Description
`GET`	`/api/:table`	List all records (paginated)
`GET`	`/api/:table/:id`	Get single record by ID
`POST`	`/api/:table`	Create new record
`PATCH`	`/api/:table/:id`	Update record
`DELETE`	`/api/:table/:id`	Delete record

Deploy to any Bun-compatible host:

# Build for production
bun run build

# Start production server
bun run start

Docker

Create a Dockerfile:

FROM oven/bun:1 AS base
WORKDIR /app

FROM base AS deps
COPY package.json bun.lock ./
RUN bun install --frozen-lockfile

FROM base AS builder
COPY --from=deps /app/node_modules ./node_modules
COPY . .
RUN bun run build

FROM base
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
COPY package.json ./

EXPOSE 3000
CMD ["bun", "run", "start"]

Build and run:

docker build -t betterbase-app .
docker run -p 3000:3000 betterbase-app

Cloud Providers

Provider	Deployment Method
Railway	`bb deploy` or Docker
Render	Docker
Fly.io	Docker
Vercel	Edge Functions
AWS Lambda	Serverless Framework
Cloudflare Workers	`wrangler`

Configuration

betterbase.config.ts

import { defineConfig } from '@betterbase/core'

export default defineConfig({
  // Database configuration
  database: {
    provider: 'sqlite',
    connectionString: process.env.DATABASE_URL || 'file:./dev.db',
    // For connection pooling (PostgreSQL)
    pool: {
      min: 2,
      max: 10
    }
  },

  // Authentication
  auth: {
    providers: ['email', 'github', 'google', 'discord'],
    email: {
      confirmEmail: true,
      passwordMinLength: 8
    },
    session: {
      expiry: 7 * 24 * 60 * 60 * 1000, // 7 days
      refreshTokenExpiry: 30 * 24 * 60 * 60 * 1000 // 30 days
    }
  },

  // Storage
  storage: {
    provider: 'local', // or 's3'
    local: {
      path: './storage'
    },
    s3: {
      bucket: process.env.S3_BUCKET,
      region: process.env.AWS_REGION,
      accessKeyId: process.env.AWS_ACCESS_KEY_ID,
      secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY
    },
    // File size limits (bytes)
    maxFileSize: 10 * 1024 * 1024, // 10MB
    allowedMimeTypes: ['image/*', 'application/pdf']
  },

  // GraphQL
  graphql: {
    enabled: true,
    playground: process.env.NODE_ENV !== 'production',
    depthLimit: 10,
    costLimit: 1000
  },

  // API Configuration
  api: {
    port: parseInt(process.env.PORT || '3000'),
    host: process.env.HOST || '0.0.0.0',
    cors: {
      origin: process.env.CORS_ORIGIN?.split(',') || ['http://localhost:3000'],
      credentials: true
    }
  },

  // Row Level Security
  rls: {
    enabled: true,
    auditLog: true
  },

  // Webhooks
  webhooks: {
    retry: {
      maxAttempts: 3,
      retryInterval: 1000
    }
  }
})

Environment Variables

# Database
DATABASE_URL=file:./dev.db
# Or for PostgreSQL
DATABASE_URL=postgres://user:password@localhost:5432/mydb

# Auth
AUTH_SECRET=your-secret-key-min-32-chars-long
AUTH_URL=http://localhost:3000

# Storage (S3)
STORAGE_PROVIDER=s3
STORAGE_REGION=us-east-1
STORAGE_ACCESS_KEY_ID=your-access-key
STORAGE_SECRET_ACCESS_KEY=your-secret-key
STORAGE_BUCKET=my-bucket

# API
PORT=3000
HOST=0.0.0.0
NODE_ENV=development

# CORS
CORS_ORIGIN=http://localhost:3000,http://localhost:5173

Database Providers

Betterbase supports multiple database providers for different use cases:

SQLite (Development)

Best for local development. Zero configuration required.

database: {
  provider: 'sqlite',
  connectionString: 'file:./dev.db'
}

PostgreSQL (Production)

Best for production deployments requiring full SQL capabilities.

database: {
  provider: 'postgres',
  connectionString: process.env.DATABASE_URL
}

Neon (Serverless PostgreSQL)

Best for serverless applications with automatic scaling.

database: {
  provider: 'neon',
  connectionString: process.env.NEON_CONNECTION_STRING
}

Turso (libSQL)

Best for edge deployments and distributed databases.

database: {
  provider: 'turso',
  connectionString: process.env.TURSO_DATABASE_URL,
  authToken: process.env.TURSO_AUTH_TOKEN
}

MySQL

Best for legacy applications or MySQL preference.

database: {
  provider: 'mysql',
  connectionString: process.env.MYSQL_URL
}

PlanetScale (MySQL-compatible)

Best for serverless MySQL with branch-based schema changes.

database: {
  provider: 'planetscale',
  connectionString: process.env.PLANETSCALE_URL
}

Authentication

Setup BetterAuth

Initialize authentication in your project:

bb auth setup

This creates src/auth/ with default configuration.

Configure Providers

Edit src/auth/index.ts:

import { betterAuth } from 'better-auth'
import { drizzleAdapter } from 'better-auth/adapters/drizzle'
import { db } from '../db'

export const auth = betterAuth({
  database: drizzleAdapter(db, {
    provider: 'sqlite' // or 'postgres', 'mysql'
  }),
  emailAndPassword: {
    enabled: true,
    requireEmailVerification: false
  },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID,
      clientSecret: process.env.GITHUB_CLIENT_SECRET
    },
    google: {
      clientId: process.env.GOOGLE_CLIENT_ID,
      clientSecret: process.env.GOOGLE_CLIENT_SECRET
    }
  },
  session: {
    expiresIn: 60 * 60 * 24 * 7, // 7 days
    updateAge: 60 * 60 * 24 // 1 day
  }
})

Row Level Security

Betterbase integrates with database RLS for secure data access:

// In your schema or via CLI
bb rls add \
  --table posts \
  --name users_own_posts \
  --command SELECT \
  --check "user_id = auth.uid()"

This ensures users can only access their own data.

Contributing

We welcome contributions! Please follow these steps:

Getting Started

Fork the repository
Clone your fork: git clone https://github.com/your-username/betterbase.git
Install dependencies: bun install
Create a branch: git checkout -b feature/my-feature

Development Setup

# Install dependencies
bun install

# Build all packages
bun run build

# Run tests
bun test

# Run linting
bun run lint

Project Structure

betterbase/
├── apps/
│   └── test-project/      # Example/test project
├── packages/
│   ├── cli/               # @betterbase/cli
│   ├── client/            # @betterbase/client
│   └── core/              # @betterbase/core
├── templates/             # Project templates
└── turbo.json             # Turborepo configuration

Code Style

We use Biome for code formatting and linting:

# Format code
bun run format

# Lint code
bun run lint

# Fix auto-fixable issues
bun run lint:fix

Testing

# Run all tests
bun test

# Run tests for specific package
bun test --filter=@betterbase/cli

# Run tests in watch mode
bun test --watch

Commit Messages

Follow Conventional Commits:

feat: add new feature
fix: resolve bug
docs: update documentation
refactor: restructure code
test: add tests
chore: maintenance

Submitting Changes

Push your branch: git push origin feature/my-feature
Open a Pull Request
Fill out the PR template
Wait for review

Code of Conduct

Our Pledge

In the interest of fostering an open and welcoming environment, we as contributors and maintainers pledge to make participation in our project and our community a harassment-free experience for everyone, regardless of age, body size, disability, ethnicity, gender identity and expression, level of experience, nationality, personal appearance, race, religion, or sexual identity and orientation.

Our Standards

Examples of behavior that contributes to creating a positive environment include:

Using welcoming and inclusive language
Being respectful of differing viewpoints and experiences
Gracefully accepting constructive criticism
Focusing on what is best for the community
Showing empathy towards other community members

Our Responsibilities

Project maintainers are responsible for clarifying the standards of acceptable behavior and are expected to take appropriate and fair corrective action in response to any instances of unacceptable behavior.

Enforcement

Instances of abusive, harassing, or otherwise unacceptable behavior may be reported by contacting the project team at conduct@betterbase.io. All complaints will be reviewed and investigated and will result in a response that is deemed necessary and appropriate to the circumstances.

Changelog

All notable changes to this project will be documented in this section.

[1.0.0] - 2026-03-19

Added

AI Context Generation: Automatic .betterbase-context.json generation for AI-assisted development
Branch Management: New bb branch command for creating isolated preview environments
Vector Search: pgvector-powered similarity search with embeddings support
Auto-REST: Automatic CRUD route generation from Drizzle schema
Enhanced CLI: Added 12 commands including branch, webhook management, and storage operations

Updated

Improved documentation with Last Updated timestamp
Verified all features against current codebase structure
Removed deprecated @betterbase/shared package references

Security

Improved webhook signature verification
Enhanced RLS policy engine

License

Betterbase is open source under the MIT License.

MIT License

Copyright (c) 2026 Betterbase

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

Community & Support

Get Help

Resource	Link
Documentation	docs.betterbase.io
Discord	discord.gg/betterbase
GitHub Issues	github.com/betterbase/betterbase/issues
Stack Overflow	stackoverflow.com/questions/tagged/betterbase

Stay Updated

Channel	Link
Twitter	@betterbase
Blog	blog.betterbase.io
Newsletter	subscribe.betterbase.io

Contribute

Resource	Link
GitHub	github.com/betterbase/betterbase
Contributing Guide	CONTRIBUTING.md
Good First Issues	github.com/betterbase/betterbase/labels/good%20first%20issue

Built with ❤️ using Weroperking

Website • Documentation • Discord • Twitter

Name		Name	Last commit message	Last commit date
Latest commit History 227 Commits
.devcontainer		.devcontainer
.github/workflows		.github/workflows
apps/test-project		apps/test-project
cli-auth-page		cli-auth-page
new-features-docs		new-features-docs
packages		packages
scripts		scripts
templates		templates
.gitignore		.gitignore
.gitkeep		.gitkeep
.npmignore		.npmignore
03_test_suite.md		03_test_suite.md
CODEBASE_MAP.md		CODEBASE_MAP.md
README.md		README.md
biome.json		biome.json
bun.lock		bun.lock
package.json		package.json
tsconfig.base.json		tsconfig.base.json
turbo.json		turbo.json

Folders and files

Latest commit

History

Repository files navigation

Betterbase

Why Betterbase?

Features

Quick Start

Installation

Initialize a New Project

Configure Your Database

Define Your Schema

Run the Development Server

Templates

Base Template

Auth Template

Architecture Overview

System Design

Package Architecture

Environment Variables

CLI Reference

Core Commands

bb init [name]

bb dev

bb migrate

Authentication

bb auth setup

bb auth add-provider

Code Generation

bb generate

GraphQL

bb graphql

RLS (Row Level Security)

bb rls

Storage

bb storage

Webhooks

bb webhook

Serverless Functions

bb function

Branching (Preview Environments)

bb branch

Authentication (User Management)

bb login

Client SDK

Initialization

Authentication

Sign Up

Sign In

Sign In with Provider

Sign Out

Get Current User

Query Builder

Select

Insert

Update

Realtime Subscriptions

Storage

Upload File

Download File

Get Public URL

Delete File

Deployment Options

Local Development

Auto-REST (Automatic CRUD)

Docker

Cloud Providers

Configuration

betterbase.config.ts

Environment Variables

Database Providers

SQLite (Development)

PostgreSQL (Production)

Neon (Serverless PostgreSQL)

Turso (libSQL)

MySQL

PlanetScale (MySQL-compatible)

Authentication

Setup BetterAuth

Configure Providers

`bb init [name]`

`bb dev`

`bb migrate`

`bb auth setup`

`bb auth add-provider`

`bb generate`

`bb graphql`

`bb rls`

`bb storage`

`bb webhook`

`bb function`

`bb branch`

`bb login`

Packages