Quickstart ​

Requires Node.js >= 18.14.1.

Using a coding agent?

See the Agent Quickstart for a single page you can paste into your agent's chat.

Install the CLI ​

bash
npm install -g teenybase
bash
# no install needed, use npx teeny for all commands

Create a project ​

bash
teeny create my-app
cd my-app
bash
npx teeny create my-app
cd my-app

This scaffolds a project with a default teenybase.ts, worker entry point, dev secrets (.dev.vars), and Cloudflare config. It also runs npm install.

The default config ​

The scaffolded teenybase.ts comes with a users table that includes sign-up, login, JWT auth, and row-level security. You edit this file to add tables, fields, rules, OAuth providers, email config, and actions.

For example, adding a posts table:

ts
import { DatabaseSettings, TableAuthExtensionData, TableRulesExtensionData } from 'teenybase'
import { baseFields, authFields, createdTrigger, updatedTrigger } from 'teenybase/scaffolds/fields'

export default {
  appUrl: 'http://localhost:8787',
  jwtSecret: '$JWT_SECRET',

  tables: [
    {
      name: 'users',
      // ... (scaffolded by teeny create)
    },
    {
      name: 'posts',                                        // add this table
      autoSetUid: true,
      fields: [
        ...baseFields,
        { name: 'title', type: 'text', sqlType: 'text' },
        { name: 'body', type: 'text', sqlType: 'text' },
        { name: 'author', type: 'text', sqlType: 'text' },
        { name: 'published', type: 'bool', sqlType: 'boolean', default: '0' },
      ],
      triggers: [createdTrigger, updatedTrigger],
      extensions: [
        {
          name: 'rules',
          listRule: 'published == true',
          viewRule: 'published == true',
          createRule: 'auth.uid == author',
          updateRule: 'auth.uid == author',
          deleteRule: 'auth.uid == author',
        } as TableRulesExtensionData,
      ],
    },
  ],
} satisfies DatabaseSettings

See the Config Reference for all options.

Deploy locally ​

bash
teeny deploy --local
teeny dev
bash
npx teeny deploy --local
npx teeny dev

deploy --local generates migrations from your config and applies them to a local SQLite database. dev starts the API server at http://localhost:8787.

Available endpoints:

  • http://localhost:8787/api/v1/health (health check)
  • http://localhost:8787/api/v1/doc/ui (Swagger UI)
  • http://localhost:8787/api/v1/pocket/ (admin panel)

When you change teenybase.ts, run teeny deploy --local again to apply the changes, then restart teeny dev.

Deploy to Teenybase Cloud ​

Register a free account (once):

bash
teeny register
bash
npx teeny register

Create production secrets:

bash
cp .dev.vars .prod.vars

Open .prod.vars and replace every value with a strong random string. Generate one with openssl rand -base64 32. These are used for JWT signing and admin access.

Set appUrl in teenybase.ts to your frontend URL (e.g. https://myapp.com), or to the backend URL if you don't have a frontend yet. You can check your backend URL with teeny status after deploying.

Deploy:

bash
teeny deploy --remote
bash
npx teeny deploy --remote

The first deploy uploads your .prod.vars automatically. For later secret changes:

bash
teeny secrets --remote --upload
bash
npx teeny secrets --remote --upload

Check your live URL:

bash
teeny status
bash
npx teeny status

Test it ​

Create a user:

bash
curl -X POST http://localhost:8787/api/v1/table/users/auth/sign-up \
  -H 'Content-Type: application/json' \
  -d '{"username":"alice","email":"alice@test.com","password":"secret123","name":"Alice"}'

The response includes a token (JWT) and a record with the user's id.

Create a post (replace YOUR_TOKEN and YOUR_USER_ID from the sign-up response):

bash
curl -X POST http://localhost:8787/api/v1/table/posts/insert \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer YOUR_TOKEN' \
  -d '{"values":{"title":"Hello World","body":"My first post","author":"YOUR_USER_ID","published":true},"returning":"*"}'

List published posts (no auth needed):

bash
curl http://localhost:8787/api/v1/table/posts/select

For production, replace http://localhost:8787 with the URL from teeny status.

Next steps ​