Composition Guides

Compose worker families with service bindings when another worker is a real dependency

Use this page for the architecture question: when a separate worker boundary is justified, how and service bindings keep it explicit, and where local tests and release checks should prove the wiring.

The Services guide can explain the mechanics. This page exists for the composition question: when should another worker exist at all, how do you keep the boundary explicit, and which docs own the deeper service details once you commit to it?

Best for: Service bindings, worker families, and deciding when another worker boundary is actually real
Core tools: , service bindings, and generated env types
Best local proof: plus one real service call through
Main release risk: Resolved worker naming and preview topology drift

Choose another worker only when the boundary is real

The goal is not to split one worker just because the file count went up. The goal is to give a real runtime boundary a real worker boundary, then let service bindings make that relationship explicit enough for tooling and review.

That means this page should answer the architecture choice first. The Services guide can take over once the answer is already “yes, another worker should exist.”

If the real thing is...	Prefer...	Why
A separate runtime capability or internal API	and another worker	The boundary is a real worker-to-worker relationship, not just shared state.
One stateful identity or serialized mutation lane		The core need is state ownership, not another general-purpose service boundary.
Shared data, files, or a background job handoff	, , , or	The problem is data or deferred work, not a second worker API.

A good review question

Ask “what does this second worker own that a binding or Durable Object would not?” before you celebrate the split.

Model the relationship with so the worker family stays explicit

If another worker is real, the relationship belongs in config instead of in copied worker names or half-remembered script references. gives Devflare enough structure to follow the dependency into local runtime, generated env types, and compiled output.

Keep the architecture example simple: one referenced worker and one explicit service binding are enough to show the boundary. Named entrypoints are real too, but the Services and generated-types pages own that deeper contract once the worker boundary itself is already justified.

Model the worker family with `ref()` and one explicit service binding

import { defineConfig, ref } from 'devflare/config'

const mathWorker = ref(() => import('../math-service/devflare.config'))

export default defineConfig({

name: 'gateway',

bindings: {

services: {

MATH_SERVICE: mathWorker.worker

}

})

Prove the wiring locally, then validate the names before release

The shortest truthful proof is one real service call through the generated env binding. That already shows the config relationship, the local multi-worker setup, and the callable surface the gateway worker will actually use.

But the release question is still different: local tests prove the call path, not that preview or production worker names resolve the way you intended.

Use the bound env service directly when the worker relationship is the thing you want to prove.
Refresh generated types when the service contract changes, and open the generated types page when named entrypoints become part of that contract.
Preview isolation follows resolved worker names, not just which branch variable existed in CI.
Validate compiled or preview naming when the worker family is business-critical.

One real service call through the default harness

import { afterAll, beforeAll, expect, test } from 'bun:test'

import { createTestContext, env } from 'devflare/test'

beforeAll(() => createTestContext())

afterAll(() => env.dispose())

test('service binding calls the default worker export', async () => {

expect(await env.MATH_SERVICE.add(5, 3)).toBe(8)

})

Open the service-specific pages once the architecture choice is done

Binding guide

Services guide

Services

Open the service guide for the exact binding shape, env typing, and compiler behavior once another worker is definitely the right boundary.

Testing

Testing Services

Services

Open the service testing guide when the next question is the right default harness or how to test named entrypoints accurately.

Configuration

Generated types

Typed contracts

Open this page when relationships, named entrypoints, or typing becomes the real question.

Ship & operate

Preview strategies

Preview topology

Open the preview page when the worker family needs real isolation and the naming model is the release question now.

Testing

Testing overview

Map

Use the testing map when the next question is broader than service bindings alone.

State & async patterns

Use Durable Objects when one identity should own state or coordination. Use queues when work should happen later, in batches, or with retries. Then open the specific binding guide once the pattern is clear.

KV

Author stable KV names in config, keep env typed, and run real get or put flows locally.