`exisjs` (Root API)

The root exisjs module exports the core application builder defineApp (aliased as exis), the App class definition, active application resolvers, response helpers, and circuit breaker utilities.

Module Exports

import {  exis,  defineApp,  App,  getActiveApp,  defineConfig,  parseEnv,  loadEnv,} from 'exisjs'
import type {  ExisConfig,  ExisPlugin,  ExisPluginInstance,  Logger,  CorsConfig,  LoggerConfig,  HookRequest,  HookResponse,  HookError,  HookReady,  HookClose,} from 'exisjs'

1. Application Entrypoint: `exis()` / `defineApp()`

Defines an ExisJS application definition for CLI execution or programmatic booting.

function defineApp(options?: ExisAppOptions): ExisAppDefinitionexport { defineApp as exis }

`ExisAppOptions` Interface

Extends ExisConfig with application lifecycle hooks:

Option	Type	Default	Description
`port`	`number`	`3000`	Port number to bind the server listener to.
`host`	`string`	`'0.0.0.0'`	Network address to bind the listener to.
`env`	`'development' \| 'production' \| 'test'`	`NODE_ENV`	Application execution environment.
`logger`	`boolean \| LoggerConfig`	`true`	Configures or disables the built-in Pino structured logger.
`helmet`	`boolean \| HelmetOptions`	`true`	Automatically injects security response headers.
`cors`	`boolean \| CorsConfig`	`false`	Manages Cross-Origin Resource Sharing headers and preflights.
`compression`	`boolean \| CompressionOptions`	`false`	Response payload compression via Gzip, Deflate, or Brotli.
`plugins`	`(ExisPlugin \| ExisPluginInstance)[]`	`[]`	Array of modules or plugins to initialize on boot.
`middlewares`	`Handler[]`	`[]`	Global middleware executed on all incoming requests.
`onStart`	`(app: App) => void \| Promise<void>`	`undefined`	Hook executed during startup before the listener begins accepting requests.
`onClose`	`(app: App) => void \| Promise<void>`	`undefined`	Hook executed during graceful shutdown.

2. Dual-Paradigm Setup

Functional Paradigm

src/http/server.ts

import { exis } from 'exisjs'
export default exis({  port: 3000,  logger: true,  helmet: true,  cors: { origin: '*' },  async onStart(app) {    app.log.info('Application initialized successfully')  },  async onClose(app) {    app.log.info('Graceful shutdown complete')  },})

Class-Based (OOP) Paradigm

src/http/server.ts

import { Server } from 'exisjs/decorators'import type { App } from 'exisjs'
@Server({  plugins: [],})export default class RootServer {  async onStart(app: App) {    app.log.info('Application initialized successfully')  }
  async onClose(app: App) {    app.log.info('Graceful shutdown complete')  }}

3. `App` Class Methods Reference

The App instance coordinates dependency injection, routing, middleware pipelines, lifecycle hooks, and background cron execution.

Routing & Pipeline

Method	Signature	Description
`use`	`(...handlers: (Handler \| ErrorHandler)[]): this`	Registers global request middlewares or 4-argument error handlers.
`get`	`(path: string, ...handlers: Handler[]): this`	Registers a `GET` route handler.
`post`	`(path: string, ...handlers: Handler[]): this`	Registers a `POST` route handler.
`put`	`(path: string, ...handlers: Handler[]): this`	Registers a `PUT` route handler.
`patch`	`(path: string, ...handlers: Handler[]): this`	Registers a `PATCH` route handler.
`delete`	`(path: string, ...handlers: Handler[]): this`	Registers a `DELETE` route handler.
`mount`	`(prefix: string, subRouter: Router): this`	Mounts a sub-router under a URL path prefix.
`getRoutes`	`(): Route[]`	Returns an array of all compiled route definitions.

Dependency Injection & Plugins

Method	Signature	Description
`provide`	`<T>(token: ProviderToken<T>, provider: ProviderDefinition<T>): this`	Registers a dependency provider into the application container.
`resolve`	`<T>(token: ProviderToken<T>, requestCache?: Map<any, any>): T`	Resolves a singleton or request-scoped dependency from the container.
`register`	`(plugin: ExisPlugin \| ExisPluginInstance, options?: any): Promise<this>`	Registers an encapsulated plugin or module.
`hasPlugin`	`(name: string): boolean`	Checks whether a plugin has been registered.

Lifecycle Hooks

// Registers a hook called once the server is ready and listeningapp.onReady((app: App) => void | Promise<void>)
// Registers a hook called when the server initiates graceful shutdownapp.onClose((app: App) => void | Promise<void>)
// Registers a hook called on each incoming HTTP requestapp.onRequest((req: Request, res: Response) => void | Promise<void>)
// Registers a hook called after an HTTP response finishes dispatchingapp.onResponse((req: Request, res: Response) => void | Promise<void>)
// Registers a hook called whenever an unhandled error occursapp.onError((err: Error, req: Request, res: Response) => void | Promise<void>)

Server Execution & Testing

Method	Signature	Description
`create`	`(cwd?: string): Promise<this>`	Automatically loads configuration, mounts file-system routes, connects databases, and initializes lifecycles.
`listen`	`(portOrOptions?: number \| ListenOptions, callback?: () => void): Server`	Binds the underlying Node.js HTTP/HTTPS server and begins listening for connections.
`close`	`(timeout?: number): Promise<void>`	Initiates graceful server shutdown, drains cron jobs, and destroys DI singletons.
`inject`	`(options: InjectOptions): Promise<TestResponse>`	Dispatches an in-memory synthetic request without binding a real network socket (ideal for unit/E2E testing).

4. `getActiveApp()`

Retrieves the currently running singleton App instance within the active Node.js process:

function getActiveApp(): App

src/services/billing.ts

import { getActiveApp } from 'exisjs'
export function processInvoice(invoiceId: string) {  const app = getActiveApp()  app.log.info({ invoiceId }, 'Processing invoice')}

Continue to Config Reference Edit this page on GitHub

exisjs (Root API)