Skip to main content

Getting started

cf-common is a set of typed helpers for Cloudflare Workers bindings. You install it once and import only the modules you need — each is a separate subpath export, so your Worker bundle stays small.

Install​

pnpm add @rtorcato/cf-common
npm install @rtorcato/cf-common

Import from subpaths​

Always import from a service subpath — never from the package root:

// ✅ pulls in only the KV helper
import { createKvStore } from '@rtorcato/cf-common/kv'

// ❌ the root entry is intentionally empty
import { createKvStore } from '@rtorcato/cf-common'

Configure TypeScript​

Add the Workers types and leave the DOM lib out. @cloudflare/workers-types declares the same globals (Request, Response, fetch, …) that the DOM lib does, so keeping DOM in your default lib gives duplicate-identifier errors on your first Worker.

{
"compilerOptions": {
"target": "ES2022",
"lib": ["ES2022"],
"types": ["@cloudflare/workers-types"],
"strict": true,
"noEmit": true
}
}

Type your environment​

Cloudflare passes bindings on the env argument. Declare them once so every helper is typed against your real bindings. The index signature lets your Env fit the Record<string, unknown> that the helpers take:

interface Env {
[key: string]: unknown
CACHE: KVNamespace
BUCKET: R2Bucket
DB: D1Database
}

A first Worker​

import { getBinding } from '@rtorcato/cf-common/env'
import { createKvStore } from '@rtorcato/cf-common/kv'

export default {
async fetch(req: Request, env: Env): Promise<Response> {
const store = createKvStore<{ id: number }>(getBinding<KVNamespace>(env, 'CACHE'))
const user = await store.get('u:42') // { id: number } | null
return Response.json(user ?? { id: 42 })
},
}

Agent skill​

This repo ships an agent skill (skills/cf-common/SKILL.md) that teaches coding agents the subpath imports, the CloudflareError / defineFetch error contract, and each module's API. Install it in one command, straight from GitHub:

npx skills add https://github.com/rtorcato/cf-common --skill cf-common

Next steps​

  • Browse the milestones to see what's available and what's coming.
  • Follow issues for per-module progress.