Express backend

ExpressBackend lets you run actor-ts routes through Express — the most-widely-used Node HTTP framework. Right choice when:

• You already have Express middleware invested (custom auth, session handling, app-specific instrumentation).
• Team familiarity with Express > framework benefits of Fastify.
• You’re incrementally migrating an existing Express app to actor-ts.

import { ActorSystem, HttpExtensionId } from 'actor-ts';
import { ExpressBackend, ExpressBackendOptions } from 'actor-ts/http';

const http = system.extension(HttpExtensionId);

await http.newServerAt('0.0.0.0', 8080)
  .useBackend(new ExpressBackend())
  .bind(routes);

Configuration

const expressBackendOptions = ExpressBackendOptions.create().withMaxBodyBytes(1 * 1024 * 1024);
new ExpressBackend(
  expressBackendOptions,
);
// X-Forwarded-* handling is configured on a bring-your-own Express app
// (`app.set('trust proxy', true)`), passed via `.withApp(app)`.

Express-style settings.

Security headers

Every response this backend writes carries X-Content-Type-Options: nosniff — its error mapping, the fallback 404 and the body-too-large 413 included, none of which a middleware sees. A response’s own header still wins.

Configure it per server, not per backend — one surface instead of three:

await http.newServerAt('0.0.0.0', 8080)
  .useBackend(new ExpressBackend())
  .withSecurityHeaders(false)      // or a SecurityHeadersOptions bundle
  .bind(routes);

See Security best practices.

Adding Express middleware

import express from 'express';
import { ExpressBackend } from 'actor-ts/http';

const backend = new ExpressBackend();
await http.newServerAt('0.0.0.0', 8080)
  .useBackend(backend)
  .bind(routes);

// Access the raw Express app:
backend.getApp().use(express.session({ secret: '...' }));
backend.getApp().use(expressRateLimitFromNpm);
backend.getApp().use(customAuth);

Express middleware wraps the actor-ts routes — request flows through your middleware first, then to the actor-ts handler.

This is the main reason to pick Express over Fastify: the middleware ecosystem. If you don’t need it, Fastify is faster.

TLS

import express from 'express';
import https from 'node:https';

// TLS is set up on a bring-your-own Express app, wrapped in Node's
// `https` server; pass the app to the backend via `.withApp(app)`.
const app = express();
https.createServer(
  {
    cert: fs.readFileSync('./tls/cert.pem'),
    key:  fs.readFileSync('./tls/key.pem'),
  },
  app,
);

const expressBackendOptions = ExpressBackendOptions.create().withApp(app);
new ExpressBackend(expressBackendOptions);

Backed by Node’s https module. Same caveats as the Fastify backend — typically TLS terminates at the load balancer.

Peer dependency

npm install express
# or: bun add express

For Express 5+ recommendation; older versions may work but aren’t tested.

Performance

Rough numbers:

• 40K-60K req/sec for trivial routes (slower than Fastify).
• P50 latency similar; throughput differs.

Express’s middleware chain has more overhead than Fastify’s hooks. For high-throughput paths, prefer Fastify; for paths gated by heavy middleware, the framework choice doesn’t matter much.

Migrating from existing Express app

If you have an existing Express app and want to add actor-ts:

import express from 'express';
import { ExpressBackend, ExpressBackendOptions } from 'actor-ts/http';

const app = express();

// Existing routes + middleware stay as-is:
app.use('/legacy', oldLegacyRouter);

// Hand the existing app to the backend; actor-ts registers its
// routes on the same app, alongside your existing ones.
const expressBackendOptions = ExpressBackendOptions.create().withApp(app);
const backend = new ExpressBackend(expressBackendOptions);

await http.newServerAt('0.0.0.0', 8080)
  .useBackend(backend)
  .bind(routes);

Pass your existing app to the backend via .withApp(app) — actor-ts registers its routes on the same app, so your existing routes and middleware keep working without swapping the whole HTTP stack.

Express vs Fastify benchmarks

// Choose Express because "it's simpler"

Both are simple from an actor-ts perspective. Fastify is faster. Express has more middleware. Pick by what middleware you need, not by perceived simplicity.

Async error handling

app.use((req, res, next) => {
  asyncWork().then(...);   // ✗ unhandled rejection
});

Express’s default error handling is synchronous-friendly. For async middleware, use express-async-errors or wrap manually. The actor-ts routes themselves handle async cleanly; this is about your custom middleware.

Where to next

• HTTP overview — the bigger picture.
• Fastify backend — the default + recommended.
• Route DSL — what backends register.