Core Systems
HTTP Engine
MoroJS serves HTTP from its own native engine by default, with the Node.js server as an automatic fallback. One setting selects the backend; nothing needs installing or configuring.
Overview
The native engine, @morojs/engine, is a dependency of the framework with prebuilt binaries per platform and Node version. Where it cannot load (a platform or Node ABI without a prebuilt binary), the Node.js http server takes over automatically and the app still boots.
1import { createApp } from '@morojs/moro';
2
3const app = await createApp({
4 server: {
5 engine: 'moro', // the default; may be left out
6 // engine: 'node' - the Node.js http server, no native engine
7 },
8});
9
10// What actually booted (also logged at startup)
11app.engine;
12// { server: 'engine', enginePackage: '@morojs/engine',
13// engineVersion: '1.1.20', protocols: ['http/1.1'] }Engine selection
- engine: 'moro' (default): the native engine, with the Node.js server as its fallback
- engine: 'node': the Node.js http server, no native engine
- The MORO_SERVER_ENGINE environment variable overrides the config value
- app.engine.fallbackReason says why the Node.js server is serving when the engine was expected
- The old 'auto' and 'native' values map to 'moro'
What the Engine Serves
| Feature | On the engine | Notes |
|---|---|---|
| HTTP/1.1 | yes | Keep-alive, pipelining, chunked bodies; limits and timeouts from server.limits and server.timeouts |
| HTTP/2 | yes (@morojs/engine 1.1.19+) | http2: true; ALPN h2 on TLS, prior knowledge on cleartext, HTTP/1.1 on the same port |
| TLS | yes | server.ssl, one config for every backend; certificate reload through app.reloadTLS() and ssl.watch |
| WebSockets | yes | app.websocket(); upgrades share the HTTP port |
| Clustering | yes | performance.clustering; worker threads in one process on macOS and Linux |
An older engine that lacks a feature is detected by capability, not by version: for example, HTTP/2 with an engine before 1.1.19 is served by the Node.js HTTP/2 server instead.
TLS
1const app = await createApp({
2 server: {
3 ssl: {
4 keyFile: './key.pem',
5 certFile: './cert.pem', // or inline: { key, cert, ca }
6 // library: 'auto', // 'boringssl' | 'openssl' | 'auto' (the default)
7 },
8 },
9});
10
11// The library actually in use, and why
12app.engine.tls;
13// { library: 'boringssl', version: '0.20261105.0', date: '2026-11-05', reason: 'default' }From @morojs/engine 1.1.20 the engine terminates TLS with a BoringSSL it carries inside its binary, and ships a second binary on the OpenSSL of the running Node.js. server.ssl.library chooses between them.
server.ssl.library
- 'auto' (default): BoringSSL, unless Node's OpenSSL is specially configured (FIPS mode, --openssl-config and its relatives, OPENSSL_CONF), in which case OpenSSL, so a FIPS or provider setup keeps working with nothing to change
- 'boringssl': the BoringSSL bundled with the engine and updated with it
- 'openssl': the OpenSSL of the running Node.js
- With no library named, a certificate or cipher configuration BoringSSL has no support for (an Ed448, DSA or brainpool key) is served by the engine on OpenSSL; app.engine.tls then reports reason: fallback with the cause
- The choice is per process: the first app started decides. The MORO_ENGINE_TLS environment variable sets it without a code change
- Older engines and the Node.js server have one TLS library and ignore the setting
The bundled BoringSSL is updated through engine releases. Keep @morojs/engine updated as you keep Node.js updated; a TLS server on a build more than 180 days old logs a MORO_ENGINE_TLS_STALE process warning. An app behind a proxy that terminates TLS (nginx, a load balancer) is not affected by any of this.
When to Choose engine: 'node'
- You attach something to the raw Node.js http.Server that the engine has no equivalent for
- You use the socket.io or ws WebSocket adapter. Both attach to a Node.js server, so MoroJS selects it for you when one of them is configured
- You need HTTP/2 server push or stream prioritization, which the Node.js HTTP/2 server provides
- You are on an edge or serverless runtime, where no listening server is used at all (selected automatically)
Routes, middleware, validation, and request and response objects behave the same on both backends; a conformance suite in the framework repository holds them to identical responses.
Coming from uWebSockets.js
MoroJS 1.8.24 removed its uWebSockets.js integration. The native engine replaced it: it is faster in our measurements, installs from npm with prebuilt binaries, and supports HTTP/2, worker-thread clustering and certificate reload, which the uWebSockets.js integration did not.
Existing configurations keep working. None of these stops an app from booting; each runs the app on the Moro engine and logs one warning:
| Old setting | What happens now |
|---|---|
server.engine: 'uws' | Runs on the Moro engine (as engine: 'moro') |
server.useUWebSockets: true | Runs on the Moro engine |
MORO_SERVER_ENGINE=uws | Runs on the Moro engine |
websocket.adapter: 'uws' | The engine's own WebSocket support, as when no adapter is set |
To finish the migration
- 1Remove those settings.
- 2Remove uWebSockets.js from your package.json; MoroJS no longer loads it.
- 3If you imported UWebSocketsHttpServer or UWebSocketsAdapter from @morojs/moro, remove those imports. Those two exports are gone; app.websocket() and the default engine need neither.
With http2 enabled, an app that was configured for uWebSockets.js is now served HTTP/2 by the engine, where the uWebSockets.js integration served HTTP/1.1 only.
Troubleshooting
- The app runs on the Node.js server and you expected the engine: read app.engine.fallbackReason; the same text is logged at startup. The usual causes are a platform without a prebuilt binary, or npm's optional-dependency lockfile bug (rm -rf node_modules package-lock.json && npm install)
- EADDRINUSE with clustering on Windows: clustering on Windows uses the Node.js server and worker processes, because the engine’s workers share a port through SO_REUSEPORT, which Windows lacks. MoroJS makes this choice itself