Skip to content

Application ​

Every Megh app is one MeghApplication. You create it, turn features on with use* methods, and start it with run().

ts
import { Megh } from '@meghjs/core';
import { UserController } from './controllers/user.controller';

const app = Megh.createApplication();

app
  .useCors({ origin: true })
  .useHealth()
  .useControllers([UserController]);

app.run(3000);

Creating the app ​

Megh.createApplication(options?) returns the application. It's a singleton: calling it again returns the same app, and the options of the later calls are ignored. Pass every option in the first call.

OptionDefault
serverFastify server options (logger, bodyLimit, trustProxy, https, …), passed to Fastify()
requestId{} (on)Request ID settings. false turns request IDs off. See Logging
plugins[]Plugins to register explicitly
autoloadPluginstrueFind plugins among the app's dependencies
experimental.compiledValidationMEGH_COMPILED_VALIDATION env, else falseCompile DTO validation once per class. See Validation
ts
const app = Megh.createApplication({
  server: {
    bodyLimit: 2 * 1024 * 1024, // 2 MB
    trustProxy: true,           // behind a load balancer
  },
});

The Fastify instance ​

app.app is the underlying Fastify instance. Use it for anything Megh doesn't wrap, such as registering a Fastify plugin:

ts
import etag from '@fastify/etag';

app.app.register(etag);

Turning features on ​

Each use* method returns the app, so they chain. Call them before run().

MethodWhat it doesGuide
useControllers([...]) or useControllers({ auto: true, path? })Register controllers, or scan a folder (default: every controllers/ folder under src/). Calling it again adds to the listControllers
useMiddlewares([...])Global middleware for every routeMiddleware
useAuthentication(Handler)Sets request.user on every requestAuthentication
useAuthorization(Handler)Decides access for @Authorized routesAuthentication
useExceptionFilters(...), useErrorHandler(fn), useErrorLogger(...)Customise error responses and loggingError Handling
useOpenApi(options)OpenAPI document and Swagger UI or ScalarOpenAPI
useCors(options)CORS, through @fastify/corsSecurity
useSecurityHeaders(options?)CSP, HSTS, nosniff and other security headersSecurity
useRateLimit(options?)Requests per client per window, 429 over the limitSecurity
useMultipart(options)File uploads, through @fastify/multipartFile Uploads
useStaticFiles(options)Serve files, through @fastify/staticFile Uploads
useCompression(options?)gzip / brotli responses, through @fastify/compressCompression
setGlobalPrefix(prefix, { exclude? })Serve every route under a prefix such as /apiControllers
useVersioning(options)Version routes with @Version(), by URI or headerControllers
useEnvSchema(EnvDto)Validate environment variables at bootConfiguration
useCache(options)Memory or Redis cacheCaching
useMeghORM(options)Database connection for MeghORMMeghORM
useScheduler([...]) or useScheduler({ path })Scheduled tasksScheduler
useWorker([...])Queue workersQueue
useMail(options?)Send mail over SMTP or a provider's API, now or queuedMail
useSocketIo(options)Socket.IO serverWebSocket
useHealth(options), addHealthCheck(name, fn)/health and /ready endpointsHealth Checks

Integrations are optional peer dependencies. If one isn't installed, the use* call throws with the npm install command you need.

useGlobal ​

useGlobal sets several features in one call. Each key calls the matching use* method:

ts
import path from 'path';

app.useGlobal({
  cors: { origin: ['https://example.com'] },
  openApi: { info: { title: 'My API', version: '1.0.0' } },
  controllers: [UserController],
  middlewares: [RequestTimer],
  authorization: AppAuthorization,
  multipart: { limits: { fileSize: 5 * 1024 * 1024 } },
  staticFiles: { root: path.join(process.cwd(), 'public') }, // must be absolute
});
KeyCalls
corsuseCors
openApiuseOpenApi
controllersuseControllers
middlewaresuseMiddlewares
authorizationuseAuthorization
multipartuseMultipart
staticFilesuseStaticFiles
scheduleruseScheduler
compressionuseCompression (true or options)

Compression ​

useCompression() compresses responses for clients that send Accept-Encoding, with @fastify/compress (npm install @fastify/compress). Bodies under 1024 bytes are sent as they are. Options go to the plugin:

ts
app.useCompression();
app.useCompression({ encodings: ['br', 'gzip'], threshold: 2048 });

If a proxy or CDN in front of the app already compresses, leave it off.

Running the app ​

run(port?, options?) starts the app. The port defaults to the PORT environment variable, else 4000:

ts
app.run();      // PORT, else :4000
app.run(3000);  // :3000, whatever PORT says
app.run(3000, { host: '127.0.0.1', shutdownTimeout: 20_000 });
OptionDefault
hostHOST or 0.0.0.0Interface to listen on
onListenCalled once the server is listening
shutdownTimeout10000Milliseconds to wait for a clean shutdown before exiting with code 1

The host defaults to 0.0.0.0 so the app is reachable inside a container. Pass 127.0.0.1 to accept local connections only. run() can be called once; a second call throws App already running.

What run() does ​

In order:

  1. Validates the environment (useEnvSchema) and every @AppConfig({ schema }) class.
  2. Prepares the OpenAPI document, if useOpenApi was called.
  3. Runs the onInit hooks. MeghORM connects to the database here.
  4. Finds controllers (with { auto: true }), then maps controller and inline routes.
  5. Finds and starts scheduled tasks.
  6. Installs the error handler and waits for Fastify to be ready.
  7. Starts Socket.IO, if useSocketIo was called.
  8. Listens for SIGTERM and SIGINT.
  9. Starts listening on the port and logs Application running on <address>.
  10. Runs the onReady hooks, then onListen.

A thrown error in steps 1 to 6 stops startup, and the server never listens.

Lifecycle hooks ​

Register work to run at each stage of the app's life. Call these before run(); each returns the app, so they chain:

ts
app
  .onInit(async () => {
    // After the database connects, before routes are mapped and the server
    // listens. A thrown error aborts startup.
    await cache.warmUp();
  })
  .onReady(() => {
    // The server is listening.
  })
  .onClose(async () => {
    // On shutdown, after the server stops accepting requests.
    await metrics.flush();
  });

Hooks of the same kind run in the order you register them, except onClose hooks, which run in reverse so that things set up last are torn down first. A failing onClose hook is logged and the others still run.

Shutting down ​

await app.close() shuts the app down, for example at the end of a test. In order, it:

  1. Stops the HTTP server, waiting for in-flight requests.
  2. Stops scheduled tasks.
  3. Closes queue workers.
  4. Closes the cache, if useCache was called.
  5. Runs the onClose hooks (MeghORM closes its connection in one).

Calling close() twice is safe: the second call waits for the first.

On SIGTERM or SIGINT, run() calls close() and exits with code 0. If shutdown fails, or takes longer than shutdownTimeout, it exits with code 1. See Deployment for running behind a process manager or in a container.

Development and production ​

app.isDevelopment() is true only when NODE_ENV=development. An unset NODE_ENV counts as production. In production mode, 5xx details are hidden and logs are written as JSON. Set NODE_ENV=development locally to get detailed errors, pretty logs and any docs you gate behind isDevelopment():

ts
if (app.isDevelopment()) {
  app.useOpenApi({ info: { title: 'My API', version: '1.0.0' } });
}

Megh loads .env into process.env when it is first imported. Set MEGH_DOTENV=false to skip that and manage the environment yourself. See Configuration.

Released under the MIT License.