# 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](https://bun.sh/), [Node.js](https://nodejs.org/) 18+, or
  [Deno](https://deno.com/)
**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:

   ```sh
   mkdir hello-effect
   cd hello-effect
   ```

2. Initialize the project and install TypeScript and Effect:

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

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

   ```sh
   pnpm init
   pnpm add effect
   pnpm add -D typescript tsx
   ```

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

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

   ```json
   {
     "compilerOptions": {
       "strict": true
     }
   }
   ```

   ```sh
   npx tsc --init
   ```

   Then open `tsconfig.json` and confirm:

   ```json
   {
     "compilerOptions": {
       "strict": true
     }
   }
   ```

   ```sh
   pnpm tsc --init
   ```

   Then open `tsconfig.json` and confirm:

   ```json
   {
     "compilerOptions": {
       "strict": true
     }
   }
   ```

   ## Write a first program

Create a source file:

```sh
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:

```ts title="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

```sh
bun run src/index.ts
```

```sh
npx tsx src/index.ts
```

```sh
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](https://github.com/Effect-TS/language-service). 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](https://effect.website/blog/the-one-weird-git-trick-that-makes-coding-agents-more-effect-ive/)**.
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:

   ```sh
   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:

   ```json title=".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:

   ```md title="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:

```sh
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](https://effect.plants.sh/introduction/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](https://effect.plants.sh/introduction/importing-effect/).