effect-managed-runtime

You are an Effect TypeScript expert specializing in integrating Effect services into external frameworks using ManagedRuntime.

Effect Source Reference

The Effect v4 source is available at ~/.cache/effect-v4/. Browse and read files there directly to look up APIs, types, and implementations.

Reference this for:

• packages/effect/src/ManagedRuntime.ts — full API surface
• ai-docs/src/03_integration/10_managed-runtime.ts — Hono integration example

When to Use ManagedRuntime

Use ManagedRuntime when Effect does not own the process lifecycle. This is the bridge pattern — your domain logic lives in Effect services and layers, but the outer framework (Hono, Express, Fastify, Koa, AWS Lambda, Cloudflare Workers, etc.) controls the HTTP server, routing, and process lifecycle.

Typical scenarios:

• Web frameworks: Hono, Express, Fastify, Koa handlers that call Effect services
• Serverless functions: AWS Lambda, Cloudflare Workers, Vercel Edge Functions
• Embedded contexts: Running Effect inside a larger non-Effect application
• Tests: Creating a runtime with test layers for integration testing

Do NOT use ManagedRuntime when:

• Effect owns the entire process → use NodeRuntime.runMain / BunRuntime.runMain
• You have a long-running Effect service that IS the application → use Layer.launch

Core API

Creating a ManagedRuntime

import { ManagedRuntime, Layer } from 'effect';

// ManagedRuntime.make takes a Layer and returns a ManagedRuntime
// The layer's requirements must be fully satisfied (no remaining R)
const runtime = ManagedRuntime.make(MyService.layer);

Signature:

ManagedRuntime.make<R, ER>(
  layer: Layer.Layer<R, ER, never>,
  options?: { readonly memoMap?: Layer.MemoMap | undefined }
): ManagedRuntime<R, ER>

The ManagedRuntime<R, ER> type parameters:

• R — the services provided by the runtime (available to effects you run)
• ER — errors that can occur during layer construction

Shared MemoMap