Skip to main content

Quik Framework :: HTTP Express Implementation

Express-based implementation of the HTTP engine. It registers the Express engine and adds documentation routes when OpenAPI support is enabled.

Installation​

npm install @quik/http-express

Usage​

Register the Express engine through bootstrap:

import { Module as HttpExpress } from '@quik/http-express';

await HttpExpress.setup({ /* bootstrap options */ });

Integration checklist:

  • Ensure @quik/http is installed and loaded before @quik/http-express.
  • Provide an http configuration block (listen/port, CORS, cookie, and session settings).
  • Call start() on the HTTP module during bootstrap to register routes and middleware.

Attach Express middleware to routes/endpoints:

import { ExpressMiddlewareUtils } from '@quik/http-express';
import { Decorators, QRoute } from '@quik/http';

@ExpressMiddlewareUtils.RouteMiddleware((req, _res, next) => next())
@Decorators.Route.Route('/health')
export class HealthRoute extends QRoute {
  @ExpressMiddlewareUtils.EndpointMiddleware((req, _res, next) => next())
  @Decorators.Endpoint.GET('/')
  async get() {
    return { status: 'ok' };
  }
}

API Highlights​

  • QExpressEngine HTTP engine implementation.
  • QExpressContext Express request/response context implementation.
  • ExpressMiddlewareUtils.RouteMiddleware() and .EndpointMiddleware() helpers.
  • Automatically registers OpenAPI docs route when @quik/openapi is loaded.
  • ScalarHooks.addConfiguration() lets other modules extend the Scalar API Reference configuration.
  • QExpressEngine.setSessionStore(store) — plug in a production-ready session store before the engine starts.

Cookies​

QExpressContext implements the cookie helpers exposed by QEvent and QContext:

  • getCookie(name) reads from request.cookies.
  • setCookie(name, value, options) writes through response.cookie().
  • clearCookie(name, options) clears through response.clearCookie().

When writing or clearing cookies, the Express context applies these defaults:

  • httpOnly: true
  • secure: http.cookie.secure
  • domain: http.cookie.domain

Options passed by endpoint code override those defaults.

import { Decorators, QRoute, type IQEvent } from '@quik/http';

@Decorators.Route.Route('/preferences')
export class PreferencesRoute extends QRoute {
  @Decorators.Endpoint.POST('/theme')
  async saveTheme(event: IQEvent) {
    event.setCookie('theme', 'dark', {
      maxAge: 30 * 24 * 60 * 60 * 1000,
      sameSite: 'lax'
    });

    return { saved: true };
  }

  @Decorators.Endpoint.DELETE('/theme')
  async clearTheme(event: IQEvent) {
    event.clearCookie('theme');

    return { cleared: true };
  }
}

Custom session store​

Call setSessionStore before the HTTP module boots (e.g. in your bootstrap setup):

import RedisStore from 'connect-redis';
import { createClient } from 'redis';
import { QExpressEngine } from '@quik/http-express';

const client = createClient();
await client.connect();
QExpressEngine.setSessionStore(new RedisStore({ client }));

Default Routes​

  • OpenAPI docs are exposed at DOCS_BASE_PATH (default /api/docs) when @quik/openapi is enabled.
  • Swagger UI uses a Swagger-compatible OpenAPI projection so unsupported custom schemes, such as passkey webauthn, do not break the authorize modal.
  • Static content is served when http.static.serve is enabled, using http.static.path as the mount path.
  • SPA frontend fallback is available through http.static.singlePageApplication.enable. HTML navigation requests without a file extension are rewritten to http.static.singlePageApplication.indexFile. Requests under http.paths.api and http.paths.docs are excluded from the fallback.

Example SPA setup:

{
  http: {
    static: {
      serve: true,
      global: true,
      folder: './public',
      path: '',
      singlePageApplication: {
        enable: true,
        indexFile: 'index.html'
      }
    }
  }
}

Testing & Coverage​

See the root instructions for details on running pnpm run test:coverage and accessing coverage artifacts.

API Reference​

Generated API documentation is available in the http-express API section.