Environment:Helicone Helicone Node 20 TypeScript Runtime

Knowledge Sources	Helicone Monorepo Node.js
Domains	Infrastructure, Web_Development
Last Updated	2026-02-14 06:00 GMT

Overview

Node.js 20+ runtime with TypeScript 5.x for the Helicone monorepo (web frontend, Jawn backend, worker proxy, and shared packages).

Description

This environment provides the primary application runtime for all JavaScript/TypeScript services in Helicone. The monorepo uses Yarn workspaces and requires Node.js >= 20 across all packages. TypeScript versions vary by package: the web frontend pins 5.1.6, the Jawn backend uses ^5.2.2, and the worker uses ^5.8.3. The dev container provides Node 22 for local development.

Usage

Use this environment for all Helicone application development and deployment. It is required for running the Next.js web dashboard, Express.js Jawn backend, Cloudflare Worker proxy, and all shared packages (cost, llm-mapper, prompts).

System Requirements

Category	Requirement	Notes
OS	Linux (Ubuntu 20.04+) or macOS	Docker uses Debian Bookworm Slim base images
Node.js	>= 20	Enforced via `engines` field in root package.json
Package Manager	Yarn (Classic)	Monorepo uses Yarn workspaces
Disk	2GB+	For node_modules across all workspace packages

Dependencies

System Packages

`node` >= 20 (production images use `node:20.19.4-bookworm-slim`)
`yarn` (Classic, v1.x)
`git` (for Husky hooks)

TypeScript Versions (by package)

`typescript` = 5.1.6 (web frontend, pinned)
`typescript` >= 5.2.2 (Jawn backend)
`typescript` >= 5.8.3 (worker)

Key Framework Dependencies

`next` >= 14.2.30 (web frontend)
`react` = 18.3.1 (web frontend)
`express` >= 5.1.0 (Jawn backend)
`wrangler` >= 4.27.0 (worker development/deployment)

Credentials

The following environment variables must be set in `.env`:

`DATABASE_URL`: PostgreSQL connection string for Supabase
`NEXT_PUBLIC_SUPABASE_URL`: Supabase API URL
`NEXT_PUBLIC_SUPABASE_ANON_KEY`: Supabase anonymous key (public)
`SUPABASE_SERVICE_KEY`: Supabase service role key (secret)
`NEXT_PUBLIC_HELICONE_JAWN_SERVICE`: URL to Jawn backend (default `http://localhost:8585`)
`CLICKHOUSE_HOST`: ClickHouse HTTP interface URL
`CLICKHOUSE_USER`: ClickHouse username
`CLICKHOUSE_PASSWORD`: ClickHouse password

Quick Install

# Install Node.js 20+ via nvm
nvm install 20
nvm use 20

# Install all monorepo dependencies
yarn install

# Build shared packages
yarn workspace @helicone-package/cost build
yarn workspace @helicone-package/llm-mapper build

Code Evidence

Node.js version constraint from `package.json:12-14`:

"engines": {
  "node": ">=20"
}

Docker base image from `valhalla/dockerfile:1`:

FROM node:20.19.4-bookworm-slim

Dev container from `.devcontainer/Dockerfile`:

FROM mcr.microsoft.com/devcontainers/typescript-node:1-22-bookworm

Common Errors

Error Message	Cause	Solution
`The engine "node" is incompatible`	Node.js version < 20	Install Node.js 20+ via nvm: `nvm install 20`
`error TS5023: Unknown compiler option`	TypeScript version mismatch	Check package-specific TS version requirements
`Cannot find module '@helicone-package/cost'`	Shared packages not built	Run `yarn build` in the respective package directory

Compatibility Notes

Dev Container: Uses Node 22 (via Microsoft devcontainer image), which is ahead of production Node 20. Test compatibility before using Node 22 features.
Worker Dockerfile: The worker Docker image at `docker/dockerfiles/dockerfile_worker` uses Node 18.11.0, which is behind the monorepo requirement. This is a legacy image.
Yarn Workspaces: All packages share a single `node_modules` at the root. Individual package builds may need to run in dependency order.

Related Pages

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment