{"id":17213,"library":"effect-http-node","title":"Effect HTTP Node.js Server","description":"effect-http-node is a crucial adapter package within the `effect-ts` ecosystem, providing the Node.js-specific implementation for serving declarative HTTP APIs built with `effect-http`. It leverages the `@effect/platform-node` package to bridge `effect-http`'s server abstractions with Node.js's native HTTP server capabilities, enabling developers to run highly type-safe, functional, and concurrently managed web services. The current stable version is 0.27.0. This package, along with `effect-http` and core `effect` libraries, follows a rapid release cadence, often undergoing minor version bumps to align with updates in its peer dependencies, reflecting the active development of the `effect-ts` project. Its key differentiator lies in enabling the `effect-ts` programming model—emphasizing structured concurrency, resource management, and robust error handling—directly within Node.js for HTTP services, providing a strong alternative to traditional imperative frameworks. It does not introduce new HTTP API paradigms but rather provides the runtime environment for `effect-http`'s existing ones.","status":"active","version":"0.27.0","language":"javascript","source_language":"en","source_url":"https://github.com/sukovanej/effect-http","tags":["javascript","typescript"],"install":[{"cmd":"npm install effect-http-node","lang":"bash","label":"npm"},{"cmd":"yarn add effect-http-node","lang":"bash","label":"yarn"},{"cmd":"pnpm add effect-http-node","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core Effect platform abstractions for HTTP, required by effect-http.","package":"@effect/platform","optional":false},{"reason":"Node.js-specific platform implementation for running Effect programs, including HTTP servers.","package":"@effect/platform-node","optional":false},{"reason":"The core Effect-TS library, providing the foundational functional programming primitives, type system, and runtime.","package":"effect","optional":false},{"reason":"The declarative HTTP API definition and routing library, for which `effect-http-node` provides the Node.js server implementation.","package":"effect-http","optional":false}],"imports":[{"note":"Used for creating a Node.js HTTP server instance from an `effect-http` application. The Effect ecosystem is primarily ESM-first.","wrong":"const NodeServer = require('effect-http-node').NodeServer;","symbol":"NodeServer","correct":"import { NodeServer } from 'effect-http-node';"},{"note":"While `NodeRuntime` is from `@effect/platform-node`, it is essential for running `Effect` programs, including the server, in a Node.js environment. It's often imported as a namespace.","wrong":"import { NodeRuntime } from '@effect/platform-node';","symbol":"NodeRuntime","correct":"import * as NodePlatform from '@effect/platform-node';\n// ...\nNodePlatform.NodeRuntime.runMain(program);"},{"note":"Although `Api` is from `effect-http`, it's fundamental for defining the API contract that `effect-http-node` then serves.","symbol":"Api","correct":"import { Api } from 'effect-http';"}],"quickstart":{"code":"import { pipe, Effect } from 'effect';\nimport { Api, Router } from 'effect-http';\nimport { NodeServer } from 'effect-http-node';\nimport * as NodePlatform from '@effect/platform-node';\nimport * as Logger from '@effect/data/Logger';\n\n// 1. Define your API using effect-http\nconst api = Api.make().pipe(\n  Api.get('hello', '/hello', {\n    response: Api.string(),\n  }),\n  Api.post('echo', '/echo', {\n    request: {\n      body: Api.string(),\n    },\n    response: Api.string(),\n  }),\n);\n\n// 2. Implement the API handlers\nconst app = Router.make(api).pipe(\n  Router.handle('hello', () => Effect.succeed('Hello from Effect-HTTP!')), \n  Router.handle('echo', ({ body }) => Effect.succeed(`You said: ${body}`)),\n);\n\n// 3. Create a Node.js server from the API and application\nconst server = NodeServer.make(app, { port: 3000 });\n\n// 4. Run the server using NodePlatform.NodeRuntime\npipe(\n  server.pipe(\n    Effect.tap(() =>\n      Effect.logInfo('Server started on http://localhost:3000'),\n    ),\n  ),\n  NodePlatform.NodeRuntime.runMain,\n);","lang":"typescript","description":"This quickstart demonstrates defining a simple `effect-http` API, implementing its handlers, and serving it using `effect-http-node` within a Node.js runtime. It includes a GET and a POST endpoint."},"warnings":[{"fix":"Begin migrating your HTTP API definitions and server implementations to use the `@effect/platform` and `@effect/platform-node` modules directly for server creation and routing. `effect-http` will only receive Effect updates and critical patches.","message":"The `effect-http` library, and by extension `effect-http-node`, is considered 'deprecated in favour of the @effect/platform' as of August 30, 2024. Users are advised to migrate to `@effect/platform` for future-proof HTTP server development within the Effect ecosystem.","severity":"breaking","affected_versions":">=0.2.0"},{"fix":"Always keep `effect`, `@effect/platform`, `@effect/platform-node`, and `effect-http` (and `effect-http-node`) at compatible versions, ideally by updating them simultaneously or frequently checking the `effect-http` changelog for specific dependency requirements. Use a lockfile (pnpm-lock.yaml, yarn.lock, package-lock.json) to ensure consistent dependency resolution.","message":"Due to the rapid development and interconnectedness of the Effect-TS ecosystem, frequent minor version updates across `effect`, `@effect/platform`, `@effect/platform-node`, and `effect-http` are common. Mismatched peer dependencies can lead to runtime errors or subtle type-system inconsistencies.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Refer to the official Effect documentation, especially sections on error handling, schema, and basic Effect patterns. Ensure your TypeScript configuration is strict, and gradually introduce Effect concepts.","message":"The Effect ecosystem is designed for TypeScript and leverages advanced type features. Incorrect type inference or usage can lead to complex type errors. While powerful, this can be a learning curve for developers new to Effect.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-22T00:00:00.000Z","next_check":"2026-07-21T00:00:00.000Z","problems":[{"fix":"Change the `port` in `NodeServer.make` to an available port, or terminate the process currently using the port.","cause":"The specified port (e.g., 3000) is already occupied by another process.","error":"Error: EADDRINUSE: address already in use :::3000"},{"fix":"Ensure your project is configured for ESM (e.g., `\"type\": \"module\"` in `package.json`) and use `import { NodeServer } from 'effect-http-node';` syntax. Avoid `require()` for Effect-TS modules.","cause":"This error typically indicates an ESM/CJS module incompatibility. You might be trying to `require` an ESM-only module or using incorrect named/default import syntax.","error":"TypeError: (0 , effect_http_node_1.NodeServer.make) is not a function"},{"fix":"Ensure you've created an `EffectHttp.Router` instance by calling `Router.make(api).pipe(Router.handle(...))` before passing it to `NodeServer.make`.","cause":"The `NodeServer.make` function expects an `HttpApp` (an implemented router), not just an `Api` definition. The `Api` needs to be transformed into a `Router` (application) with handlers.","error":"TS2345: Argument of type 'Api<...>' is not assignable to parameter of type 'HttpApp<...>'"}],"ecosystem":"npm","meta_description":null}