Arkos.js - The Express And Prisma RESTful Framework

Arkos ships a set of global middlewares that run on every request before any route handler. They are enabled by default with sensible defaults and can be customized, replaced, or disabled through arkos.config.ts.

Configuration Pattern

Every built-in middleware follows the same three-way pattern under middlewares.*:

Value	Behavior
omitted	Runs with Arkos defaults
options object	Deep-merged into the defaults
`ArkosRequestHandler` function	Your middleware runs instead — Arkos's is removed
`false`	Middleware is disabled entirely

Replacing or disabling middlewares like cors, express-json, or global-error-handler can break your application. Do it only if you know what you're replacing them with.

Middlewares

Compression

Compresses response bodies using the compression npm package.

Default: enabled with no options.

arkos.config.ts

import { defineConfig } from "arkos/config";

export default defineConfig({
  middlewares: {
    compression: { level: 6, threshold: 1024 }, // options
    // compression: myMiddleware,                // replace
    // compression: false,                       // disable
  },
});

arkos.config.ts

import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  middlewares: {
    compression: { level: 6, threshold: 1024 },
    // compression: myMiddleware,
    // compression: false,
  },
};

export default arkosConfig;

See compression npm package for all available options.

Rate Limit

Limits the number of requests per IP across all endpoints using express-rate-limit.

Default:

{
  windowMs: 60 * 1000,
  limit: 300,
  standardHeaders: "draft-7",
  legacyHeaders: false,
}

arkos.config.ts

import { defineConfig } from "arkos/config";

export default defineConfig({
  middlewares: {
    rateLimit: { windowMs: 60 * 1000, limit: 100 }, // options — deep-merged
    // rateLimit: myMiddleware,                       // replace
    // rateLimit: false,                              // disable
  },
});

arkos.config.ts

import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  middlewares: {
    rateLimit: { windowMs: 60 * 1000, limit: 100 },
  },
};

export default arkosConfig;

Authentication endpoints have their own separate rate limit configured under authentication.requestRateLimitOptions. See Authentication — Setup for details.

See express-rate-limit npm package for all available options.

CORS

Controls cross-origin resource sharing using the cors npm package.

Default: all origins blocked unless allowedOrigins is set.

arkos.config.ts

import { defineConfig } from "arkos/config";

export default defineConfig({
  middlewares: {
    cors: {
      allowedOrigins: ["https://myapp.com", "https://admin.myapp.com"],
      // allowedOrigins: "*",           // allow all
      options: { credentials: true },
      // customHandler: myCorsDelegate, // replace cors logic only
    },
    // cors: myMiddleware, // replace the entire middleware
    // cors: false,        // disable
  },
});

arkos.config.ts

import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  middlewares: {
    cors: {
      allowedOrigins: ["https://myapp.com", "https://admin.myapp.com"],
      options: { credentials: true },
    },
  },
};

export default arkosConfig;

See cors npm package for all available options.

JSON Body Parser

Parses incoming application/json request bodies using express.json().

Default: enabled with no options.

arkos.config.ts

import { defineConfig } from "arkos/config";

export default defineConfig({
  middlewares: {
    expressJson: { limit: "10mb" }, // options
    // expressJson: myMiddleware,   // replace
    // expressJson: false,          // disable
  },
});

arkos.config.ts

import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  middlewares: {
    expressJson: { limit: "10mb" },
  },
};

export default arkosConfig;

Parses Cookie headers using the cookie-parser npm package.

Default: enabled with no parameters.

arkos.config.ts

import { defineConfig } from "arkos/config";

export default defineConfig({
  middlewares: {
    cookieParser: ["mySecretSigningKey"], // parameters array
    // cookieParser: myMiddleware,        // replace
    // cookieParser: false,               // disable
  },
});

arkos.config.ts

import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  middlewares: {
    cookieParser: ["mySecretSigningKey"],
  },
};

export default arkosConfig;

See cookie-parser npm package for all available options.

Query Parser

Automatically coerces query string values from strings into their correct types — null, undefined, boolean, and number.

Default:

{
  parseNull: true,
  parseUndefined: true,
  parseBoolean: true,
  parseNumber: true,
}

arkos.config.ts

import { defineConfig } from "arkos/config";

export default defineConfig({
  middlewares: {
    queryParser: { parseNull: true, parseBoolean: true, parseNumber: false }, // options
    // queryParser: myMiddleware, // replace
    // queryParser: false,        // disable
  },
});

arkos.config.ts

import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  middlewares: {
    queryParser: { parseNull: true, parseBoolean: true, parseNumber: false },
  },
};

export default arkosConfig;

parseNumber is enabled by default. Any query string field containing only digits will be converted to a number — including fields you may intend to keep as strings. Disable it if that causes issues in your app.

Request Logger

Logs incoming requests. Useful for debugging and monitoring.

Default: enabled.

arkos.config.ts

import { defineConfig } from "arkos/config";

export default defineConfig({
  middlewares: {
    requestLogger: myLoggerMiddleware, // replace
    // requestLogger: false,           // disable
  },
});

arkos.config.ts

import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  middlewares: {
    requestLogger: myLoggerMiddleware,
    // requestLogger: false,
  },
};

export default arkosConfig;

Helmet

Available since v1.6.0-beta

Sets security-related HTTP response headers using the helmet npm package.

Default: enabled with no options.

arkos.config.ts

import { defineConfig } from "arkos/config";

export default defineConfig({
  middlewares: {
    helmet: {}, // options
    // helmet: myMiddleware, // replace
    // helmet: false,        // disable
  },
});

arkos.config.ts

import { ArkosConfig } from "arkos";
import helmet from "helmet";

const arkosConfig: ArkosConfig = {
  configureApp: (app) => {
    app.use(helmet());
  },
};

export default arkosConfig;

Install helmet first: npm install helmet or pnpm add helmet.

See helmet npm package for all available options.

Global Error Handler

Arkos registers its global error handler automatically. You can replace it entirely or disable it.

arkos.config.ts

import { defineConfig } from "arkos/config";

export default defineConfig({
  middlewares: {
    errorHandler: myErrorHandler, // replace
    // errorHandler: false,        // disable
  },
});

arkos.config.ts

import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  middlewares: {
    errorHandler: myErrorHandler,
    // errorHandler: false,
  },
};

export default arkosConfig;

Replacing the global error handler means you take full responsibility for formatting and sending error responses. See Error Handling — Overview for what Arkos's handler does by default.

If you want to run additional logic alongside Arkos's error handler rather than replacing it, use a Custom Handler instead.

Additional Middlewares

To inject custom middlewares into the global stack:

src/app.ts

import arkos from "arkos";

const app = arkos();

app.use(myCustomMiddleware);

app.listen();

arkos.config.ts

import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  configureApp: (app) => {
    app.use(myCustomMiddleware);
  },
};

export default arkosConfig;

Execution Order

The global middleware stack runs in this order on every request:

compression
rateLimit
cors
expressJson
cookieParser
queryParser
requestLogger
additional middlewares
Routers (file upload, auth, prisma models, custom)
Catch-all 404
errorHandler

Global Middlewares

Configuration Pattern

Middlewares

Compression

Rate Limit

CORS

JSON Body Parser

Query Parser

Request Logger

Helmet

Global Error Handler

Additional Middlewares

Execution Order

On this page