Cloudflare Worker Cold Start Tuner

What this skill does

Profiles a Cloudflare Worker's startup cost and identifies which imports and module-level initializations dominate. Outputs a refactor plan that defers heavy work behind a fetch-handler-scoped lazy import.

Inputs

• worker_entry: path to the Worker entry file (src/index.ts or similar).
• wrangler_toml: path to wrangler.toml.
• Optional bundle_size_target_kb: defaults to 800 (Workers limit a paid tier; free tier 1MB).

Steps

1. Build the Worker: npx wrangler deploy --dry-run --outdir=/tmp/worker-build. Capture the bundle path.
2. Measure bundle size with wc -c /tmp/worker-build/index.js and record. If gzipped, also gzip -c | wc -c.
3. Run a static analysis pass over worker_entry and its imports: build the dependency graph with madge --json <worker_entry>.
4. For each top-level import, classify cost: known-heavy modules (zod schemas at top level, large polyfills, bcrypt, jsonwebtoken) get tagged.
5. Detect module-level work: rg -nN '^(const|let|var) [a-zA-Z_]+\s*=' <worker_entry> and inspect each assignment for synchronous heavy calls (e.g., regex compilation, schema construction).
6. For each candidate, propose a lazy-load: replace import x from 'big-mod' with let x; async function getX() { x ??= (await import('big-mod')).default; return x; }.
7. For schemas defined at top level, suggest constructing inside the handler or wrapping in useMemo-style cache keyed on a per-isolate global.
8. Estimate cold-start delta: each known-heavy module mapped to a cost (rough order: zod: 5-10ms, jose: 3-5ms, marked: 8-12ms).
9. Compose a refactor plan with diffs.

Output

worker-cold-start-plan.md with sections: bundle size analysis, top heavy imports, per-import refactor patches (fenced diffs), expected savings table. Stdout prints current bundle size and projected post-refactor savings.

Verification

Apply one suggested patch at a time, redeploy with wrangler deploy --dry-run, and compare cold-start latency using wrangler tail plus a synthetic-request loop from a different region. Post-refactor cold-start p95 should drop by the projected delta within 20%. Functional tests must pass; lazy imports change error timing, so update tests that asserted synchronous error throws.

Edge cases

• Workers that use Durable Objects: their constructors run cold per object; lazy-loading there has different semantics.
• Workers that depend on KV at startup: KV read is async-only; never moves to module level anyway.
• Workers using nodejs_compat flag: bundle is fatter inherently; document that compatibility flag costs roughly 200KB.
• Workers under 100KB: cold start is already minimal; suggest skipping the refactor and document baseline instead.