Registry / web-framework / effect-http-node

effect-http-node

library0.27.0jsnpmunverified

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.

web-framework http-networking

npm install effect-http-node

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · EFFECT-HTTP-NODE

effect-http-node

web-frameworkjavascriptv0.27.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

NodeServer

✓ import { NodeServer } from 'effect-http-node';

✗ const NodeServer = require('effect-http-node').NodeServer;

Used for creating a Node.js HTTP server instance from an `effect-http` application. The Effect ecosystem is primarily ESM-first.

NodeRuntime

✓ import * as NodePlatform from '@effect/platform-node'; // ... NodePlatform.NodeRuntime.runMain(program);

✗ import { NodeRuntime } from '@effect/platform-node';

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.

Api

✓ import { Api } from 'effect-http';

Although `Api` is from `effect-http`, it's fundamental for defining the API contract that `effect-http-node` then serves.

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.

import { pipe, Effect } from 'effect'; import { Api, Router } from 'effect-http'; import { NodeServer } from 'effect-http-node'; import * as NodePlatform from '@effect/platform-node'; import * as Logger from '@effect/data/Logger'; // 1. Define your API using effect-http const api = Api.make().pipe( Api.get('hello', '/hello', { response: Api.string(), }), Api.post('echo', '/echo', { request: { body: Api.string(), }, response: Api.string(), }), ); // 2. Implement the API handlers const app = Router.make(api).pipe( Router.handle('hello', () => Effect.succeed('Hello from Effect-HTTP!')), Router.handle('echo', ({ body }) => Effect.succeed(`You said: ${body}`)), ); // 3. Create a Node.js server from the API and application const server = NodeServer.make(app, { port: 3000 }); // 4. Run the server using NodePlatform.NodeRuntime pipe( server.pipe( Effect.tap(() => Effect.logInfo('Server started on http://localhost:3000'), ), ), NodePlatform.NodeRuntime.runMain, );

Debug

Known issues

breakingThe `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.

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.

affects: >=0.2.0

gotchaDue 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.

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.

affects: >=0.1.0

gotchaThe 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.

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.

affects: >=0.1.0

Errors

Common errors & fixes

Error: EADDRINUSE: address already in use :::3000

The specified port (e.g., 3000) is already occupied by another process.

fix

Change the `port` in `NodeServer.make` to an available port, or terminate the process currently using the port.

TypeError: (0 , effect_http_node_1.NodeServer.make) is not a function

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.

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.

TS2345: Argument of type 'Api<...>' is not assignable to parameter of type 'HttpApp<...>'

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.

fix

Ensure you've created an `EffectHttp.Router` instance by calling `Router.make(api).pipe(Router.handle(...))` before passing it to `NodeServer.make`.

Upgrade

Version history

0.27.0latest on npm

Audit

Dependencies

@effect/platformrequiredCore Effect platform abstractions for HTTP, required by effect-http.

@effect/platform-noderequiredNode.js-specific platform implementation for running Effect programs, including HTTP servers.

effectrequiredThe core Effect-TS library, providing the foundational functional programming primitives, type system, and runtime.

effect-httprequiredThe declarative HTTP API definition and routing library, for which `effect-http-node` provides the Node.js server implementation.

Agent activity

9 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/sukovanej/effect-http ↗

packagehttps://www.npmjs.com/package/effect-http-node ↗

homepagehttps://effect.website ↗