---
name: build-app
description: Use when building a new Butterbase app from scratch, creating a full-stack application, or when the user asks to set up a complete backend with database, auth, and deployment
---

> **Prefer `/butterbase-skills:journey`** — for a fully guided multi-stage build with preflight, planning, deployment verification, and (optionally) hackathon submission. This one-shot skill remains for users who want the legacy linear setup.

# Build a Complete Butterbase App

This skill walks through all seven phases of building a production-ready Butterbase application — from provisioning a backend to deploying a live frontend. Follow each phase in order; later phases depend on artifacts (app_id, schema, RLS policies) produced by earlier ones.

> **Convention:** every JSON body below is the argument object for the tool named in its **Tool:** header. When the header reads `manage_schema` with `action: "apply"`, include `"action": "apply"` alongside the other fields when you make the call.

---

## Phase 1: Create the App

Use `init_app` to provision an isolated backend with its own database and auto-generated REST API.

**Tool:** `init_app`

```json
{
  "name": "my-blog"
}
```

**Returns:**
```json
{
  "app_id": "app_abc123",
  "api_base": "https://api.butterbase.ai/v1/app_abc123"
}
```

**Important:** Save `app_id` and `api_base` — every subsequent tool call requires `app_id`.

### Optional: Generate a Service API Key

If the user needs programmatic access (CI/CD pipelines, server-to-server calls, admin scripts), generate a service key now.

**Tool:** `manage_auth_config` with `action: "generate_service_key"`

```json
{
  "name": "Production Deploy Key"
}
```

> ⚠️ The full key (`bb_sk_...`) is shown **only once**. Store it securely — it cannot be retrieved again.

---

## Phase 2: Design & Apply Schema

Work with the user to understand their data model before writing any SQL. Ask:

- What are the primary entities (users, posts, products, orders)?
- Which tables are user-owned vs. shared/public?
- What relationships exist between tables (foreign keys)?
- Are there any boolean flags for public visibility (e.g. `published`, `is_public`)?

### Preview First with dry_run_schema

Always preview schema changes before applying them.

**Tool:** `manage_schema` with `action: "dry_run"`

```json
{
  "app_id": "app_abc123",
  "schema": {
    "tables": {
      "posts": {
        "columns": {
          "id": { "type": "uuid", "primaryKey": true, "default": "gen_random_uuid()" },
          "author_id": { "type": "uuid", "nullable": false },
          "title": { "type": "text", "nullable": false }
        }
      }
    }
  }
}
```

Review the generated SQL — make sure it matches intent before applying.

### Apply the Schema

**Tool:** `manage_schema` with `action: "apply"`

Below is a complete example for a **blog app** with posts and comments:

```json
{
  "app_id": "app_abc123",
  "schema": {
    "tables": {
      "posts": {
        "columns": {
          "id": { "type": "uuid", "primaryKey": true, "default": "gen_random_uuid()" },
          "author_id": { "type": "uuid", "nullable": false },
          "title": { "type": "text", "nullable": false },
          "body": { "type": "text" },
          "published": { "type": "boolean", "default": "false" },
          "created_at": { "type": "timestamptz", "default": "now()" }
        }
      },
      "comments": {
        "columns": {
          "id": { "type": "uuid", "primaryKey": true, "default": "gen_random_uuid()" },
          "post_id": { "type": "uuid", "nullable": false, "references": "posts.id" },
          "author_id": { "type": "uuid", "nullable": false },
          "body": { "type": "text", "nullable": false },
          "created_at": { "type": "timestamptz", "default": "now()" }
        }
      }
    }
  }
}
```

### Verify the Schema Was Applied

**Tool:** `manage_schema` with `action: "get"`

```json
{
  "app_id": "app_abc123"
}
```

Confirm every table and column is present before moving to Phase 3.

### Schema Tips

- Always include `id` as UUID with `gen_random_uuid()` default
- Always include `created_at` with `now()` default
- Use `author_id` / `user_id` UUID columns on user-owned tables — RLS will reference these
- Use `references: "table.column"` for foreign keys (cascades must be set carefully)
- `manage_schema` action `apply` is idempotent — safe to call again if schema is unchanged

---

## Phase 3: Secure Data with RLS

Row-Level Security (RLS) ensures users can only access their own data. This phase is **not optional** for any table that holds user-generated content.

### Enable User Isolation

Call `create_user_isolation_policy` for each user-owned table. This single call:
1. Enables RLS on the table
2. Creates a policy so users only see their own rows
3. Installs a BEFORE INSERT trigger to auto-populate the user column
4. Creates a service bypass policy for admin access

**Tool:** `manage_rls` with `action: "create_user_isolation"`

```json
{
  "app_id": "app_abc123",
  "table_name": "posts",
  "user_column": "author_id"
}
```

### Allow Public Reads (Optional)

For tables where some rows should be publicly visible (e.g. published blog posts), add `public_read_column`. This creates extra SELECT policies for both authenticated and anonymous users.

```json
{
  "app_id": "app_abc123",
  "table_name": "posts",
  "user_column": "author_id",
  "public_read_column": "published"
}
```

Repeat for every user-owned table. For the blog example:

```json
{
  "app_id": "app_abc123",
  "table_name": "comments",
  "user_column": "author_id"
}
```

### Test RLS Isolation

After applying policies, verify they work correctly by simulating user requests.

**Test SELECT as a specific user** — should only see that user's rows:

**Tool:** `select_rows`

```json
{
  "app_id": "app_abc123",
  "table": "posts",
  "as_role": "user",
  "as_user": "11111111-1111-1111-1111-111111111111"
}
```

**Test SELECT as anonymous** — should only see published/public rows (or nothing if no public policy):

```json
{
  "app_id": "app_abc123",
  "table": "posts",
  "as_role": "anon"
}
```

**Test INSERT as a specific user** — `author_id` should be auto-populated by the trigger (do not include it in `data`):

**Tool:** `insert_row`

```json
{
  "app_id": "app_abc123",
  "table": "posts",
  "data": {
    "title": "My First Post",
    "body": "Hello world!",
    "published": false
  },
  "as_role": "user",
  "as_user": "11111111-1111-1111-1111-111111111111"
}
```

Confirm the returned row has `author_id` set to `11111111-1111-1111-1111-111111111111` automatically.

### Verify All Policies

**Tool:** `manage_rls` with `action: "list"`

```json
{
  "app_id": "app_abc123"
}
```

Review the policy list and confirm every user-data table has at least one policy.

---

## Phase 4: Authentication

Butterbase uses OAuth 2.0 for end-user authentication. Users sign in via a provider (Google, GitHub, Discord, etc.) and receive a JWT to authenticate subsequent API calls.

### Configure an OAuth Provider

Built-in providers (google, github, discord, facebook, linkedin, microsoft, apple, x) only require three fields — URLs and scopes are auto-filled.

**Tool:** `manage_oauth` with `action: "configure"`

**Google example:**
```json
{
  "app_id": "app_abc123",
  "provider": "google",
  "client_id": "123456789.apps.googleusercontent.com",
  "client_secret": "GOCSPX-xxxxxxxxxxxxxxxxxxxxxxxx",
  "redirect_uris": ["https://api.butterbase.ai/auth/app_abc123/oauth/google/callback"]
}
```

**GitHub example:**
```json
{
  "app_id": "app_abc123",
  "provider": "github",
  "client_id": "Iv1.xxxxxxxxxxxxxxxx",
  "client_secret": "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "redirect_uris": ["https://api.butterbase.ai/auth/app_abc123/oauth/github/callback"]
}
```

**Redirect URI format:**
```
https://api.butterbase.ai/auth/{app_id}/oauth/{provider}/callback
```

Replace `{app_id}` and `{provider}` with real values. Register this exact URI in the OAuth provider's developer console.

### Setup Steps (per provider)

1. Go to the provider's developer console (Google Cloud Console, GitHub Settings → Developer applications, etc.)
2. Create a new OAuth app / client
3. Set the redirect URI to the Butterbase callback URL above
4. Copy the `client_id` and `client_secret`
5. Call `configure_oauth_provider` with those credentials

### Frontend Authentication Flow

Install the Butterbase SDK in the frontend:

```bash
npm install @butterbase/sdk
```

Initialize the client and trigger OAuth sign-in:

```typescript
import { createClient } from '@butterbase/sdk'

const client = createClient({
  appId: 'app_abc123',
  apiBase: 'https://api.butterbase.ai/v1/app_abc123'
})

// Initiate OAuth sign-in (redirects to provider)
await client.auth.signInWithOAuth({ provider: 'google' })

// After redirect back, get the current session
const { user, accessToken } = await client.auth.getSession()

// Use the access token in API calls — the SDK handles this automatically
const posts = await client.from('posts').select('*')
```

### Adjust JWT Token Lifetimes (Optional)

**Tool:** `manage_auth_config` with `action: "update_jwt"`

```json
{
  "app_id": "app_abc123",
  "accessTokenTtl": "15m",
  "refreshTokenTtlDays": 30
}
```

Short access tokens (15m) with longer refresh tokens (30 days) balance security and user experience.

---

## Phase 5: Backend Logic (Optional)

Deploy serverless functions for business logic that cannot run in the browser: sending emails, processing payments, calling third-party APIs with secrets, scheduled jobs, and more.

### Deploy a Function

**Tool:** `deploy_function`

**Critical rules:**
- Handler **must** be exported as `export async function handler`
- Handler **must** return a `new Response()` object — **never** return a plain object
- Context provides `db` (Postgres), `env` (encrypted env vars), `user` (authenticated user or null)

**HTTP function example:**
```json
{
  "app_id": "app_abc123",
  "name": "create-post",
  "description": "Create a new blog post and notify subscribers",
  "trigger": {
    "type": "http",
    "config": {
      "method": "POST",
      "path": "/create-post",
      "auth": "required"
    }
  },
  "code": "export async function handler(request, ctx) {\n  const { title, body } = await request.json();\n  if (!title) {\n    return new Response(JSON.stringify({ error: 'title is required' }), {\n      status: 400,\n      headers: { 'Content-Type': 'application/json' }\n    });\n  }\n  const result = await ctx.db.query(\n    'INSERT INTO posts (title, body, author_id) VALUES ($1, $2, $3) RETURNING *',\n    [title, body, ctx.user.id]\n  );\n  return new Response(JSON.stringify(result.rows[0]), {\n    status: 201,\n    headers: { 'Content-Type': 'application/json' }\n  });\n}"
}
```

**Cron function example** (runs daily at 9 AM UTC):
```json
{
  "app_id": "app_abc123",
  "name": "daily-digest",
  "description": "Send a daily digest email to subscribers",
  "trigger": {
    "type": "cron",
    "config": {
      "schedule": "0 9 * * *",
      "timezone": "UTC"
    }
  },
  "code": "export async function handler(request, ctx) {\n  const result = await ctx.db.query(\n    'SELECT * FROM posts WHERE created_at > NOW() - INTERVAL \\'24 hours\\''\n  );\n  // send digest email with result.rows...\n  return new Response(JSON.stringify({ sent: result.rows.length }), {\n    status: 200,\n    headers: { 'Content-Type': 'application/json' }\n  });\n}"
}
```

### Pass Secrets via Environment Variables

Never hardcode API keys. Pass them as `envVars`:

```json
{
  "app_id": "app_abc123",
  "name": "send-email",
  "envVars": {
    "SENDGRID_API_KEY": "SG.xxxxxxxxxxxxxxxx",
    "FROM_EMAIL": "noreply@example.com"
  },
  "trigger": { "type": "http", "config": { "method": "POST", "auth": "required" } },
  "code": "export async function handler(request, ctx) {\n  const apiKey = ctx.env.SENDGRID_API_KEY;\n  // use apiKey...\n  return new Response('ok', { status: 200 });\n}"
}
```

To rotate secrets without redeploying code, call `manage_function` with `action: "update_env"`.

### Test a Function

**Tool:** `invoke_function`

```json
{
  "app_id": "app_abc123",
  "function_name": "create-post",
  "method": "POST",
  "body": {
    "title": "Hello World",
    "body": "This is a test post."
  }
}
```

### Debug with Logs

If a function returns an unexpected response or error, check logs immediately.

**Tool:** `manage_function` with `action: "get_logs"`

```json
{
  "app_id": "app_abc123",
  "function_name": "create-post",
  "level": "error",
  "limit": 20
}
```

Logs include stack traces, duration, memory used, and status codes. Logs are retained for 7 days.

### RLS Behavior in Functions

| Invoked with | Role assigned | RLS enforced? |
|---|---|---|
| End-user JWT | `butterbase_user` | Yes — sees only user's data |
| Platform API key | `butterbase_service` | No — sees all data |
| Cron trigger | `butterbase_service` | No — sees all data |

---

## Phase 6: Deploy Frontend

Deploy the frontend as a static site. Butterbase hosts it on a CDN with SPA routing support.

### Step 1: Configure CORS

Allow the frontend domain to call the API.

**Tool:** `manage_app` with `action: "update_cors"`

```json
{
  "app_id": "app_abc123",
  "allowed_origins": [
    "http://localhost:3000",
    "https://my-app.pages.dev"
  ]
}
```

Add both local dev and production URLs. Update again after you know the final deployment URL.

### Step 2: Set Frontend Environment Variables

**Tool:** `manage_frontend` with `action: "set_env"`

```json
{
  "app_id": "app_abc123",
  "vars": {
    "VITE_API_BASE": "https://api.butterbase.ai/v1/app_abc123",
    "VITE_APP_ID": "app_abc123"
  }
}
```

Prefix variables for your framework:
- Vite: `VITE_`
- Next.js: `NEXT_PUBLIC_`
- Create React App: `REACT_APP_`

### Step 3: Build the Frontend

```bash
npm run build
```

This produces a `dist/` (Vite) or `out/` (Next.js static) folder.

### Step 4: Create Deployment & Get Upload URL

**Tool:** `create_frontend_deployment`

```json
{
  "app_id": "app_abc123",
  "framework": "react-vite"
}
```

**Returns:**
```json
{
  "deployment_id": "dep_xyz789",
  "uploadUrl": "https://s3.amazonaws.com/...",
  "expiresIn": 900
}
```

Save `deployment_id` and `uploadUrl`.

### Step 5: Zip and Upload

> ⚠️ **Windows warning:** Use Git Bash or WSL to create the zip. Windows built-in zip uses backslashes, which breaks MIME types and causes JS/CSS to be served as `text/html`.

```bash
# From the project root — use Git Bash on Windows
cd dist && zip -r ../frontend.zip . && cd ..
```

Upload the zip:

```bash
curl -X PUT "https://s3.amazonaws.com/..." \
  -H "Content-Type: application/zip" \
  --data-binary @frontend.zip
```

Replace the URL with the `uploadUrl` returned in the previous step.

### Step 6: Start the Deployment

**Tool:** `manage_frontend` with `action: "start_deployment"`

```json
{
  "app_id": "app_abc123",
  "deployment_id": "dep_xyz789"
}
```

This polls until the deployment reaches `READY` status (up to 5 minutes) and returns the live URL.

```json
{
  "deployment_id": "dep_xyz789",
  "url": "https://my-app.pages.dev",
  "status": "READY"
}
```

Visit the URL to verify the frontend is live.

### Step 7: Update CORS with Final URL

Once you have the live deployment URL, add it to CORS if it wasn't already included:

```json
{
  "app_id": "app_abc123",
  "allowed_origins": [
    "http://localhost:3000",
    "https://my-app.pages.dev"
  ]
}
```

### Framework Reference

| Framework | Build command | Zip folder | `framework` param |
|---|---|---|---|
| React + Vite | `npm run build` | `dist/` | `react-vite` |
| Next.js (static) | `next build && next export` | `out/` | `nextjs-static` |
| Plain HTML/CSS/JS | n/a | root | `static` |
| Other | varies | build output | `other` |

---

## Phase 7: Production Checklist

Before announcing the app as production-ready, verify each item:

- [ ] **1. CORS configured for production domain** — `update_cors` includes the live frontend URL (not just localhost)
- [ ] **2. RLS enabled on all user-data tables** — `manage_rls` (`action: "list"`) shows policies for every table holding user-generated content; no table is accidentally wide-open
- [ ] **3. OAuth redirect URIs point to production** — Provider developer consoles have the Butterbase callback URL registered; no localhost URIs are the only option in production
- [ ] **4. Frontend env vars set for production API URL** — `VITE_API_BASE` (or equivalent) points to `https://api.butterbase.ai/v1/{app_id}`, not a localhost URL
- [ ] **5. Error handling in all functions** — Every `deploy_function` handler returns appropriate HTTP status codes (400 for bad input, 401 for auth failures, 500 for unexpected errors) rather than throwing unhandled exceptions
- [ ] **6. JWT config reviewed** — `manage_auth_config` (`action: "update_jwt"`) has been called with intentional token lifetimes; access token TTL is appropriate for the security sensitivity of the app (default 15m is reasonable)
- [ ] **7. Storage quotas checked** — `manage_storage` (`action: "list"`) and app config reviewed; storage usage is within plan limits and `allowedContentTypes` are restricted to what the app actually needs
- [ ] **8. Functions tested with `invoke_function`** — Every HTTP function has been invoked with realistic payloads and edge cases (missing fields, invalid auth, large inputs) and returned correct responses
- [ ] **9. Frontend deployed and verified** — `manage_frontend` (`action: "list_deployments"`) shows a `READY` deployment; the live URL loads correctly in a browser and all API calls succeed
- [ ] **10. Monitoring and audit logs reviewed** — `query_audit_logs` shows no unexpected login failures or suspicious activity; `manage_function` (`action: "get_logs"`) shows no recurring errors in production traffic

---

## Quick Reference: Tool → Phase Mapping

| Phase | Tools Used |
|---|---|
| 1 — Create App | `init_app`, `manage_auth_config` (`generate_service_key`) |
| 2 — Schema | `manage_schema` (`dry_run`, `apply`, `get`) |
| 3 — RLS | `manage_rls` (`create_user_isolation`, `create_policy`, `enable`, `list`), `select_rows`, `insert_row` |
| 4 — Auth | `manage_oauth` (`configure`), `manage_auth_config` (`update_jwt`) |
| 5 — Functions | `deploy_function`, `invoke_function`, `manage_function` (`update_env`, `get_logs`, `list`, `delete`) |
| 6 — Frontend | `manage_app` (`update_cors`), `manage_frontend` (`set_env`, `start_deployment`, `list_deployments`), `create_frontend_deployment` |
| 7 — Production | `manage_rls` (`list`), `query_audit_logs`, `manage_function` (`get_logs`), `manage_storage` (`list`) |

---

## Common Mistakes to Avoid

**Schema**
- Do not drop and recreate tables to rename a column — use `manage_schema` (`action: "apply"`) with the new column name and migrate data separately
- Do not skip `action: "dry_run"` — always preview before applying

**RLS**
- Do not forget `manage_rls` (`action: "create_user_isolation"`) — a table without RLS is readable by all authenticated users
- Do not include `author_id` / `user_id` in INSERT bodies when a trigger is installed — it will be set automatically

**Functions**
- Do not return plain objects from handlers (`return { status: 200 }`) — always `return new Response(...)`
- Do not hardcode secrets in function code — use `envVars` and access via `ctx.env`

**Frontend**
- Do not create zips on Windows with the built-in tool — use Git Bash or WSL
- Do not forget to update CORS after deploying to the final URL

**Auth**
- Do not register `localhost` redirect URIs in the production OAuth app — keep dev and prod OAuth apps separate, or add both URIs to the same app