ShellBot Website#

Build and deploy micro apps and websites on Cloudflare Workers with production-grade design.

Arguments#

• Command: $0 ( create | deploy | domain | provision | secrets | status | teardown)
• Arg 1: $1 (template name, resource type, domain, etc.)
• Arg 2+: $2, $3, etc.
• All args: $ARGUMENTS

CommandScriptExamplecreate``scripts/create-project.sh``/shellbot-website create my-app --template react-hono``deploy``scripts/deploy.sh``/shellbot-website deploy --env production``domain``scripts/setup-domain.sh``/shellbot-website domain my-worker example.com``provision``scripts/provision-*.sh``/shellbot-website provision d1 my-db``secrets``scripts/manage-secrets.sh``/shellbot-website secrets put API_KEY``status``scripts/status.sh``/shellbot-website status --resources``teardown``scripts/teardown.sh``/shellbot-website teardown my-worker

Authentication#

Two authentication methods, checked in this order:

Method 1: API Token (recommended, required for agents/CI)#

Set CLOUDFLARE_API_TOKEN environment variable. This is the primary method — it takes precedence over OAuth if both are present.

If any command fails with authentication errors, tell user:

text

Get an API token from https://dash.cloudflare.com/profile/api-tokens
Use the "Edit Cloudflare Workers" template, or create a custom token with:
  Workers Scripts: Edit
  D1: Edit
  Workers KV Storage: Edit
  Workers R2 Storage: Edit
  Zone DNS: Edit (for custom domains)
Then: export CLOUDFLARE_API_TOKEN="your-token-here"

Method 2: OAuth via wrangler login (fallback for local use)#

If CLOUDFLARE_API_TOKEN is not set, attempt OAuth login:

bash

wrangler login

This opens a browser for Cloudflare OAuth. When running in an agent context:

1. Run wrangler login — it will print an authorization URL to stdout
2. Show the URL to the user and ask them to open it in their browser
3. The user authorizes in the browser, which redirects to localhost:8976
4. Wrangler receives the callback and stores OAuth tokens in ~/.wrangler/config/default.toml

Limitation: This only works when the agent runs on the user's local machine (the OAuth callback must reach localhost:8976). It will NOT work in remote/CI environments — use API token there.

After login, verify with:

bash

wrangler whoami

Auth check order in scripts#

All scripts check CLOUDFLARE_API_TOKEN first. If not set, they check if wrangler whoami succeeds (meaning OAuth tokens exist in ~/.wrangler/config/default.toml). If neither works, they error with instructions for both methods.

Optional: Account ID#

CLOUDFLARE_ACCOUNT_ID — auto-detected by wrangler. Set it to skip the account selection prompt when multiple accounts exist.

text

Find at: Dashboard → Overview → right sidebar → Account ID
Then: export CLOUDFLARE_ACCOUNT_ID="your-account-id"

Prerequisites#

• Node.js v20+
• Wrangler: npm install -g wrangler or use npx wrangler

Verify setup:

bash

wrangler whoami

Non-Interactive Design#

All scripts run fully non-interactively — no prompts, no user input required. This makes them safe for agent invocation. Destructive operations require explicit --force flags instead of confirmation prompts.

Quick Start#

bash

# 1. Scaffold from template (fully non-interactive, no deploy, no git init)
bash scripts/create-project.sh my-app

# 2. Local development
cd my-app && npm run dev

# 3. Deploy to Cloudflare
bash scripts/deploy.sh

# 4. Add custom domain
bash scripts/setup-domain.sh my-app example.com

# 5. Provision resources as needed
bash scripts/provision-d1.sh my-db --binding DB
bash scripts/provision-kv.sh my-cache --binding CACHE
bash scripts/provision-r2.sh my-assets --binding ASSETS

Project Scaffolding#

Default Templates#

Short NameTemplateBest Forreact-hono (default)react-router-hono-fullstack-templateFullstack apps with React Router 7 + Hono APInext``next-starter-templateNext.js apps on CF Workersbash

# Primary default (React Router + Hono)
bash scripts/create-project.sh my-app

# Use Next.js instead
bash scripts/create-project.sh my-app --template next

# Use any CF template by short name or full name
bash scripts/create-project.sh my-app --template astro-blog
bash scripts/create-project.sh my-app --template remix
bash scripts/create-project.sh my-app --template vite-react

See references/cf-templates.md for the full catalog of 36+ templates.

Custom Template URL#

bash

bash scripts/create-project.sh my-app --template-url https://github.com/user/repo

Deployment#

bash

# Deploy to production
bash scripts/deploy.sh

# Deploy to specific environment
bash scripts/deploy.sh --env staging
bash scripts/deploy.sh --env production

# Dry run (shows what would deploy)
bash scripts/deploy.sh --dry-run

# View deployments
wrangler deployments list

# Rollback to previous version
wrangler rollback [version-id]

The deploy.sh script pre-checks that wrangler config exists and CLOUDFLARE_API_TOKEN is set before deploying.

Custom Domains#

Three approaches to connect a custom domain to a CF Worker. See references/custom-domains.md for the full guide.

1. Automated Setup (Recommended)#

bash

# Domain must already be in your CF account
bash scripts/setup-domain.sh my-worker example.com

# With specific zone ID (skips lookup)
bash scripts/setup-domain.sh my-worker example.com --zone-id abc123

# Subdomain
bash scripts/setup-domain.sh my-worker app.example.com

2. Via wrangler.toml Routes#

toml

[[routes]]
pattern = "example.com/*"
zone_id = "your-zone-id"

3. Via Cloudflare Dashboard#

Workers & Pages → your worker → Settings → Domains & Routes → Add Custom Domain.

DNS Requirements#

• Domain must be in your Cloudflare account (orange-cloud proxied)
• SSL is automatic — no certificate management needed
• DNS propagation takes 1-5 minutes for proxied domains

Resource Provisioning#

D1 (SQL Database)#

bash

bash scripts/provision-d1.sh my-db --binding DB
# Creates database, outputs binding snippet for wrangler.toml
# Optional: --migration-file schema.sql (applies initial migration)

Common D1 operations:

bash

wrangler d1 execute my-db --command "SELECT * FROM users"
wrangler d1 execute my-db --file schema.sql
wrangler d1 execute my-db --local --command "..."  # Local dev
wrangler d1 migrations create my-db add-users
wrangler d1 migrations apply my-db

KV (Key-Value Store)#

bash

bash scripts/provision-kv.sh my-cache --binding CACHE
# Creates namespace, outputs binding snippet

R2 (Object Storage)#

bash

bash scripts/provision-r2.sh my-assets --binding ASSETS
# Creates bucket, outputs binding snippet

Queues#

bash

bash scripts/provision-queue.sh my-queue --binding QUEUE --type producer
# Creates queue, outputs producer/consumer binding snippets

Secrets Management#

bash

# Add a secret (non-interactive)
bash scripts/manage-secrets.sh put API_KEY "sk-..."

# List secrets
bash scripts/manage-secrets.sh list

# Delete a secret
bash scripts/manage-secrets.sh delete API_KEY

# Bulk upload from JSON
bash scripts/manage-secrets.sh bulk secrets.json

# Environment-specific
bash scripts/manage-secrets.sh put API_KEY "sk-..." --env production

Configuration#

Wrangler supports TOML and JSON/JSONC. If both exist, JSON takes precedence. Pick one.

Quick Reference (wrangler.toml)#

toml

name = "my-worker"
main = "src/index.ts"
compatibility_date = "2024-12-30"
compatibility_flags = ["nodejs_compat"]

[vars]
API_URL = "https://api.example.com"

[[d1_databases]]
binding = "DB"
database_name = "my-db"
database_id = "xxx"

[[kv_namespaces]]
binding = "CACHE"
id = "xxx"

[[r2_buckets]]
binding = "ASSETS"
bucket_name = "my-assets"

[env.production]
vars = { API_URL = "https://api.example.com" }

[env.staging]
vars = { API_URL = "https://staging-api.example.com" }

See references/wrangler-config.md for the full reference including JSONC format, static assets, and all binding types.

Frontend Design#

When building the frontend, apply these principles. Each links to a deep reference guide.

Typography#

→ See references/typography.md

Choose distinctive fonts (not Inter/Roboto). Use a modular type scale with clamp() for headings. Pair a display font with a body font. Use font-display: swap and fallback metric matching to prevent layout shift.

Color & Theme#

→ See references/color-and-contrast.md

Use OKLCH for perceptually uniform palettes. Tint neutrals toward your brand hue. Follow the 60-30-10 rule (neutrals / secondary / accent). Avoid pure black/white. Avoid the AI palette (cyan-on-dark, purple-blue gradients).

Layout & Space#

→ See references/spatial-design.md

Use a 4pt spacing system. Create rhythm through varied spacing. Use auto-fit grids. Avoid wrapping everything in cards. Embrace asymmetry.

Motion#

→ See references/motion-design.md

Only animate transform and opacity. Use exponential easing (quart/quint/expo). 100-150ms for feedback, 200-300ms for state changes, 300-500ms for layout. Always support prefers-reduced-motion.

Interaction#

→ See references/interaction-design.md

Design all 8 states (default, hover, focus, active, disabled, loading, error, success). Use :focus-visible for keyboard-only focus rings. Prefer optimistic UI and undo over confirmation dialogs.

Responsive#

→ See references/responsive-design.md

Mobile-first with min-width queries. Use container queries for components. Detect input method ( pointer: fine/coarse), not just screen size. Handle safe areas.

UX Writing#

→ See references/ux-writing.md

Specific verb + object for buttons. Every error message answers what/why/how-to-fix. Empty states are onboarding moments. Pick one term and stick with it.

The AI Slop Test#

If someone sees this interface and immediately thinks "AI made this" — that's the problem. Avoid: cyan-on-dark, purple gradients, glassmorphism everywhere, identical card grids, gradient text, dark mode with glowing accents. Make unexpected, intentional design choices.

Context Gathering#

Before doing design work, you MUST have confirmed design context:

1. Check loaded instructions for a Design Context section
2. Check .impeccable.md in project root
3. If neither exists, ask the user for: target audience, use cases, brand personality/tone

Troubleshooting#

IssueSolution"Not authenticated"Set CLOUDFLARE_API_TOKEN env var or run wrangler loginNode version errorRequires Node.js v20+No config foundRun from project root with wrangler.toml or wrangler.jsoncConfig changes ignoredJSON takes precedence over TOML if both existBinding not foundCheck wrangler config bindings match code referencesCustom domain not workingDomain must be proxied (orange cloud) in CF DNSSSL pendingWait 1-5 min for automatic certificate provisioning

Scripts & References#

Scripts#

ScriptPurposescripts/create-project.shScaffold project from CF templatesscripts/deploy.shDeploy worker with pre-checksscripts/setup-domain.shConfigure custom domain via CF APIscripts/provision-d1.shCreate D1 database + binding snippetscripts/provision-kv.shCreate KV namespace + binding snippetscripts/provision-r2.shCreate R2 bucket + binding snippetscripts/provision-queue.shCreate queue + binding snippetscripts/manage-secrets.shAdd/list/delete/bulk secretsscripts/status.shDeployment status, resources, logsscripts/teardown.shDelete worker + resources

References#

FileTopicreferences/cf-templates.mdAll 36+ CF quickstart templatesreferences/custom-domains.mdDomain setup, DNS, routes, SSLreferences/wrangler-config.mdFull wrangler.toml/jsonc referencereferences/typography.mdFont selection, scales, loadingreferences/color-and-contrast.mdOKLCH, palettes, dark modereferences/spatial-design.mdGrids, spacing, hierarchyreferences/motion-design.mdAnimation timing, easingreferences/interaction-design.mdStates, forms, focus, loadingreferences/responsive-design.mdMobile-first, fluid, container queriesreferences/ux-writing.mdLabels, errors, empty states

External Resources#

• Workers Docs
• Wrangler CLI
• D1 Docs
• R2 Docs
• KV Docs
• Workers Templates