Installation

Effect ships as a single package, effect, that contains the entire core library — the Effect type, Schema, Stream, Layer, and much more. Installing that one package is all you need to start. This page walks you through creating a fresh, strict TypeScript project and running a first program.

Requirements:

• TypeScript 5.8 or newer (Effect v4 is developed and built against TypeScript 6.x — use the latest release for the best results)
• A runtime: Bun, Node.js 18+, or Deno

Caution

Effect relies on strict mode to give you accurate types for the error (E) and requirement (R) channels. Make sure "strict": true is set in your tsconfig.json — without it, inference will be wrong.

Create a project

1. Create a project directory and move into it:

   mkdir hello-effect
   cd hello-effect

2. Initialize the project and install TypeScript and Effect:

   Bun

   bun init -y
   bun add effect
   bun add -d typescript

   npm

   npm init -y
   npm install effect
   npm install --save-dev typescript tsx

   pnpm

   pnpm init
   pnpm add effect
   pnpm add -D typescript tsx

3. Generate a tsconfig.json and make sure strict mode is on:

   Bun

   bun init already creates a tsconfig.json with strict enabled. Verify it contains:

   {
     "compilerOptions": {
       "strict": true
     }
   }

   npm

   npx tsc --init

   Then open tsconfig.json and confirm:

   {
     "compilerOptions": {
       "strict": true
     }
   }

   pnpm

   pnpm tsc --init

   Then open tsconfig.json and confirm:

   {
     "compilerOptions": {
       "strict": true
     }
   }

Write a first program

Create a source file:

mkdir -p src
touch src/index.ts

Add the following to src/index.ts. The program is described as a value, then handed to a runtime to actually run:

src/index.ts

import { Console, Effect } from "effect"

// `Effect.gen` builds an effect in imperative style. Nothing runs yet — this is
// just a description of the work to be done.
const program = Effect.gen(function* () {
  yield* Console.log("Hello, Effect!")
})

// `Effect.runPromise` executes the program and returns a Promise. This is the
// boundary between the Effect world (descriptions) and the outside world.
Effect.runPromise(program)

Run it

Bun

bun run src/index.ts

npm

npx tsx src/index.ts

pnpm

pnpm tsx src/index.ts

You should see Hello, Effect! printed to the console. That confirms your project is set up correctly.

Tip

For a smoother developer experience — better diagnostics and inline error/type hints directly in your editor — install the Effect LSP plugin. It surfaces the E and R channels and catches common mistakes as you type.

Give your coding agent the source

If you write Effect with a coding agent (Claude Code, Cursor, and friends), the single highest-leverage thing you can do for code quality is to let the agent read Effect’s actual source. Agents are far better at exploring real code — following usage patterns, tracing abstractions, learning from existing examples — than at working from human-oriented prose or fragmented web-search snippets. Reading from node_modules usually isn’t enough: the code there is compiled/flattened, and most agents are tuned to skip gitignored directories.

The cleanest way to make the source explorable is to vendor it into your repo as a git subtree. Unlike a submodule, a subtree is just a normal directory — no separate init step, no .gitmodules, nothing you or the agent has to think about.

1. Vendor the Effect source under repos/effect as a single squashed commit:

   git subtree add \
     --prefix=repos/effect \
     https://github.com/Effect-TS/effect.git \
     main \
     --squash

   --squash collapses the upstream history into one commit rather than importing thousands of commits into your project. Keep all vendored repos under one directory (repos/) so a single line in your agent instructions can point at them.

2. Keep your editor out of the vendored copy. In .vscode/settings.json, exclude repos/** from search, file watching, and auto-imports so you never get suggestions or auto-imports from the reference source:

   .vscode/settings.json

   {
     "typescript.preferences.autoImportFileExcludePatterns": ["repos/**"],
     "javascript.preferences.autoImportFileExcludePatterns": ["repos/**"],
     "files.exclude": { "repos/**": true },
     "files.watcherExclude": { "repos/**": true },
     "search.exclude": { "repos/**": true }
   }

3. Make the agent aware of the source and how to use it — in AGENTS.md (or whichever instructions file your agent reads). Be explicit that it is read-only reference, not part of your application:

   AGENTS.md

   ## Vendored repositories
   
   This project vendors external repositories under `repos/`.
   
   - Use them as read-only reference material when working with related libraries.
   - Prefer examples and patterns from the vendored source over guesses or web search.
   - Do not edit files under `repos/` unless explicitly asked.
   - Do not import from `repos/` — application code imports from normal dependencies.
   
   When writing Effect code, inspect `repos/effect/` for idiomatic usage, tests,
   module structure, and API design, and treat it as the source of truth for
   Effect patterns. Always read `repos/effect/LLMS.md` first.

To pull in upstream changes later, run the matching pull — each update lands as one reviewable commit:

git subtree pull \
  --prefix=repos/effect \
  https://github.com/Effect-TS/effect.git \
  main \
  --squash

Tip

Go a step further and have the agent distil a vendored module into a small, project-local pattern file. For example, ask it to read repos/effect’s Schema implementation, tests, and docs and write agent-patterns/effect-schema.md capturing the idioms to follow (constructors, decoding/encoding, transformations, error handling, things to avoid). It then has a durable artifact to reuse instead of rediscovering the same patterns each time.

Note

The trade-off: vendoring grows your repo and you take on keeping it current. In an AI-assisted workflow the gain in output quality is usually well worth it — and the same technique works for any external dependency, not just Effect.

Next steps

Now that everything runs, the Quickstart builds a small but realistic program with services, typed errors, and a Layer. To learn how the package is organized and how to reach the unstable modules (HTTP, CLI, RPC, and more), see Importing Effect.