runtime_skill

Overview

This skill explains Effect's runtime system: how effects are executed, configured, and composed. It covers the default runtime, custom and managed runtimes, runtime-scoped configuration, service injection with Effect.Tag, and common run methods. The goal is practical guidance for running effects reliably in apps and tests.

How this skill works

The runtime is the execution engine that interprets and runs Effect values. By default effects run on a zero-configuration runtime with helper methods like runPromise, runSync, and their Exit-returning variants. You can derive custom runtimes by layering FiberRefs or providing services, or build a ManagedRuntime to prebuild layers, reuse services, and manage lifecycle and cleanup.

When to use it

• When you need to execute an Effect and choose sync vs async semantics (runSync vs runPromise).
• When you want application-wide services or context provided to effects (use ManagedRuntime or provide services to a runtime).
• When you need scoped overrides like log levels or test clocks for specific effect runs.
• When integrating with frameworks (Express, React) and require lifecycle management and cleanup.
• When writing deterministic tests that require TestClock or controlled randomness.

Best practices

• Use ManagedRuntime for long-lived applications to prebuild layers and ensure proper dispose().
• Provide services through layers and Effect.Tag instead of ad-hoc runtime modifications for clarity and reuse.
• Prefer runPromiseExit / runSyncExit when you need to observe failures without throwing. Use runPromise / runSync when you want exceptions to propagate.
• Use scoped runtime modifications (FiberRef, provide) for local behavior changes (e.g., log level, test clock).
• In tests, replace real services with TestClock or test implementations to keep behavior deterministic.

Example use cases

• Simple script: use Effect.runPromise to execute a program and obtain the result asynchronously.
• Web server: create a ManagedRuntime from application layers and call runtime.runPromise inside request handlers; dispose runtime on shutdown.
• React app: provide a ManagedRuntime via context and call runtime.runPromise from components to fetch data.
• Integration testing: provide TestClock.layer to a program to control time and use runPromiseExit to assert outcomes without throwing.
• Critical sections: wrap transactional work with Effect.uninterruptible and manage cleanup via ManagedRuntime or provided finalizers.