Flare 0.1.x is pre-release. Expect breaking changes before 1.0 — see the changelog.

Flare

Flare is a composition-first TypeScript HTTP framework for Node.js and Cloudflare Workers. You register config, services, and routes on a FlareHost, then call host.build() to get a compiled app object. That object exposes .run() on Node and .export() on Workers. Swap the runtime adapter; routes, services, contracts, and middleware stay the same.

host.build() resolves config, bootstraps the logger, validates every registration, and compiles route pipelines. If anything is invalid, build throws before any port binds or fetch handler is exported. See Failure modes.

Zero third-party runtime dependencies. @flare-ts/lib ships with none; @flare-ts/core depends only on @flare-ts/lib.

Install

pnpm add @flare-ts/core @flare-ts/lib

See Install for Node.js version requirements, project layout, and flare.json.

Hello, Flare

import { FlareHost, FlareResponse } from "@flare-ts/core";
import { node } from "@flare-ts/core/node";

const host = new FlareHost(node);

host.http.get("/ping", () => new FlareResponse(200, { ok: true }));

const app = host.build();
app.run();

new FlareHost(node) creates a host using the Node adapter. The adapter reads flare.json from the project root when the file exists; if it’s missing, defaults apply plus FLARE__* env overrides.

host.build() validates registrations and compiles route pipelines, returning a compiled app. app.run() binds the HTTP server on the port from flare.json host.port (default 3000) and begins accepting requests.

Continue with Your First App for curl and project layout.

Cloudflare Workers

The cf adapter supplies an empty bundled config and reads overrides from process.env at runtime. Set FLARE__-prefixed values in wrangler.toml [vars] (or via wrangler secret put for secrets) instead of shipping a flare.json file:

import { FlareHost, FlareResponse } from "@flare-ts/core";
import { cf } from "@flare-ts/core/cloudflare";

const host = new FlareHost(cf);

host.http.get("/ping", () => new FlareResponse(200, { ok: true }));

const app = host.build();
export default app.export();

[vars]
FLARE__log__level = "warn"

app.export() returns the ExportedHandler that Cloudflare invokes on each request.

Enable nodejs_compat in wrangler.toml compatibility_flags. Without it, Workers deployments fail at startup when the logger needs Node.js compatibility APIs. Per-request log context on Node requires log.enableContext: true in flare.json; on Workers, see Logger for what context is available today.

If you need bundled flare.json settings in the Worker artifact, use buildCf:

import flareJson from "./flare.json" with { type: "json" };
import { FlareHost } from "@flare-ts/core";
import { buildCf } from "@flare-ts/core/cloudflare";

const host = new FlareHost(buildCf(flareJson));

const app = host.build();
export default app.export();

buildCf(json) merges the imported JSON into the adapter config so the values are available at build time, before FLARE__* env overrides apply.

Where to go next

Goal	Page
Package imports and subpaths	Core (package exports table)
Install, `flare.json`, Workers setup	Install
First runnable app	Your First App
Copy-paste patterns	Examples
Arcs, composition, DI mental model	Concepts
`FlareHost`, HTTP, config, logger, testing	Core
When errors surface (build vs request)	Failure modes
Schema primitives and `model()`	Lib