Skip to content
Get packs

Guide · Open source

How to use Effect in TypeScript: install and get started

Updated · written with AI from the project's own documentation and checked against our catalogue data

Effect is an MIT-licensed TypeScript library for building production-grade applications that need typed errors, dependency injection, structured concurrency, scheduling, tracing and schema validation. This guide shows you how to check your setup, install the core package and choose the integration packages you need. It is written for developers who are new to Effect but comfortable with TypeScript.

EffectEffect-TS/effect · ★ 17.5k · MIT

Quick start

  1. 1Check the requirements. Confirm your TypeScript and Node.js versions meet the minimums in the README Requirements section. Make sure the strict flag is enabled in tsconfig.json.
  2. 2Install the core package. Run npm install effect in your project folder. The core package is named effect.
  3. 3Pick your version. Use the current LTS documentation for new projects, or follow the migration guide if you are coming from Effect 3.x.
  4. 4Add integration packages. Install only the platform, SQL or AI packages your project needs, such as @effect/platform-node for Node.js or @effect/sql-pg for PostgreSQL.
  5. 5Read the docs and get help. Use the API reference and guides on effect.website. Ask questions in the Discord or report bugs on the GitHub Issues page.

What Effect helps you handle

Effect is a library, not a framework. You add it to a TypeScript project to handle problems that tend to get harder as a codebase grows: errors that show up in types, dependencies passed in explicitly, concurrent work that is structured and observable, retries and scheduling, tracing, and one approach to validating data with schemas.

The README says Effect is aimed at larger, long-lived systems. It is organized as a core package plus integration packages for platforms, databases and AI providers.

  • Typed errors
  • Dependency injection
  • Structured concurrency
  • Scheduling
  • Tracing
  • Unified schema validation

Check your environment before you install

Effect has explicit requirements. Confirm them before you install anything, because the library will not be useful in an older setup.

Look at the Requirements section of the README for the minimum TypeScript and Node.js versions. The README recommends the newest TypeScript release for the best performance and compatibility with its tooling. It also requires the strict flag to be enabled in your tsconfig.json.

  • TypeScript: use the minimum version listed in the README Requirements section, or newer. The README recommends the newest release.
  • Node.js: use the minimum version listed in the README for running Effect on Node.js.
  • tsconfig.json: set the strict flag to true.

Install the core Effect package

Effect is installed with a package manager. The README gives one install command for the core package, run from your project folder.

The core package is named effect. Install it first. You add integration packages only when your project needs them.

npm install effect

Add integration packages for your platform and database

The core package is extended by separate packages. Pick only the ones that match your runtime, database or AI provider. The README lists platform packages for browser, Bun, Deno and Node.js, plus SQL clients for databases such as PostgreSQL, MySQL, SQLite variants, ClickHouse and Microsoft SQL Server.

Each package has its own API reference page on the Effect website. The README notes that all packages are released together with synchronized versions.

  • @effect/platform-node: platform services for Node.js
  • @effect/platform-bun: platform services for Bun
  • @effect/platform-deno: platform services for Deno
  • @effect/platform-browser: platform services for the browser
  • @effect/sql-pg: SQL client for PostgreSQL
  • @effect/sql-mysql2: SQL client for MySQL
  • @effect/ai-openai: OpenAI provider for the Effect AI modules

Know which major version to follow

The README centers Effect 4.x, which it describes as a long-term support release. If you are upgrading from Effect 3.x, follow the migration guide in the repository. The v3 source code lives on its own branch, and issues and pull requests for v3 should target that branch.

The README states support commitments for the LTS release: at least three years of support including bug and security fixes, bug fixes for one year after the next major version, and security fixes for two years after the next major version. Stable APIs only get breaking changes in major releases.

  • Starting a new project: follow the current LTS documentation on the Effect website.
  • Upgrading from 3.x: read the migration guide before changing code.
  • Existing v3 code: use the v3 branch for related issues and pull requests.

Get help and stay informed

The README links to the official documentation and guides on the Effect website. For questions and feedback, it points to the Discord server, where you can talk to the core team. Bug reports and feature requests go to the GitHub issues page.

The README also lists a community hub for meetups and events, and an Effect jobs page for companies hiring Effect developers.

  • Documentation and guides: effect.website
  • Questions and discussion: the Effect Discord
  • Bugs and feature requests: the GitHub Issues page
  • Community events: the community hub on effect.website

What people use it for

  • Building a large back-end service where errors and dependencies should be tracked by the type system
  • Running structured concurrency and tracing in a long-lived Node.js, Bun or Deno service
  • Connecting a TypeScript service to PostgreSQL, MySQL, SQLite or ClickHouse through Effect's SQL packages
  • Adding AI provider integrations such as OpenAI, Anthropic or OpenRouter through the Effect AI packages

Frequently asked questions

Is Effect free to use?

Yes. The repository is licensed under MIT. The README does not mention any paid tier for the library itself, though it lists adoption partners who offer consulting, training and commercial support.

What do I need to install Effect?

You need a TypeScript version and a Node.js version at or above the minimums in the README Requirements section. Your tsconfig.json must enable the strict flag. Then run npm install effect.

Does Effect work with Bun and Deno?

The README lists integration packages for Bun and Deno, named @effect/platform-bun and @effect/platform-deno. Node.js has its own package, @effect/platform-node.

Should I use Effect for a small script or simple website?

The README says Effect is aimed at larger and long-lived applications. It notes that the library adds conceptual overhead that it does not try to justify for small scripts or simple sites.

What are the alternatives to Effect?

The README lists comparable projects: fp-ts, neverthrow, RxJS and Zod. The README does not include a detailed comparison, so read each project's documentation to decide which fits your needs.

Where do I get help if something does not work?

The README points to the Discord server for questions and the GitHub Issues page for bug reports. The official documentation is on effect.website.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Effect suits teams building large or long-lived TypeScript back-end services who want errors and dependencies tracked in the type system and are comfortable with functional patterns. Skip it for small scripts, simple sites, or projects that cannot meet the README's requirements; for lighter needs, a comparable project such as Zod or neverthrow may be a better fit.

Install options & downloads