Scaffold Service

About

How to scaffold a new service on Tawa using `tawa sample` templates.

Skill Content

This is the raw markdown that gets installed as a Claude Code command.

# Scaffold Service

## What this skill covers
How to scaffold a new service on Tawa using `tawa sample` templates.

## Available Templates

| Template | Command | What You Get |
|----------|---------|-------------|
| Express API | `tawa sample --api my-svc` | TypeScript Express API, Vitest, health endpoint |
| Next.js App | `tawa sample --nextjs my-app` | Next.js 14 standalone, Bio-ID auth wired up |
| Static Site | `tawa sample --static my-site` | HTML/CSS served by nginx |

## Step-by-Step

### 1. Scaffold
```bash
tawa sample --api my-new-service    # or --nextjs for a web app
cd my-new-service
```

### 2. Review catalog-info.yaml

Every scaffold starts with the minimal catalog. Extend it for what you need:

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-new-service
  description: What this service does
  annotations:
    insureco.io/framework: express       # or nextjs, hono, fastify, worker
    insureco.io/pod-tier: nano           # start here — upgrade when you have load data
    insureco.io/health-endpoint: /health # REQUIRED
spec:
  type: service
  lifecycle: production
  owner: my-org                          # your org slug

  # ── Add a database ──────────────────────────────────────────────────────────
  databases:
    - type: mongodb    # → MONGODB_URI injected automatically

  # ── Enable user login (Bio-ID OAuth) ────────────────────────────────────────
  # WITHOUT this, BIO_CLIENT_ID and BIO_CLIENT_SECRET are never injected.
  # Adding bio-id to internalDependencies is NOT the same thing — don't do that.
  auth:
    mode: sso          # → BIO_CLIENT_ID + BIO_CLIENT_SECRET injected on every deploy

  # ── Expose public API routes ────────────────────────────────────────────────
  routes:
    - path: /api/my-service/data
      methods: [GET, POST]
      auth: required
      gas: 1

  # ── Call other platform services ────────────────────────────────────────────
  internalDependencies:
    - service: septor      # → SEPTOR_URL
```

### 3. Run preflight
```bash
tawa preflight    # catches config issues before you waste a build
```

### 4. Deploy
```bash
tawa deploy --watch              # sandbox
tawa deploy --prod               # production
```

## Next.js with Auth Checklist

If you used `tawa sample --nextjs` and need login working:

- [ ] `spec.auth: mode: sso` is in catalog-info.yaml
- [ ] Callback is at `/api/auth/callback` (exactly — no variations)
- [ ] `BioAuth.fromEnv()` reads from env vars, not hardcoded values
- [ ] Every API route passes `request` to `getAuthUser(request)` — not `getAuthUser()`
- [ ] Only the root/dashboard page auto-redirects on 401 — sub-pages show a login button
- [ ] Run `/tawa-auth` for the full Next.js auth implementation pattern

## Key Facts
- `metadata.name` becomes your hostname: `my-svc.tawa.insureco.io`
- You do NOT need a Dockerfile — the builder generates one
- `spec.auth` is the ONLY way to get `BIO_CLIENT_ID` injected — `internalDependencies: bio-id` won't do it
- `BIO_ID_URL` is always injected — no declaration needed
- See tawa.insureco.io/reference/catalog-info for the full catalog reference

Install

Copy the skill content and save it to:

~/.claude/commands/tawa-scaffold.md

Details

Format

Command

Category

platform

Version

1.0.95085

Tokens

~785

Updated

2026-06-24