Learn

Install and First Effect

Install

npm install effect@rc

Gotcha: Effect v4 is published under the rc tag. npm install effect gives you v3 stable, which has a different API surface.

Requirements

  • TypeScript 5.9 or higher
  • strict: true in tsconfig.json
  • Node.js 18+, Deno, or Bun
{
  "compilerOptions": {
    "strict": true,
    "target": "ES2022",
    "moduleResolution": "bundler"
  }
}

Hello World

import { Effect, Console } from "effect"

const program = Console.log("Hello, World!")

Effect.runSync(program)
// Output: Hello, World!

Console.log returns an Effect. Nothing runs until you call a runtime function. This is the core Effect principle: build a description of the computation, then execute it.

Create Effects from Values

import { Effect } from "effect"

const succeed = Effect.succeed(42)
// Effect.Effect<number, never, never>

const fail = Effect.fail("something went wrong")
// Effect.Effect<never, string, never>

The type signature is Effect<Success, Error, Requirements>. You read it as: “this effect produces a number on success, can fail with a string, and requires no services.”

Run Effects

import { Effect } from "effect"

const sync = Effect.succeed(42)

// Synchronous execution - only works if the effect has no async operations
const result = Effect.runSync(sync)
// => 42

// Async execution - returns a Promise
const asyncResult = Effect.runPromise(Effect.succeed("hello"))
// Promise<"hello">

Gotcha: Effect.runSync throws if the effect is async or fails. Use Effect.runPromise for anything involving promises, timers, or I/O.

A Slightly Bigger Example

import { Effect, Console } from "effect"

const program = Effect.gen(function*() {
  yield* Console.log("Computing...")
  const value = yield* Effect.succeed(6 * 7)
  yield* Console.log(`Answer: ${value}`)
  return value
})

Effect.runPromise(program).then(console.log)
// Output:
// Computing...
// Answer: 42
// 42

Effect.gen lets you write imperative-style code using generators. Each yield* unwraps an Effect and gives you its success value. If any yielded effect fails, the generator short-circuits.

Next Steps