Introduction to Effect Platform

@effect/platform is a library for building platform-independent abstractions in environments such as Node.js, Deno, Bun, and browsers.

With @effect/platform, you can integrate abstract services like FileSystem or Terminal into your program. When assembling your final application, you can provide specific layers for the target platform using the corresponding packages:

@effect/platform-node for Node.js or Deno
@effect/platform-bun for Bun
@effect/platform-browser for browsers

Stable Modules

The following modules are stable and their documentation is available on this website:

Module	Description	Status
Command	Provides a way to interact with the command line.	Stable
FileSystem	A module for file system operations.	Stable
KeyValueStore	Manages key-value pairs for data storage.	Stable
Path	Utilities for working with file paths.	Stable
PlatformLogger	Log messages to a file using the FileSystem APIs.	Stable
Runtime	Run your program with built-in error handling and logging.	Stable
Terminal	Tools for terminal interaction.	Stable

Unstable Modules

Some modules in @effect/platform are still in development or marked as experimental. These features are subject to change.

Module	Description	Status
Http API	Provide a declarative way to define HTTP APIs.	Unstable
Http Client	A client for making HTTP requests.	Unstable
Http Server	A server for handling HTTP requests.	Unstable
Socket	A module for socket-based communication.	Unstable
Worker	A module for running tasks in separate workers.	Unstable

For the most up-to-date documentation and details, please refer to the official README of the package.

Installation

To install the beta version:

npm install @effect/platform

pnpm add @effect/platform

yarn add @effect/platform

bun add @effect/platform

deno add npm:@effect/platform

Getting Started with Cross-Platform Programming

Here’s a basic example using the Path module to create a file path, which can run across different environments:

Example (Cross-Platform Path Handling)

1
import { 
import Path
Path } from "@effect/platform"
2
import { 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from "effect"
3

4
const 
const program: Effect.Effect<void, never, Path.Path>
program = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Tag<Path.Path, Path.Path>>, void>(f: (resume: Effect.Adapter) => Generator<YieldWrap<Tag<Path.Path, Path.Path>>, void, never>) => Effect.Effect<void, never, Path.Path> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to Use
Effect.gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.
The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.
Example
import { Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

export const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
gen(function* () {
5
  // Access the Path service
6
  const 
const path: Path.Path
path = yield* 
import Path
Path.
const Path: Tag<Path.Path, Path.Path>@since ― 1.0.0
@since ― 1.0.0
@since ― 1.0.0
Path
7

8
  // Join parts of a path to create a complete file path
9
  const 
const mypath: string
mypath = 
const path: Path.Path
path.
Path.join: (...paths: ReadonlyArray<string>) => string
join("tmp", "file.txt")
10

11
  
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log(
const mypath: string
mypath)
12
})

Running the Program in Node.js or Deno

First, install the Node.js-specific package:

npm install @effect/platform-node

pnpm add @effect/platform-node

yarn add @effect/platform-node

deno add npm:@effect/platform-node

Update the program to load the Node.js-specific context:

Example (Providing Node.js Context)

1
import { 
import Path
Path } from "@effect/platform"
2
import { 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from "effect"
3
import { 
import NodeContext
NodeContext, 
import NodeRuntime
NodeRuntime } from "@effect/platform-node"
4

5
const 
const program: Effect.Effect<void, never, Path.Path>
program = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Tag<Path.Path, Path.Path>>, void>(f: (resume: Effect.Adapter) => Generator<YieldWrap<Tag<Path.Path, Path.Path>>, void, never>) => Effect.Effect<void, never, Path.Path> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to Use
Effect.gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.
The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.
Example
import { Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

export const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
gen(function* () {
6
  // Access the Path service
7
  const 
const path: Path.Path
path = yield* 
import Path
Path.
const Path: Tag<Path.Path, Path.Path>@since ― 1.0.0
@since ― 1.0.0
@since ― 1.0.0
Path
8

9
  // Join parts of a path to create a complete file path
10
  const 
const mypath: string
mypath = 
const path: Path.Path
path.
Path.join: (...paths: ReadonlyArray<string>) => string
join("tmp", "file.txt")
11

12
  
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log(
const mypath: string
mypath)
13
})
14

15
import NodeRuntime
NodeRuntime.
const runMain: RunMain
<never, void>(effect: Effect.Effect<void, never, never>, options?: {
    readonly disableErrorReporting?: boolean | undefined;
    readonly disablePrettyLogger?: boolean | undefined;
    readonly teardown?: Teardown | undefined;
}) => void (+1 overload)
Helps you run a main effect with built-in error handling, logging, and signal management.
Details
This function launches an Effect as the main entry point, setting exit codes
based on success or failure, handling interrupts (e.g., Ctrl+C), and optionally
logging errors. By default, it logs errors and uses a "pretty" format, but both
behaviors can be turned off. You can also provide custom teardown logic to
finalize resources or produce different exit codes.
Options
An optional object that can include:

disableErrorReporting: Turn off automatic error logging.
disablePrettyLogger: Avoid adding the pretty logger.
teardown: Provide custom finalization logic.

When to Use
Use this function to run an Effect as your application’s main program, especially
when you need structured error handling, log management, interrupt support,
or advanced teardown capabilities.
runMain(
const program: Effect.Effect<void, never, Path.Path>
program.
Pipeable.pipe<Effect.Effect<void, never, Path.Path>, Effect.Effect<void, never, never>>(this: Effect.Effect<void, never, Path.Path>, ab: (_: Effect.Effect<void, never, Path.Path>) => Effect.Effect<void, never, never>): Effect.Effect<void, never, never> (+21 overloads)
pipe(
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const provide: <NodeContext.NodeContext, never, never>(layer: Layer<NodeContext.NodeContext, never, never>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, NodeContext.NodeContext>> (+9 overloads)
Provides necessary dependencies to an effect, removing its environmental
requirements.
Details
This function allows you to supply the required environment for an effect.
The environment can be provided in the form of one or more Layers, a
Context, a Runtime, or a ManagedRuntime. Once the environment is
provided, the effect can run without requiring external dependencies.
You can compose layers to create a modular and reusable way of setting up the
environment for effects. For example, layers can be used to configure
databases, logging services, or any other required dependencies.
Example
import { Context, Effect, Layer } from "effect"

class Database extends Context.Tag("Database")<
  Database,
  { readonly query: (sql: string) => Effect.Effect<Array<unknown>> }
>() {}

const DatabaseLive = Layer.succeed(
  Database,
  {
    // Simulate a database query
    query: (sql: string) => Effect.log(`Executing query: ${sql}`).pipe(Effect.as([]))
  }
)

//      ┌─── Effect<unknown[], never, Database>
//      ▼
const program = Effect.gen(function*() {
  const database = yield* Database
  const result = yield* database.query("SELECT * FROM users")
  return result
})

//      ┌─── Effect<unknown[], never, never>
//      ▼
const runnable = Effect.provide(program, DatabaseLive)

Effect.runPromise(runnable).then(console.log)
// Output:
// timestamp=... level=INFO fiber=#0 message="Executing query: SELECT * FROM users"
// []
@see ― provideService for providing a service to an effect.
@since ― 2.0.0
provide(
import NodeContext
NodeContext.
const layer: Layer<NodeContext.NodeContext, never, never>@since ― 1.0.0
layer)))

Finally, run the program in Node.js using tsx, or directly in Deno:

npx tsx index.ts

pnpm dlx tsx index.ts

yarn dlx tsx index.ts

deno run index.ts
# or

deno run -RE index.ts
# Output: tmp/file.txt
# (granting required Read and Environment permissions without being prompted)

Running the Program in Bun

To run the same program in Bun, first install the Bun-specific package:

bun add @effect/platform-bun

Update the program to use the Bun-specific context:

Example (Providing Bun Context)

1
import { 
import Path
Path } from "@effect/platform"
2
import { 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect } from "effect"
3
import { 
import BunContext
BunContext, 
import BunRuntime
BunRuntime } from "@effect/platform-bun"
4

5
const 
const program: Effect.Effect<void, never, Path.Path>
program = 
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const gen: <YieldWrap<Tag<Path.Path, Path.Path>>, void>(f: (resume: Effect.Adapter) => Generator<YieldWrap<Tag<Path.Path, Path.Path>>, void, never>) => Effect.Effect<void, never, Path.Path> (+1 overload)
Provides a way to write effectful code using generator functions, simplifying
control flow and error handling.
When to Use
Effect.gen allows you to write code that looks and behaves like synchronous
code, but it can handle asynchronous tasks, errors, and complex control flow
(like loops and conditions). It helps make asynchronous code more readable
and easier to manage.
The generator functions work similarly to async/await but with more
explicit control over the execution of effects. You can yield* values from
effects and return the final result at the end.
Example
import { Effect } from "effect"

const addServiceCharge = (amount: number) => amount + 1

const applyDiscount = (
  total: number,
  discountRate: number
): Effect.Effect<number, Error> =>
  discountRate === 0
    ? Effect.fail(new Error("Discount rate cannot be zero"))
    : Effect.succeed(total - (total * discountRate) / 100)

const fetchTransactionAmount = Effect.promise(() => Promise.resolve(100))

const fetchDiscountRate = Effect.promise(() => Promise.resolve(5))

export const program = Effect.gen(function* () {
  const transactionAmount = yield* fetchTransactionAmount
  const discountRate = yield* fetchDiscountRate
  const discountedAmount = yield* applyDiscount(
    transactionAmount,
    discountRate
  )
  const finalAmount = addServiceCharge(discountedAmount)
  return `Final amount to charge: ${finalAmount}`
})
@since ― 2.0.0
gen(function* () {
6
  // Access the Path service
7
  const 
const path: Path.Path
path = yield* 
import Path
Path.
const Path: Tag<Path.Path, Path.Path>@since ― 1.0.0
@since ― 1.0.0
@since ― 1.0.0
Path
8

9
  // Join parts of a path to create a complete file path
10
  const 
const mypath: string
mypath = 
const path: Path.Path
path.
Path.join: (...paths: ReadonlyArray<string>) => string
join("tmp", "file.txt")
11

12
  
var console: Console
The console module provides a simple debugging console that is similar to the
JavaScript console mechanism provided by web browsers.
The module exports two specific components:

A Console class with methods such as console.log(), console.error() and console.warn() that can be used to write to any Node.js stream.
A global console instance configured to write to process.stdout and
process.stderr. The global console can be used without importing the node:console module.

Warning: The global console object's methods are neither consistently
synchronous like the browser APIs they resemble, nor are they consistently
asynchronous like all other Node.js streams. See the note on process I/O for
more information.
Example using the global console:
console.log('hello world');
// Prints: hello world, to stdout
console.log('hello %s', 'world');
// Prints: hello world, to stdout
console.error(new Error('Whoops, something bad happened'));
// Prints error message and stack trace to stderr:
//   Error: Whoops, something bad happened
//     at [eval]:5:15
//     at Script.runInThisContext (node:vm:132:18)
//     at Object.runInThisContext (node:vm:309:38)
//     at node:internal/process/execution:77:19
//     at [eval]-wrapper:6:22
//     at evalScript (node:internal/process/execution:76:60)
//     at node:internal/main/eval_string:23:3

const name = 'Will Robinson';
console.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to stderr
Example using the Console class:
const out = getStreamSomehow();
const err = getStreamSomehow();
const myConsole = new console.Console(out, err);

myConsole.log('hello world');
// Prints: hello world, to out
myConsole.log('hello %s', 'world');
// Prints: hello world, to out
myConsole.error(new Error('Whoops, something bad happened'));
// Prints: [Error: Whoops, something bad happened], to err

const name = 'Will Robinson';
myConsole.warn(`Danger ${name}! Danger!`);
// Prints: Danger Will Robinson! Danger!, to err
@see ― source
console.
Console.log(message?: any, ...optionalParams: any[]): void
Prints to stdout with newline. Multiple arguments can be passed, with the
first used as the primary message and all additional used as substitution
values similar to printf(3)
(the arguments are all passed to util.format()).
const count = 5;
console.log('count: %d', count);
// Prints: count: 5, to stdout
console.log('count:', count);
// Prints: count: 5, to stdout
See util.format() for more information.
@since ― v0.1.100
log(
const mypath: string
mypath)
13
})
14

15
import BunRuntime
BunRuntime.
const runMain: RunMain
<never, void>(effect: Effect.Effect<void, never, never>, options?: {
    readonly disableErrorReporting?: boolean | undefined;
    readonly disablePrettyLogger?: boolean | undefined;
    readonly teardown?: Teardown | undefined;
}) => void (+1 overload)
Helps you run a main effect with built-in error handling, logging, and signal management.
Details
This function launches an Effect as the main entry point, setting exit codes
based on success or failure, handling interrupts (e.g., Ctrl+C), and optionally
logging errors. By default, it logs errors and uses a "pretty" format, but both
behaviors can be turned off. You can also provide custom teardown logic to
finalize resources or produce different exit codes.
Options
An optional object that can include:

disableErrorReporting: Turn off automatic error logging.
disablePrettyLogger: Avoid adding the pretty logger.
teardown: Provide custom finalization logic.

When to Use
Use this function to run an Effect as your application’s main program, especially
when you need structured error handling, log management, interrupt support,
or advanced teardown capabilities.
runMain(
const program: Effect.Effect<void, never, Path.Path>
program.
Pipeable.pipe<Effect.Effect<void, never, Path.Path>, Effect.Effect<void, never, never>>(this: Effect.Effect<void, never, Path.Path>, ab: (_: Effect.Effect<void, never, Path.Path>) => Effect.Effect<void, never, never>): Effect.Effect<void, never, never> (+21 overloads)
pipe(
import Effect@since ― 2.0.0
@since ― 2.0.0
@since ― 2.0.0
Effect.
const provide: <BunContext.BunContext, never, never>(layer: Layer<BunContext.BunContext, never, never>) => <A, E, R>(self: Effect.Effect<A, E, R>) => Effect.Effect<A, E, Exclude<R, BunContext.BunContext>> (+9 overloads)
Provides necessary dependencies to an effect, removing its environmental
requirements.
Details
This function allows you to supply the required environment for an effect.
The environment can be provided in the form of one or more Layers, a
Context, a Runtime, or a ManagedRuntime. Once the environment is
provided, the effect can run without requiring external dependencies.
You can compose layers to create a modular and reusable way of setting up the
environment for effects. For example, layers can be used to configure
databases, logging services, or any other required dependencies.
Example
import { Context, Effect, Layer } from "effect"

class Database extends Context.Tag("Database")<
  Database,
  { readonly query: (sql: string) => Effect.Effect<Array<unknown>> }
>() {}

const DatabaseLive = Layer.succeed(
  Database,
  {
    // Simulate a database query
    query: (sql: string) => Effect.log(`Executing query: ${sql}`).pipe(Effect.as([]))
  }
)

//      ┌─── Effect<unknown[], never, Database>
//      ▼
const program = Effect.gen(function*() {
  const database = yield* Database
  const result = yield* database.query("SELECT * FROM users")
  return result
})

//      ┌─── Effect<unknown[], never, never>
//      ▼
const runnable = Effect.provide(program, DatabaseLive)

Effect.runPromise(runnable).then(console.log)
// Output:
// timestamp=... level=INFO fiber=#0 message="Executing query: SELECT * FROM users"
// []
@see ― provideService for providing a service to an effect.
@since ― 2.0.0
provide(
import BunContext
BunContext.
const layer: Layer<BunContext.BunContext, never, never>@since ― 1.0.0
layer)))

Run the program in Bun:

bun index.ts
tmp/file.txt