Project Setup

Creating the Project

Run the following commands to create a new directory and initialize it as a Node.js project:

1
mkdir effect-http-server
2
cd effect-http-server
3
pnpm init

Installing Dependencies

Run the following command to install the dependencies:

1
pnpm add effect@4.0.0-beta.66 @effect/platform-node@4.0.0-beta.66
2
pnpm add -D typescript tsx @types/node

What is @effect/platform-node and why do we need it?

Effect ships an HTTP module (effect/unstable/http) that defines platform-agnostic interfaces for servers, requests, responses, and routing, but it doesn’t include any code that actually binds to a network port. Since we’re building on Node.js, we need something that connects those interfaces to the Node.js runtime. That’s what @effect/platform-node provides. Its NodeHttpServer plugs Node’s built-in node:http module into Effect’s HttpServer, so the server can listen on a port and handle real requests.

Configuring the Project

Add "type": "module" to your package.json and replace the test script with a dev script as shown below:

1
{
2
  "name": "effect-http-server",
3
  "version": "1.0.0",
4
  "description": "",
5
  "main": "index.js",
6
  "scripts": {
7
    "dev": "tsx watch server.ts"
8
  },
9
  "keywords": [],
10
  "author": "",
11
  "license": "ISC",
12
  "type": "module",
13
  "packageManager": "pnpm@10.33.1",
14
  "dependencies": {
15
    "@effect/platform-node": "4.0.0-beta.66",
16
    "effect": "4.0.0-beta.66"
17
  },
18
  "devDependencies": {
19
    "@types/node": "^25.8.0",
20
    "tsx": "^4.22.0",
21
    "typescript": "^6.0.3"
22
  }
23
}

To start the dev server, you’ll run pnpm dev, which will run tsx watch server.ts under the hood.

tsx is a TypeScript execution environment for Node.js. Node.js (v22.18.0 and later) can run TypeScript files natively. However, tsx offers additional features like watch mode, which makes it a better fit for development. Watch mode automatically re-runs your script whenever any of its imported files are changed. So every time you save a change, tsx will re-run server.ts for you.

Note that the server.ts file doesn’t exist yet; we’ll create it in a later chapter.

Configuring TypeScript

Create a tsconfig.json file in the project root:

1
{
2
  "compilerOptions": {
3
    "target": "ES2022",
4
    "module": "nodenext",
5
    "moduleResolution": "nodenext",
6
    "strict": true,
7
    "skipLibCheck": true,
8
    "forceConsistentCasingInFileNames": true,
9
    "rootDir": ".",
10
    "outDir": "./dist"
11
  },
12
  "include": ["ecom/**/*.ts"]
13
}

Your project setup is now complete.