{"id":17212,"library":"effect-http","title":"Effect HTTP","description":"effect-http is a high-level, declarative, and type-safe HTTP API layer built specifically for the `effect-ts` ecosystem. It leverages `Effect`'s powerful functional programming primitives, including Effects, Layers, and Schemas, to provide a robust framework for defining both HTTP servers and clients. Currently at version 0.87.0, the library maintains a rapid release cadence, often issuing minor version updates to align with ongoing developments and breaking changes within its core peer dependency, `effect`. This close coupling ensures full compatibility and leverages the latest features of `effect-ts`, but also means users should expect frequent dependency updates. Its primary differentiation lies in its deep integration with the `Effect` paradigm, offering end-to-end type safety from API definition to implementation and client consumption, while remaining platform-agnostic at its core (`effect-http` package) with specific adapters like `effect-http-node` for server execution. It promotes a functional and declarative style for building robust, concurrent, and error-handled web services.","status":"active","version":"0.87.0","language":"javascript","source_language":"en","source_url":"https://github.com/sukovanej/effect-http","tags":["javascript","typescript"],"install":[{"cmd":"npm install effect-http","lang":"bash","label":"npm"},{"cmd":"yarn add effect-http","lang":"bash","label":"yarn"},{"cmd":"pnpm add effect-http","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides platform-agnostic HTTP server/client primitives and utilities, foundational for network operations in the Effect ecosystem.","package":"@effect/platform","optional":false},{"reason":"The core functional programming library providing the Effect data type, Layers for dependency management, and Schemas for data validation, which effect-http is built upon.","package":"effect","optional":false}],"imports":[{"note":"Most effect-ts related modules prefer a namespace import (e.g., `* as Api`) due to numerous exports and potential naming conflicts.","wrong":"import { Api } from 'effect-http';","symbol":"Api","correct":"import * as Api from 'effect-http/Api';"},{"note":"Similar to `Api`, `Router` is typically imported as a namespace to access its various functions for building HTTP handlers and services.","wrong":"import { Router } from 'effect-http';","symbol":"Router","correct":"import * as Router from 'effect-http/Router';"},{"note":"The `Client` module provides functions for generating type-safe clients from an `Api` definition. Use `Client.make` or similar.","wrong":"import { Client } from 'effect-http';","symbol":"Client","correct":"import * as Client from 'effect-http/Client';"}],"quickstart":{"code":"import * as Effect from 'effect';\nimport * as Schema from '@effect/schema/Schema';\nimport * as Http from '@effect/platform/Http';\nimport * as NodeHttpServer from '@effect/platform-node/HttpServer';\nimport * as NodeHttpClient from '@effect/platform-node/HttpClient';\nimport * as Api from 'effect-http/Api';\nimport * as Router from 'effect-http/Router';\nimport * as Client from 'effect-http/Client';\n\n// 1. Define your API schema\nconst MyApi = Api.api().pipe(\n  Api.get('getUser', '/users/:id', {\n    request: { params: Schema.struct({ id: Schema.NumberFromString }) },\n    response: Schema.struct({ id: Schema.number, name: Schema.string }),\n  }),\n  Api.post('createUser', '/users', {\n    request: { body: Schema.struct({ name: Schema.string }) },\n    response: Schema.struct({ id: Schema.number, name: Schema.string }),\n  }),\n);\n\n// 2. Implement the handlers\nconst app = Router.make(MyApi).pipe(\n  Router.handle('getUser', ({ params }) =>\n    Effect.succeed({\n      id: params.id,\n      name: `User ${params.id}`,\n    }),\n  ),\n  Router.handle('createUser', ({ body }) =>\n    Effect.succeed({\n      id: Math.floor(Math.random() * 1000) + 1,\n      name: body.name,\n    }),\n  ),\n);\n\n// 3. Set up the Node.js server\nconst server = NodeHttpServer.server.pipe(\n  Effect.tap((s) => Http.server.serve(app, s)),\n  Effect.scoped,\n  Effect.provide(NodeHttpServer.layer(() => Http.listeningOn({ port: 3000 }))),\n);\n\n// 4. Create a client for the API\nconst myClient = Client.make(MyApi);\nconst httpClient = Http.client.fetch.pipe(NodeHttpClient.layer); // Use Node's fetch\n\n// 5. Run the server and make a client request\nconst program = Effect.gen(function* () {\n  yield* Effect.fork(server);\n  yield* Effect.sleep('100ms'); // Give server time to start\n\n  const getUserResult = yield* myClient.getUser({ params: { id: 1 } });\n  console.log('GET /users/1 result:', getUserResult);\n\n  const createUserResult = yield* myClient.createUser({ body: { name: 'Alice' } });\n  console.log('POST /users result:', createUserResult);\n\n  yield* Effect.log('Server and client interaction complete. Stopping server.');\n}).pipe(Effect.provide(httpClient));\n\nEffect.runPromise(program);\n","lang":"typescript","description":"This quickstart defines a simple REST API with GET and POST endpoints, implements them using `effect-http/Router`, starts a Node.js server with `effect-http-node`, and then uses `effect-http/Client` to interact with the running API programmatically."},"warnings":[{"fix":"Pin `effect-http` and `effect` dependencies to specific versions, or review release notes for both `effect-http` and `effect` when upgrading to manage breaking changes. Use `npm install effect-http@latest effect@latest` cautiously.","message":"effect-http frequently updates its peer dependencies on `effect` and `@effect/platform`. Minor version bumps in effect-http often correspond to minor or patch updates in `effect` itself, which can include breaking changes in the underlying `effect-ts` library. Always review the `effect-ts` changelog when updating `effect-http`.","severity":"breaking","affected_versions":">=0.1.0"},{"fix":"For Node.js server environments, install `effect-http-node` (`npm install effect-http-node`) and use its server utilities (e.g., `NodeHttpServer.server`).","message":"The `effect-http` package itself is platform-agnostic, primarily providing the API definition and routing logic. To run an HTTP server, you must install and use a platform-specific adapter like `effect-http-node` for Node.js environments or `effect-http-express` for Express.js integration.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Consult the `effect-ts` migration guides for upgrading to `effect` v3. Ensure all `effect` ecosystem libraries, including `effect-http`, are compatible with your target `effect` version. `effect-http` versions >=0.80.0 are generally aligned with `effect` v3.","message":"The `effect` library, upon which `effect-http` is built, underwent significant breaking changes in its transition to version 3. If you are migrating from an `effect` v2 (or earlier) project, expect extensive code refactoring, especially around `Layer` composition, `Effect` constructors, and `Schema` usage.","severity":"breaking","affected_versions":"<3.0.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Ensure every operation defined in `Api.api()` has a corresponding handler attached to the `Router.make(api)` instance using `Router.handle('operationName', handlerFunction)`.","cause":"You have defined an operation in your `Api` but have not provided an implementation for it using `Router.handle('myOperation', ...)`.","error":"Error: Operation 'myOperation' not found or has no handler attached."},{"fix":"Verify that all necessary dependencies (Layers) are provided to your `Effect` program. Use `Effect.provide()` or `Layer.merge()`/`Layer.provide()` correctly to ensure services are available in the desired scope. Inspect the specific line number for the `undefined` value.","cause":"This often indicates that you're trying to call a method like `pipe` on `undefined` because a dependency was not provided or an `Effect` did not resolve as expected, commonly seen when `Layer` composition is incorrect.","error":"TypeError: Cannot read properties of undefined (reading 'pipe')"},{"fix":"Review the `Schema` definition for the affected operation in your `Api`. Ensure that the data being sent or received by the client/server matches the structure and types specified by the `Schema`.","cause":"This error occurs when an incoming request (e.g., body, params, query) or an outgoing response does not conform to the `Schema` defined in your `Api` for that specific operation.","error":"Error: Decoding error: (Schema validation details)"}],"ecosystem":"npm","meta_description":null}