ThreadForge

A multi-threaded Node.js service runtime framework. Deploy multiple services on the same machine, intelligently distributed across available CPU cores, with built-in IPC messaging, metrics, and lifecycle management.

Why ThreadForge?

Node.js runs on a single thread. Modern servers have 16, 32, 64+ cores. ThreadForge bridges that gap by giving you a declarative way to run multiple services across all available cores — with zero-overhead inter-service communication via IPC instead of HTTP.

Key features:

• Declarative service config — define services, ports, thread allocation, and topology in one file
• Smart thread allocation — auto-distributes cores by weight, or set fixed counts
• 3-tier IPC resolution — colocated (direct call) → Unix Domain Socket → HTTP fallback
• Colocation groups — pack lightweight services into a shared process for zero-overhead calls
• TC39 decorators — @Route, @Expose, @Emit, @On, @Validate and more
• Plugin system — Redis, PostgreSQL, S3, CORS, Cron, Realtime — with custom plugin support
• Auto-restart — crashed workers are automatically replaced
• Runtime scaling — scale services up/down without restarting
• RequestContext propagation — correlation IDs, auth, deadlines, and baggage across services
• Built-in metrics — Prometheus-compatible endpoint with HTTP, RPC, and event loop lag metrics
• Multi-machine deployment — grow from one machine to a full cluster with forge.deploy.js

Quick Start

Option 1: Install from npm (Recommended)

# Create and scaffold a new project
mkdir my-app && cd my-app
npm init -y
npm install threadforge
npx forge init . --source npm
npm install

# Start in development mode (hot reload)
npm run dev

# Start in production mode
npm run start

forge dev / forge start now auto-start ForgeProxy by default and generate local route manifests under .threadforge/routes. Use --no-proxy to bypass proxy orchestration (for example, when ForgeProxy is not installed locally):

npx forge dev --no-proxy
npx forge start --no-proxy

Option 2: Local Development (ThreadForge contributors only)

# Clone and link ThreadForge locally
git clone https://github.com/ChrisBland/threadforge.git
cd threadforge
npm install
npm link

# Create your project
mkdir my-app && cd my-app
npm link threadforge
forge init . --source local
npm install

# Start
npm run dev

If forgeproxy is installed outside your PATH, set FORGEPROXY_BIN:

FORGEPROXY_BIN=/absolute/path/to/forgeproxy npm run dev

forge init is backend-only by default. Add static frontend scaffolding with npx forge scaffold frontend (or npx forge init . --with-frontend), or generate Vite + React with npx forge scaffold frontend --react (or npx forge init . --with-react).

Create forge.config.js:

import { defineServices, ServiceType } from 'threadforge';

export default defineServices({
  api: {
    entry: './services/api.js',
    type: ServiceType.EDGE,
    port: 3000,
    threads: 'auto',
    connects: ['users'],
  },

  users: {
    entry: './services/users.js',
    type: ServiceType.INTERNAL,
  },
});

Create services/api.js:

import { HttpMethod, Service, Route } from 'threadforge';

export default class ApiService extends Service {
  @Route(HttpMethod.GET, '/users/:id')
  async getUser(body, params) {
    return await this.users.getUser(params.id);
  }
}

Create services/users.js:

import { Service, Expose } from 'threadforge';

export default class UsersService extends Service {
  async onStart(ctx) {
    this.store = new Map([['1', { id: '1', name: 'Alice' }]]);
  }

  @Expose()
  async getUser(id) {
    return this.store.get(String(id)) ?? null;
  }
}

npm run start
# curl http://localhost:3000/users/1
# → {"id":"1","name":"Alice"}

With proxy orchestration enabled (default), you can also hit the local ForgeProxy ingress (typically http://127.0.0.1:8080 when free).

Platform Mode Quick Flow

For multi-site projects (multiple apps/domains with per-app services/frontends):

mkdir platform-app && cd platform-app
npm init -y
npm install threadforge
npx forge platform init
npx forge platform add sitea
npx forge platform add siteb

# then edit forge.platform.js:
# - add platform.apps.<appId> with domains/services/frontend
# - add top-level '<appId>-api' service entries with unique ports
# - register frontendPlugins (for example: viteFrontend())
# - create each frontend project (for example: apps/sitea/web and apps/siteb/web)

# install frontend deps for each site before build
# (example)
# cd apps/sitea/web && npm install
# cd ../../siteb/web && npm install
# cd ../../../

npx forge build
npx forge platform generate
npx forge platform start

forge platform start auto-manages ForgeProxy by default. If ForgeProxy is unavailable locally, use:

npx forge platform start --no-proxy

See:

• docs/guides/plugins.md for frontend plugin config (viteFrontend)
• docs/reference/configuration.md for definePlatform() schema
• docs/reference/cli.md for all forge platform subcommands
• examples/platform-two-app-react-date-time/README.md for a runnable two-site date/time + React example
• examples/platform-kitchen-sink/README.md for shared auth/users + event-driven multi-site example
• examples/threads-overprovision/README.md for graceful handling when requested threads exceed host CPU capacity

Documentation

Full documentation is in the docs/ directory:

• Getting Started — Install, create your first service, and run it
• Architecture — Process model, communication layers, request lifecycle
• Guides:
  • Single-App React Date/Time Quickstart — One app with /time, /date, and a React frontend
  • Services — Types, lifecycle, colocation, plain JS fallback
  • IPC & Communication — Proxy clients, events, interceptors
  • Plugins — Redis, PostgreSQL, S3, CORS, Cron, Realtime
  • Platform Two-App React Quickstart — Multi-site apps with per-site API + frontend
  • Deployment — Single machine to multi-machine scaling
• Reference:
  • Configuration — All forge.config.js options
  • Decorators — Full decorator API
  • CLI — Commands, options, metrics endpoints
  • API — All public exports
• ForgeProxy — Rust gateway architecture and ingress role

License

MIT