The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the KrabiClaw listing page.
Multi-tenant platform SaaS. Nuxt 5 nightly + Nitro 3 + Cloudflare Workers + D1.
Package manager: yarn only. Never npm or pnpm.
| Command | What it does |
|---|---|
yarn dev | Nuxt development server with HMR and locally emulated Cloudflare bindings at http://localhost:3000. |
yarn local:setup | The only local setup entry point: migrate D1, refresh fixtures, create the local developer account, and verify the result. |
yarn dev:worker | Build and run the production-like Worker locally with Wrangler at http://localhost:3000. |
yarn dev:worker:start | Run the existing .output Worker build locally without rebuilding it. |
yarn build | Production build → .output/ |
yarn db:generate | Generate a new migrations/*.sql file from server/db/schema.ts |
yarn drizzle:check | Verify server/db/schema.ts hasn't drifted from the live D1 schema |
yarn stripe:listen | Forward Stripe webhooks to localhost (local dev only) |
yarn canary:prod | Production-safe authenticated browser canary (read-only checks). |
yarn canary:notifications | Production provider-level email/WhatsApp notification canary. |
Real-send production canaries are intentionally off on normal main deploys to avoid
accidental email/WhatsApp spend on every merge. To run them on demand, use the GitHub
Actions workflow Production Real-Send Canaries and choose whether to send:
That workflow always runs production smoke first, then only sends the real canaries you explicitly selected for that run.
See docs/notification-testing.md for the full policy on log-only vs live email/WhatsApp testing, production-safe verification, and which public submission paths send for real in production.
The repository uses Node.js 24.18.1. Use the exact version declared in
.nvmrc before installing dependencies. When changing Node, follow the
Node runtime upgrade runbook so
local development, CI, type definitions, and Worker builds move together.
Yarn accepts new direct and transitive package releases only after seven days.
Routine yarn add and yarn up commands apply this rule automatically. CI
installs the package graph immutably and rechecks registry metadata in its
hardened job.
For an urgent reviewed security fix, update only the affected package:
Record the advisory and the reason for bypassing the wait in the pull request.
Do not add a package to npmPreapprovedPackages or disable the age gate in
.yarnrc.yml.
Copy .env.example to .env and fill in values. Required for local dev:
The command is safe to repeat. It leaves local D1 at the current migration, fixture, credential, and foreign-key baseline, then prints the one local developer login:
This localhost-only account is a member of every curated tenant and can access the platform dashboard. The password is generated on each setup run, printed once, and stored only as a hash in local D1. A repeated setup deletes existing local sessions, so sign in again with the newly printed password afterward.
App at http://localhost:3000.
yarn dev is the normal application-development loop. Nitro reads the bindings
declared in wrangler.toml, emulates local D1/KV/R2 resources, and preserves
Nuxt hot module replacement. It never resets D1. Run
corepack yarn local:setup when you want to restore local D1 from a production
snapshot.
Open tenant dashboards from the dashboard UI instead of guessing their URLs.
When a route must be constructed manually, the segment named siteSlug is the
site's subdomain, not its slug. Kikuzuki therefore uses
/dashboard/kikuzuki-krabi-thailand/sites/kikuzuki-krabi-thailand, not
/dashboard/kikuzuki-krabi-thailand/sites/kikuzuki.
For production-runtime browser verification, use the generated Worker locally.
Wrangler reads .env and .dev.vars using its documented local-development
behavior.
For a production-like local Worker:
After a successful build, yarn dev:worker:start restarts that same .output
without rebuilding. Source edits are not compiled into .output automatically;
use yarn dev for the normal HMR editing loop.
Playwright applies the local D1 schema, clears disposable E2E artifacts, restores
a production snapshot, provisions verified synthetic Better Auth accounts, builds the
Cloudflare Worker, and starts it under local workerd. Authenticated tests sign
in through Better Auth with a random password generated inside the Playwright
process; no email inbox or authentication bypass route is involved. Those test
credentials are not a second manual login path. Use the local developer account
printed by corepack yarn local:setup for browser work.
Local tenant tests use a shared-host routing contract: the browser targets
localhost and the test helper supplies x-preview-tenant for the selected
fixture. Deployed preview and staging use direct first-level tenant aliases
instead. This is the authoritative local browser path; do not rely on direct
*.localhost navigation for Worker browser verification.
Deployment follows the branches in .github/workflows/ci.yml:
staging deploy the staging Worker once, apply staging migrations,
provision fixtures/auth once, and run the full Playwright suite with two workers.staging to main release PR reuses the checks attached to its exact
staging head without another deployment or test cycle.staging to main merge deploys the production Worker, applies
production migrations, and runs read-only production browser smoke.CI invokes native Wrangler commands only in the matching branch job. See docs/operations/release-flow.md.
The Zaraz GA4 Backfill Plan workflow is read-only and accepts only preview or
staging targets. It reads the target D1 connections and the current zone-level
Zaraz configuration, then emits a plan; it never applies a Zaraz PUT and has
no production operator path.
During an incident, use Cloudflare's deployment history to restore the last
known-good production deployment without changing D1 data. Then land the source
fix through staging and main and repeat the browser gates.
Production secrets live in the Cloudflare dashboard → Workers & Pages → krabiclaw → Settings → Variables.
Set protected internal job secrets with Wrangler:
CRON_SECRET protects internal scheduled endpoints. Local commands read their configuration from .env; deployed Workers use Cloudflare secrets and the variables in wrangler.toml.
MCP reconnect triage and Cloudflare auth debugging are documented in docs/observability.md.
The mandatory deployed-browser release gate and outage recovery rules are documented in docs/operations/release-and-outage-prevention.md.
Database schema changes must follow the canonical migration workflow in docs/database/migrations.md. server/db/schema.ts is the only schema source of truth.
Copy the whsec_... signing secret it outputs into .env as STRIPE_WEBHOOK_SECRET. Swap back to the production webhook secret before deploying.