Cloudflare Worker Deployment Skill

Purpose

You are a specialized assistant for deploying TypeScript/Hono apps to Cloudflare Workers in a clean, repeatable, and environment-aware way.

Use this skill to:

• Set up or refine

  wrangler.toml

  for a Worker/Pages Functions service
• Decide and document environments (

  dev

  ,

  staging

  ,

  production

  )
• Configure bindings:
  • D1 (

    [[d1_databases]]

    )
  • R2 (

    [[r2_buckets]]

    )
  • KV, Durable Objects, etc. (if present)
• Set up build & entrypoint for:
  • Hono app (

    app.ts

    /

    index.ts

    )
  • Node runtime vs Worker runtime
• Design deployment workflows with Wrangler and CI (at a high level)
• Manage secrets, env vars, and per-env config

Do not use this skill for:

• Hono app routing/middleware itself → use

  hono-app-scaffold

• D1-specific schema or queries → use

  hono-d1-integration

• R2-specific flows → use

  hono-r2-integration

• Deep CI pipeline templates → use a dedicated CI/CD skill (e.g.

  cloudflare-ci-cd-github-actions

  )

If

CLAUDE.md

exists, follow its rules about deployment environments, Cloudflare accounts, and project conventions.

---

When To Apply This Skill

Trigger this skill when the user asks for things like:

• “Deploy this Hono app to Cloudflare Workers.”
• “Create wrangler.toml for this project.”
• “Set up dev/staging/prod Workers environments.”
• “Wire D1/R2 bindings for my Worker.”
• “Help me go from local dev to production on Cloudflare.”
• “Fix deployment issues with this Cloudflare Worker.”

Avoid when:

• The project is deployed only to AWS, Vercel, etc., and Cloudflare is not involved.
• The user is editing business logic but deployment config is already stable.

---

Assumptions & Project Context

By default, this skill assumes:

• Language: TypeScript

• Framework: Hono (or similar Worker-compatible TS entrypoint)

• Runtime: Cloudflare Workers (or Cloudflare Pages Functions)

• Build tooling: Wrangler’s native bundling (esbuild/miniflare) unless overridden

• Structure (adapt to actual project):

  project-root/
    src/
      app.ts      # Hono app definition
      index.ts    # Worker entry that exports app.fetch
    wrangler.toml
    package.json
    tsconfig.json
  

Other layouts (monorepo, multiple apps) are supported but this is the default mental model.

---

Entry Point Design

For a typical Hono + Workers app:

// src/index.ts
import { app } from "./app";

export default {
  fetch: app.fetch,
};

This is the file Wrangler will use as the Worker script entry (after bundling).

This skill will:

• Ensure

  main

  /

  entrypoint

  in

  wrangler.toml

  points at your built script (or

  src/index.ts

  ).
• Avoid Node-only APIs in Worker code unless polyfilled by the bundler.

---

Basic wrangler.toml Layout

Single-Environment (Simple) Example

name = "my-hono-api"
main = "src/index.ts"
compatibility_date = "2025-01-01"

[vars]
NODE_ENV = "production"

For a real project, this skill will almost always recommend multi-environment config.

Multi-Environment Example

name = "my-hono-api"
main = "src/index.ts"
compatibility_date = "2025-01-01"

[vars]
NODE_ENV = "development"

[env.staging]
vars = { NODE_ENV = "staging" }

[env.production]
vars = { NODE_ENV = "production" }

This skill should:

• Choose a compatibility_date (today-ish or a recent date) and keep it up to date.
• Suggest environment-specific overrides where needed.

---

Adding D1 & R2 Bindings

When D1 is used (with

hono-d1-integration

):

[[d1_databases]]
binding = "DB"
database_name = "my_db"
database_id = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

[env.staging]
[[env.staging.d1_databases]]
binding = "DB"
database_name = "my_db_staging"
database_id = "staging-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

[env.production]
[[env.production.d1_databases]]
binding = "DB"
database_name = "my_db_prod"
database_id = "prod-xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"

When R2 is used (with

hono-r2-integration

):

[[r2_buckets]]
binding = "BUCKET"
bucket_name = "my-bucket"
preview_bucket_name = "my-bucket-dev"

[env.production]
[[env.production.r2_buckets]]
binding = "BUCKET"
bucket_name = "my-bucket-prod"
preview_bucket_name = "my-bucket-prod-preview"

This skill will:

• Keep binding names (

  DB

  ,

  BUCKET

  ) consistent with the TypeScript Env typings.
• Help differentiate staging vs prod buckets/databases.

---

Local Development Workflow

This skill should encourage a straightforward dev loop:

• Install Wrangler and dependencies.
• Use

  wrangler dev

  to run the Worker locally (or in “remote dev” mode).

Example

package.json

scripts:

{
  "scripts": {
    "dev": "wrangler dev",
    "build": "wrangler build",
    "deploy": "wrangler deploy",
    "deploy:staging": "wrangler deploy --env staging",
    "deploy:production": "wrangler deploy --env production"
  }
}

This skill should:

• Align scripts with the project’s package manager and naming conventions.
• Make sure

  wrangler dev

  runs against the correct entrypoint.

---

Secrets & Environment Variables

Secrets should not be committed to the repo.

This skill should:

• Use Wrangler secrets for sensitive values:

  wrangler secret put JWT_SECRET
  wrangler secret put JWT_SECRET --env production
  

• Use

  [vars]

  in

  wrangler.toml

  only for non-sensitive values (or development-only):

  [vars]
  FEATURE_FLAG_COOL_THING = "on"
  

• Make sure code accesses secrets via

  c.env

  (Workers) or

  env

  in typed Env interface.

Example typed usage:

interface Env {
  DB: D1Database;
  BUCKET: R2Bucket;
  JWT_SECRET: string;
  NODE_ENV: "development" | "staging" | "production";
}

---

Deploying to Different Environments

This skill should set clear conventions like:

• Dev:

  wrangler dev

  (local)
• Staging:

  wrangler deploy --env staging

• Prod:

  wrangler deploy --env production

It can also recommend using separate:

• Routes (e.g., staging subdomain)
• D1 databases & R2 buckets
• Flags (

  NODE_ENV

  or

  APP_ENV

  )

Typical wrangler extra fields:

[env.staging]
route = "staging-api.example.com/*"

[env.production]
route = "api.example.com/*"

Or using

routes

arrays for multiple domains/routes.

---

Handling Build Output

Wrangler generally handles bundling automatically when you set

main = "src/index.ts"

.

This skill should:

• Avoid over-complicating the build unless you have a non-standard bundler.

• If using a custom build step, ensure

  wrangler.toml

  points to the built artifact instead:

  main = "dist/index.mjs"
  

  And

  package.json

  adds:

  {
    "scripts": {
      "build": "tsc",
      "deploy": "npm run build && wrangler deploy"
    }
  }
  

---

Pages Functions Variant (Optional)

If the project uses Cloudflare Pages + Functions, entry and wrangler config differ slightly.

This skill should:

• Place functions in

  functions/[[path]].ts

  or

  functions/api/[[path]].ts

  .

• Export Hono app handlers accordingly:

  // functions/api/[[route]].ts
  import { app } from "../../src/app";
  
  export const onRequest = app.fetch;
  

• Use

  wrangler.toml

  minimally (Pages uses its own config).

Use this variant only when the project explicitly indicates Pages Functions (e.g., integration with a Next/React frontend in Pages).

---

Error Diagnosis & Common Pitfalls

This skill should help debug issues like:

• ReferenceError: process is not defined

  :
  • Fix by removing Node-specific APIs or shimming, but prefer Worker-compatible alternatives.
• Incorrect bindings (

  c.env.DB

  undefined):
  • Check

    wrangler.toml

    binding names vs Env type vs actual code.
• Mismatched environments:
  • Using

    wrangler dev

    but expecting prod secrets/bindings.
• Deploy succeeds but runtime fails:
  • Check compatibility_date and Worker logs (

    wrangler tail

    ).

It should guide through:

• Checking Wrangler logs (

  wrangler tail

  )
• Validating

  wrangler.toml

• Ensuring

  main

  and exports (default + fetch) are correct

---

Interaction with Other Skills

• hono-app-scaffold

  :
  • Provides

    src/app.ts

    and

    src/index.ts

    . This skill focuses on

    wrangler.toml

    and deploy scripts.

• hono-d1-integration

  :
  • This skill creates D1 bindings; that one defines schema and query usage.

• hono-r2-integration

  :
  • This skill creates R2 bindings; that one defines upload/download logic.

• cloudflare-d1-migrations-and-production-seeding

  (future):
  • This deployment skill will call its patterns for migration before/after deploy.

• cloudflare-observability-logging-monitoring

  (future):
  • This skill uses Wrangler & Workers analytics; deployment skill ensures they’re wired correctly.

---

Example Prompts That Should Use This Skill

• “Create wrangler.toml for this Hono + Workers app with D1 + R2.”
• “Set up dev/staging/prod environments on Cloudflare Workers.”
• “Add deploy scripts to package.json for this Worker.”
• “Fix my Worker deployment; it runs locally but not on Cloudflare.”
• “Wire secrets and env vars correctly for my Hono Worker.”

For such tasks, rely on this skill to produce a clean, environment-aware Cloudflare Worker deployment setup that plays nicely with your Hono, D1, and R2 integration skills.