cloudflare-composition-root
Skill428 starsChanged 4 months agoMITView on GitHub
Composition roots for Hono and Cloudflare. Use when adding a binding-backed service or refactoring raw runtime dependencies out of inner code.
- Reads credentials
In this repository6 other files it gives its agents.
- broSkill
- coding-standardsSkill
- effect-service-designSkill
- herdrSkill
- preludeSkill
- tech-specSkill
The file
Show its rules and text
We split this skill into the rules it gives an agent
18 rules. About 0 are common, 13 are distinctive, and 5 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈13
Distinctive · estimate
This author's own choices. Worth a look.
5
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 8
Use a composition root: each runtime entrypoint turns raw Cloudflare capabilities into application-owned dependencies, assembles services, …
- Distinctive: line 43
Completion criterion: Every affected entrypoint, binding consumer, behavior, lifecycle, side effect, failure policy, and existing test seam …
- Distinctive: line 68
Use domain inputs and parsed outputs, not raw keys, strings, request objects, or binding options.
- Very specific: line 70
Keep each service's dependency object exact.
- Distinctive: line 71
Put platform serialization, keyspaces, pagination tokens, TTLs, metadata, and output parsing in the binding adapter.
- Very specific: line 74
Add an application-owned factory only when scope is genuinely dynamic after composition, such as account-bound construction after …
- Distinctive: line 82
Completion criterion: Every inner signature uses application/domain types.
- Distinctive: line 90
Keep protocol concerns in the HTTP, RPC, queue, Workflow, or scheduled adapter.
- Distinctive: line 97
Put the existing raw binding behind an adapter before changing policy.
- Very specific: line 101
Remove obsolete Env parameters, factories, generic wrappers, duplicated parsers/key builders, and compatibility overloads after their final …
- Distinctive: line 103
Do not broaden the refactor to unrelated bindings merely for symmetry.
- Distinctive: line 112
Create or obtain the tracer.
- Very specific: line 121
Prefer createApp(dependencies) and route/middleware factories that close over exact dependencies.
- Distinctive: line 123
If dependencies are invocation-scoped, have the entrypoint supply a narrow request-composition function that closes over raw bindings.
- Distinctive: line 128
Completion criterion: Every serving surface establishes tracing and constructs the complete dependency graph.
- Distinctive: line 132
Verify through production seams:
- Distinctive: line 140
Search for leakage using the project's binding names and runtime types, for example:
- Distinctive: line 148
Completion criterion: Every raw platform reference is classified and permitted.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Cloudflare Composition Root
Use a composition root: each runtime entrypoint turns raw Cloudflare capabilities into application-owned dependencies, assembles services, and invokes them. Inner code receives ports, never Env, raw bindings, framework service locators, or binding names.
Cloudflare entrypoint
→ tracer + parsed configuration
→ binding adapters
→ exact service dependencies
→ application service
→ protocol projectionApply ../coding-standards/SKILL.md for TypeScript contracts, parsing, errors, side effects, and tests. When implementation shape is unclear, consult EXAMPLES.md for Hono, WorkerEntrypoint, adapter, and refactor templates.
Ownership
- Entrypoint adapter: parses the external request/event, establishes invocation context, constructs dependencies, invokes a service, and projects its result.
- Binding adapter: implements an application-owned port using KV, R2, D1, Durable Objects, Queues, service bindings, Workflows, or another external capability.
- Application service: owns one use case's sequencing, fallback, retry, and best-effort policy.
- Domain module: owns pure values and invariants.
- Port: names exactly the capability a consumer needs; it does not mirror a Cloudflare API.
Raw platform values may exist only in composition roots and binding adapters. A binding adapter accepts the smallest platform capability, not all of Env.
1. Map the boundary
Inspect repository instructions and the affected:
- Hono app factories, middleware order, route registration, and context types;
- Worker, WorkerEntrypoint, Durable Object, Workflow, queue, and scheduled entrypoints;
Envdeclarations and every use of the relevant binding;- tracer creation, correlation, error reporting, and detached-work ownership;
- existing services, adapters, ports, tests, and architecture checks.
Trace each affected behavior from entrypoint to side effect and caller-visible result. For refactors, record current error, retry, fallback, serialization, and tracing behavior before moving it.
Completion criterion: Every affected entrypoint, binding consumer, behavior, lifecycle, side effect, failure policy, and existing test seam is accounted for.
2. Design application-owned dependencies
Define contracts from consumer needs:
/** Persistence capability required by document application services. */
export interface DocumentStore {
/** Find one document by its domain ID. */
find(id: DocumentId): Promise<Document | null>;
/** Persist one valid document. */
save(document: Document): Promise<void>;
}
/** Exact dependencies of the publish-document use case. */
export type PublishDocumentDependencies = Readonly<{
documents: DocumentStore;
clock: Clock;
tracer: Tracer;
}>;Rules:
- Use domain inputs and parsed outputs, not raw keys, strings, request objects, or binding options.
- Expose only operations required by real callers.
- Keep each service's dependency object exact; never create a shared mega-bag or rename
EnvtoDependencies. - Put platform serialization, keyspaces, pagination tokens, TTLs, metadata, and output parsing in the binding adapter.
- Let the application service own policy. The adapter translates failures precisely enough for the service to distinguish recoverable conditions from corruption and defects.
- Inject
Tracerinto services and adapters that create spans; do not add it to every method signature. - Add an application-owned factory only when scope is genuinely dynamic after composition, such as account-bound construction after authentication. The factory must not expose
Envor raw bindings.
Choose lifetimes explicitly:
- Reuse immutable adapters and services when their bindings and tracer are safe across concurrent invocations.
- Construct per invocation when they retain request-scoped runtime objects or mutable invocation state.
- Hand detached work to an explicit owner such as a narrow background-task port; do not leak
ExecutionContextinward.
Completion criterion: Every inner signature uses application/domain types; each operation and factory has a current caller; and dependency, tracer, and side-effect lifetimes have explicit owners.
3. Build or refactor
New service branch
- Implement the application service against its ports without importing Hono or Cloudflare runtime types.
- Implement one binding adapter per external role. Give technology-specific implementations explicit names, such as
WorkersKvDocumentStore. - Keep protocol concerns in the HTTP, RPC, queue, Workflow, or scheduled adapter.
- Compose the service at every entrypoint that serves the use case.
Existing code branch
- Preserve caller-visible behavior with tests at the current public seam where evidence is missing.
- Define the port at the direct consumer from the operations it already uses.
- Put the existing raw binding behind an adapter before changing policy.
- Replace the direct consumer's raw dependency with the port.
- Move adapter construction outward one layer at a time. Intermediate layers may pass the typed port, never both the port and raw binding as a permanent design.
- Split mixed modules: policy moves to the application service; platform mechanics move to the adapter; protocol mapping stays at the entrypoint.
- Remove obsolete
Envparameters, factories, generic wrappers, duplicated parsers/key builders, and compatibility overloads after their final callers move.
Do not broaden the refactor to unrelated bindings merely for symmetry.
Completion criterion: New code is fully composed on every serving surface, or every migrated raw binding reaches only its adapter; behavior and policy changes are either absent or explicitly requested and tested.
4. Compose every runtime surface
At each composition root, in order:
- Parse configuration and entrypoint props.
- Create or obtain the tracer.
- Establish correlation before invoking traced work.
- Wrap raw bindings in adapters, injecting the tracer where needed.
- Assemble exact service dependencies.
- Invoke the service through a thin protocol adapter.
- Map results and safe errors to the external contract.
For Hono:
- Prefer
createApp(dependencies)and route/middleware factories that close over exact dependencies. - Inject the tracer used by root tracing middleware instead of creating unrelated tracers deeper in the app.
- If dependencies are invocation-scoped, have the entrypoint supply a narrow request-composition function that closes over raw bindings; invoke it from the earliest owning middleware after correlation is established.
- Store only exact typed capabilities in Hono variables. Neither composition middleware nor route modules reach through
context.envfor raw bindings.
For WorkerEntrypoint, Durable Objects, Workflows, queues, and scheduled handlers, treat each runtime constructor or handler as its own composition root. Do not assume one surface's dependency graph or lifecycle fits another.
Completion criterion: Every serving surface establishes tracing and constructs the complete dependency graph; no inner module acquires runtime resources or reads a binding name.
5. Verify the seam
Verify through production seams:
- application-service behavior with small recording fakes implementing real ports;
- binding-adapter serialization, parsing, and failures against the representative local Cloudflare runtime;
- entrypoint composition and external result/error projection;
- span names, correlation, safe attributes, and detached-work ownership;
- type checking, focused tests, architecture checks, and repository-required validation.
Search for leakage using the project's binding names and runtime types, for example:
rg 'Env|KVNamespace|R2Bucket|D1Database|DurableObjectNamespace|ExecutionContext' srcClassify every match: composition root, binding adapter, unavoidable framework declaration, or violation. Also search for direct context.env and binding-name access in route, service, domain, and capability modules.
Completion criterion: Every raw platform reference is classified and permitted; every changed port, adapter, service, entrypoint, failure path, and lifecycle has evidence; and no application module imports or receives Cloudflare runtime types.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

