cloudflare-workers-publish

Cloudflare Workers Publish

Deploy static HTML files (Bokeh charts, dashboards, reports) to Cloudflare Workers with Static Assets, using 1Password for credential management.

Scope: Static-only deployments on workers.dev. No dynamic Workers, no R2 object storage.

Prerequisite: 1Password CLI (brew install 1password-cli) + Node.js (npx wrangler)

Self-Evolving Skill: This skill improves through use. If instructions are wrong, parameters drifted, or a workaround was needed — fix this file immediately, don't defer. Only update for real, reproducible issues.

When to Use This Skill

• Publishing HTML files to a public URL (too large for GitHub)
• Setting up a new Cloudflare Workers static site
• Troubleshooting a failed Cloudflare deploy
• Rotating Cloudflare API tokens in 1Password

Do NOT use for: Dynamic Workers (JavaScript/TypeScript logic), Cloudflare Pages (deprecated April 2025 - CFW-01), R2 object storage, or custom domains (advanced setup not covered).

Architecture

Local project/
├── results/published/              # Deploy root (contains wrangler.toml)
│   ├── wrangler.toml               # Workers config (name + assets)
│   ├── index.html                  # Auto-generated directory listing
│   └── gen800/                     # Subdirectories with HTML files
│       └── XRPUSDT_750/
│           └── equity_plot.html    # 13MB Bokeh chart
└── scripts/
    └── publish_findings.sh         # Deploy script (3 phases)

Credential flow:

1Password (Claude Automation vault)
   ├── account_id (TEXT)      →  CLOUDFLARE_ACCOUNT_ID env var
   └── credential (CONCEALED) →  CLOUDFLARE_API_TOKEN env var
                                       ↓
                                 npx wrangler deploy
                                       ↓
                                 https://{name}.{slug}.workers.dev/

TodoWrite Task Templates

Template A - New Static Site (First-Time Setup)

1. [Preflight] Verify Node.js and 1Password CLI installed
2. [Preflight] Create Cloudflare API token (Workers Scripts Edit permission)
3. [Execute] Pre-provision 1Password item in Claude Automation vault (biometric)
4. [Execute] Store token + account ID in 1Password item fields
5. [Execute] Create publish directory with wrangler.toml (3 fields only)
6. [Execute] Create deploy script from skill template (parameterize 4 vars)
7. [Execute] Create mise task wrapper in tasks/publish.toml
8. [Execute] Add .wrangler/ to .gitignore
9. [Execute] Add LFS tracking for large HTML files in .gitattributes
10. [Verify] Enable workers.dev subdomain in Cloudflare dashboard
11. [Verify] Run first deploy and verify URL in browser (NOT curl)
12. [Verify] Document the workers.dev URL in project docs

Template B - Add Files to Existing Published Site

1. [Preflight] Verify files are real content, not LFS pointers (head -1)
2. [Execute] Copy HTML files to published/{generation}/{symbol_threshold}/
3. [Execute] Run deploy script (index.html auto-regenerates)
4. [Verify] Verify new files appear at workers.dev URL in browser

Template C - New Worker (New Subdomain/Project)

1. [Preflight] Choose worker name ({name}.{slug}.workers.dev)
2. [Execute] Create 1Password item OR reuse existing Cloudflare credentials
3. [Execute] Create wrangler.toml with chosen name and today's date
4. [Execute] Create parameterized deploy script from skill template
5. [Execute] Create mise task wrapper
6. [Verify] Deploy and discover actual workers.dev URL via wrangler output

Template D - Rotate Cloudflare API Token

1. [Execute] Create new API token in Cloudflare dashboard (Workers Scripts Edit)
2. [Execute] Update 1Password item credential field (biometric required)
3. [Verify] Run deploy script to verify new token works
4. [Execute] Revoke old token in Cloudflare dashboard

Template E - Troubleshoot Failed Deploy

1. Is wrangler.toml in current directory? (CFW-10)
2. Are credentials populated? Print first 8 chars of account ID
3. Is --reveal present for CONCEALED fields? (CFW-03)
4. Is workers.dev subdomain registered in CF dashboard? (CFW-07)
5. Does token have Workers Scripts Edit permission? (CFW-11)
6. Are HTML files real content or LFS pointers? head -1 file (CFW-12)
7. SSL handshake error? Verify in browser, not curl (CFW-08)
8. Is npx wrangler installed? npx wrangler --version

Workflow: First-Time Setup

Phase 1: Create Cloudflare API Token

1. Go to https://dash.cloudflare.com/profile/api-tokens
2. Click Create Token > Custom token
3. Set permissions: Account > Workers Scripts > Edit (CFW-11)
4. Account Resources: Include > your account
5. Copy the token (shown only once)

Phase 2: Provision 1Password Credentials

CRITICAL (CFW-02): 1Password service accounts can only READ items. They CANNOT CREATE new items. Create the item manually first.

See 1Password setup guide for step-by-step instructions.

After provisioning, the item should have:

Phase 3: Create wrangler.toml

See wrangler setup guide.

# Minimal Workers Static Assets config (CFW-09)
name = "my-project-name"
compatibility_date = "2026-02-18"

[assets]
directory = "."

Phase 4: Create Deploy Script

Copy the bundled template and edit the 4 config variables:

cp "$(skill-path)/scripts/publish_static.sh" scripts/publish_myproject.sh
# Edit: PUBLISH_DIR, OP_ITEM_ID, SITE_TITLE, PROJECT_URL

Or reference the working implementation: rangebar-patterns/scripts/publish_findings.sh

Phase 5: Create mise Task

# tasks/publish.toml (CFW-13: bash in .sh file, not inline TOML)
["publish:site"]
description = "Deploy published files to Cloudflare Workers (static)"
run = "bash scripts/publish_myproject.sh"

Add to .mise.toml [task_config] includes:

[task_config]
includes = [
    "tasks/publish.toml",
]

Phase 6: Git Hygiene

.gitignore:

# Wrangler temp files (Cloudflare Workers deploy)
.wrangler/
results/published/.wrangler/

.gitattributes (for large HTML files):

results/published/**/*.html filter=lfs diff=lfs merge=lfs -text

Phase 7: Enable workers.dev Subdomain (CFW-07)

First-time Cloudflare accounts must enable the workers.dev route:

1. Go to https://dash.cloudflare.com > Workers & Pages
2. Enable workers.dev subdomain

The subdomain is NOT predictable (CFW-06). Discover yours after deploy:

npx wrangler whoami

Phase 8: Deploy and Verify

mise run publish:site

Verify in BROWSER, not curl (CFW-08). macOS LibreSSL can fail TLS handshake with Cloudflare but browsers handle it fine.

Anti-Patterns Summary

Full details with code examples: references/anti-patterns.md

Large files & ZIP delivery (downloads, not just pages)

This skill also covers serving downloadable files (a ZIP bundle, a dataset) from Workers — within the 25 MiB/file cap — and the password-on-the-gateway pattern for gating an otherwise-unlisted download. Full guide: references/large-files-and-zip-delivery.md.

Quick rules:

• ≤ 25 MiB → Workers is fine. A small/downscaled ZIP can sit beside the gallery and be linked directly. > 25 MiB is a hard deploy error (CFW-16) — use R2 / a GitHub Release / your own host for those.
• Password-gated, unlisted download. Encrypt the ZIP (ZipCrypto, so Windows/7-Zip/macOS open it natively) and put the password only on the gateway you share (a gist, an email), never on the Workers page. Finding the bare ZIP URL then isn't enough to open it. The heic-to-jpeg-bundle skill produces exactly this kind of capped, optionally-encrypted ZIP.

Reference Implementation

The working production deployment lives in rangebar-patterns:

Live URL: https://rangebar-findings.terry-301.workers.dev/

Post-Change Checklist

After modifying this skill:

1. Anti-patterns table matches references/anti-patterns.md
2. All bash examples use set -euo pipefail
3. No hardcoded 1Password item IDs (parameterized)
4. No hardcoded workers.dev slugs (discovered at runtime)
5. Template script passes bash -n syntax check
6. All internal links use relative paths (./references/...)
7. Link validator passes
8. Skill validator passes
9. Append changes to references/evolution-log.md

Troubleshooting

Post-Execution Reflection

After this skill completes, reflect before closing the task:

0. Locate yourself. — Find this SKILL.md's canonical path (Glob for this skill's name) before editing. All corrections target THIS file and its sibling references/ — never other documentation.
1. What failed? — Fix the instruction that caused it. If it could recur, add it as an anti-pattern.
2. What worked better than expected? — Promote it to recommended practice. Document why.
3. What drifted? — Any script, reference, or external dependency that no longer matches reality gets fixed now.
4. Log it. — Every change gets an evolution-log entry with trigger, fix, and evidence.

Do NOT defer. The next invocation inherits whatever you leave behind