--- id: terrylica/cc-skills/cloudflare-workers-publish version: "a8b79475" license: MIT install: manual updated: 2026-07-28 --- # cloudflare-workers-publish — Publish static HTML content like Bokeh charts and reports to Cloudflare Workers using 1Password for secure credential storage. The skill handles setup, deployment, and token rotation for workers.dev sites, with templates for first-time configuration, adding files to existing deployments, and troubleshooting. Publisher: terrylica · Stars: 58 · Updated: 2026-07-28 Install (manual): `git clone https://github.com/terrylica/cc-skills` ## SKILL.md # 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 .mise/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 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](./references/onep-credential-setup.md) for step-by-step instructions. After provisioning, the item should have: | Field | Type | `--reveal` | Content | | ------------ | --------- | ---------- | ------------------ | | `account_id` | TEXT | No | Cloudflare acct ID | | `credential` | CONCEALED | **YES** | API token | ### Phase 3: Create wrangler.toml See [wrangler setup guide](./references/wrangler-setup.md). ```toml # 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: ```bash 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 ```toml # .mise/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`: ```toml [task_config] includes = [ ".mise/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 > **Workers & Pages** 2. Enable workers.dev subdomain **The subdomain is NOT predictable** (CFW-06). Discover yours after deploy: ```bash npx wrangler whoami ``` ### Phase 8: Deploy and Verify ```bash 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](./references/anti-patterns.md) | ID | Severity | Gotcha | Fix | | ------ | -------- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | CFW-01 | HIGH | Cloudflare Pages deprecated (April 2025) | Use Workers with Static Assets | | CFW-02 | HIGH | 1P service account creating items | Pre-provision via biometric/web UI | | CFW-03 | HIGH | Missing `--reveal` for CONCEALED fields | Always pass `--reveal` for API tokens | | CFW-04 | MEDIUM | SC2155 `export VAR=$(cmd)` | Split: `VAR=$(cmd)` then `export VAR` | | CFW-05 | LOW | Bash 4+ `${var^^}` on macOS | Use `tr '[:lower:]' '[:upper:]'` | | CFW-06 | MEDIUM | Assuming workers.dev URL format | Run `npx wrangler whoami` to discover slug | | CFW-07 | HIGH | workers.dev subdomain not registered | Enable in Cloudflare dashboard first | | CFW-08 | LOW | curl SSL/TLS handshake failure on macOS | Verify in browser instead | | CFW-09 | MEDIUM | Overcomplicating wrangler.toml | Only `name`, `compatibility_date`, `[assets]` | | CFW-10 | HIGH | Running wrangler from wrong directory | Always `cd` to directory with wrangler.toml | | CFW-11 | MEDIUM | Excessive token permissions | Workers Scripts Edit (Account) only | | CFW-12 | HIGH | Deploying LFS pointers instead of files | Run `git lfs pull` before deploy | | CFW-13 | MEDIUM | Tera template conflict in mise TOML | Complex bash in standalone `.sh` files | | CFW-14 | MEDIUM | Pipe subshell data loss in while-read | Use `< <(find ...)` process substitution | | CFW-15 | LOW | No directory listing page | Auto-generate index.html before each deploy | | CFW-16 | HIGH | Asset > 25 MiB → `Asset too large` deploy error | Workers Static Assets hard-caps **each file at 25 MiB**. Host large ZIPs/binaries off a large-file host (R2, GitHub Release, own server); keep only ≤25 MiB files on Workers. See [large files & ZIP delivery](./references/large-files-and-zip-delivery.md) | | CFW-17 | LOW | Want a bulk-download ZIP, but it exceeds the cap | Downscale the ZIP tier to fit (e.g. `heic-to-jpeg-bundle --zip-cap-mib 25`), or split hosts: gallery + small ZIP on Workers, full-res ZIP on R2 | --- ## 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](./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`: | File | Purpose | | --------------------------------- | -------------------------- | | `results/published/wrangler.toml` | Minimal Workers config | | `scripts/publish_findings.sh` | 3-phase deploy script | | `.mise/tasks/publish.toml` | mise task wrapper | | `.gitignore` (`.wrangler/`) | Ignore wrangler temp files | | `.gitattributes` | LFS tracking for HTML | **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](./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](./references/evolution-log.md) --- ## Troubleshooting | Issue | Cause | Solution | | ------------------------------ | ------------------------------------- | ------------------------------------------------------------- | | `op item get` returns masked | Missing `--reveal` flag (CFW-03) | Add `--reveal` for CONCEALED fields | | `op item create` fails | Service account can't create (CFW-02) | Use biometric `op` or web UI to create item first | | wrangler: config not found | Not in correct directory (CFW-10) | `cd` to directory containing wrangler.toml before deploy | | SSL handshake failure | macOS LibreSSL (CFW-08) | Verify in browser; ignore curl errors | | 403 on workers.dev URL | Subdomain not enabled (CFW-07) | Enable in Cloudflare dashboard > Workers & Pages | | Deploy succeeds, files missing | LFS pointers deployed (CFW-12) | Run `git lfs pull` before deploy | | `${var^^}` syntax error | Bash 3 on macOS (CFW-05) | Use `tr '[:lower:]' '[:upper:]'` | | mise TOML parse error | Tera template conflict (CFW-13) | Move complex bash to standalone `.sh` file | | Empty index.html | No `gen*/*.html` files found | Check file paths match `find . -path './gen*/*.html'` pattern | | Token permission denied | Wrong token scope (CFW-11) | Recreate with Account > Workers Scripts > Edit permission | ## 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 [View on SkillFed](https://skillfed.io/terrylica/cc-skills/cloudflare-workers-publish) · [View on GitHub](https://github.com/terrylica/cc-skills)