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 { Path } from "@effect/platform"
2
import { Effect } from "effect"
3

4
const program = Effect.gen(function* () {
5
  // Access the Path service
6
  const path = yield* Path.Path
7

8
  // Join parts of a path to create a complete file path
9
  const mypath = path.join("tmp", "file.txt")
10

11
  console.log(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 { Path } from "@effect/platform"
2
import { Effect } from "effect"
3
import { NodeContext, NodeRuntime } from "@effect/platform-node"
4

5
const program = Effect.gen(function* () {
6
  // Access the Path service
7
  const path = yield* Path.Path
8

9
  // Join parts of a path to create a complete file path
10
  const mypath = path.join("tmp", "file.txt")
11

12
  console.log(mypath)
13
})
14

15
NodeRuntime.runMain(program.pipe(Effect.provide(NodeContext.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 { Path } from "@effect/platform"
2
import { Effect } from "effect"
3
import { BunContext, BunRuntime } from "@effect/platform-bun"
4

5
const program = Effect.gen(function* () {
6
  // Access the Path service
7
  const path = yield* Path.Path
8

9
  // Join parts of a path to create a complete file path
10
  const mypath = path.join("tmp", "file.txt")
11

12
  console.log(mypath)
13
})
14

15
BunRuntime.runMain(program.pipe(Effect.provide(BunContext.layer)))

Run the program in Bun:

bun index.ts
tmp/file.txt