Scaffold Service

About

Walks through the complete flow of creating a new service on Tawa: from tawa sample template selection, through catalog-info.yaml customization, preflight checks, and deployment. Covers all four templates (static, API, Next.js, MGA) and monorepo setup with .tawa.yaml configuration.

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 |
|----------|---------|-------------|
| Static Site | `tawa sample --static my-site` | HTML/CSS served by nginx, no build step |
| Express API | `tawa sample --api my-svc` | TypeScript Express API, Vitest, Dockerfile, Helm chart |
| Next.js App | `tawa sample --nextjs my-app` | Next.js 14 standalone, Bio-ID auth, Dockerfile, Helm |
| Full MGA | `tawa sample --mga my-mga` | API + web portal + reporting, Bio-ID SSO, multi-service |

## Step-by-Step

### 1. Create your account (if not done)
```bash
npm install -g tawa
tawa signup          # Opens Bio-ID registration
tawa whoami          # Verify: [email protected] (org: my-org)
```

### 2. Scaffold
```bash
tawa sample --api my-new-service
cd my-new-service
```

### 3. Review generated files
Every template includes:
- `catalog-info.yaml` — pre-configured for the framework
- `package.json` — with build/start scripts
- Source code with health endpoint
- `.gitignore`

Templates may also include:
- `Dockerfile` — framework-specific (optional, builder can generate)
- `helm/` — Helm chart directory
- `.env.example` — environment variables reference

### 4. Customize catalog-info.yaml
```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-new-service           # This becomes your hostname
  description: My awesome service
  annotations:
    insureco.io/framework: express
spec:
  type: service
  lifecycle: production
  owner: my-org
  databases:
    - type: mongodb              # Add if you need a database
```

### 5. Run preflight
```bash
tawa preflight
```

### 6. Deploy
```bash
tawa deploy --watch               # Deploy to sandbox
# Verify at https://my-new-service.sandbox.tawa.insureco.io

tawa deploy --prod                # Deploy to production
```

## Monorepo Setup

For monorepos with multiple services:

```
my-monorepo/
  apps/
    frontend/
      catalog-info.yaml
      .tawa.yaml           # Points to shared Dockerfile, build context
    api/
      catalog-info.yaml
      .tawa.yaml
  helm/
    frontend/
    api/
  package.json
```

Each service's `.tawa.yaml`:
```yaml
dockerfile: Dockerfile
buildContext: ../..
helmChart: ../../helm/api
```

## Key Facts
- Every template comes with a pre-configured catalog-info.yaml
- The `metadata.name` field becomes your service hostname
- `spec.owner` is set automatically from your JWT when scaffolding
- You don't need a Dockerfile — the builder generates one from your framework annotation
- Run `tawa preflight` before your first deploy to catch config issues early

Install

Copy the skill content and save it to:

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

Details

Format

Command

Category

configure

Version

1.0.0

Tokens

~900

Updated

2026-02-13