Arkos Configuration

Arkos provides a comprehensive configuration system that allows you to customize every aspect of your application. This reference covers all available configuration options for both arkos.init() and arkos.config.ts.

The dedicated configuration file was introduced on v1.4.0-beta it was made for the clearly separate concerns between what is really application configuration and what is initialization configuration. And this also makes possible for different tools such as the Built-in CLI to make usage of the confiugration when generating different components in your project.

Key Changes From `v1.4.0-beta`

Split Configuration: Configuration is now split between arkos.init() (app initialization) and arkos.config.ts (static configuration)
Simplified Middleware Configuration: Individual middleware options replace complex middlewares object
Unified Router Registration: All custom routers use the use array
Enhanced ArkosRouter: New declarative configuration for routes

File Structure Changes

v1.4.0+ (Recommended)
v1.3.0 and earlier

Two-file setup:

// src/app.ts - App initialization
import arkos from "arkos";
import customRouter from "./routers/custom.router";

arkos.init({
  use: [customRouter],
  configureApp: (app) => {
    app.set("trust proxy", 1);
  },
});

// arkos.config.ts - Static configuration
import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  port: 3000,
  authentication: {
    enabled: true,
    mode: "static",
  },
  validation: {
    resolver: "zod",
  },
};

export default arkosConfig;

Single-file setup:

// src/app.ts - Everything in one file
import arkos from "arkos";
import customRouter from "./routers/custom.router";

arkos.init({
  port: 3000,
  authentication: {
    mode: "static",
  },
  validation: {
    resolver: "zod",
  },
  routers: {
    additional: [customRouter],
  },
  configureApp: (app) => {
    app.set("trust proxy", 1);
  },
});

Configuration Structure

ArkosInitConfig (arkos.init())

Used for app initialization and runtime configuration:

interface ArkosInitConfig {
  use?: (
    | IArkosRouter
    | express.Router
    | ArkosRequestHandler
    | ArkosErrorRequestHandler
  )[];
  configureApp?: (app: express.Express) => Promise<any> | any;
  configureServer?: (server: http.Server) => Promise<any> | any;
}

ArkosConfig (arkos.config.ts)

Used for static application configuration:

interface ArkosConfig {
  // Basic settings
  welcomeMessage?: string;
  port?: number;
  host?: string;

  // Feature configurations
  authentication?: AuthenticationConfig;
  validation?: ValidationConfig;
  fileUpload?: FileUploadConfig;
  middlewares?: MiddlewareConfig;
  routers?: RouterConfig;
  email?: EmailConfig;
  swagger?: SwaggerConfig;
  request?: RequestConfig;
  debugging?: DebuggingConfig;
}

Configuration Properties

Basic Application Settings

v1.4.0+ (Recommended)
v1.3.0

// arkos.config.ts
const arkosConfig: ArkosConfig = {
  welcomeMessage: "Welcome to Our API",
  port: 3000,
  host: "0.0.0.0",
};

export default arkosConfig;

// src/app.ts
arkos.init({
  welcomeMessage: "Welcome to Our API",
  port: 3000,
  host: "0.0.0.0",
});

`welcomeMessage`

Type: string
Default: "Welcome to our Rest API generated by Arkos, find more about Arkos at www.arkosjs.com."
Description: Message returned when accessing GET /api

`port`

Type: number
Default: 8000 or process.env.PORT or -p argument
Description: Port where the application will run

`host`

Type: string
Default: localhost
Description: Host to bind the server to

Authentication Configuration

v1.4.0+ (Recommended)
v1.3.0

// arkos.config.ts
const arkosConfig: ArkosConfig = {
  authentication: {
    enabled: true,
    mode: "static",
    login: {
      allowedUsernames: ["email", "username"],
      sendAccessTokenThrough: "both",
    },
    rateLimit: {
      windowMs: 5000,
      limit: 10,
    },
    jwt: {
      secret: process.env.JWT_SECRET,
      expiresIn: "7d",
      cookie: {
        secure: process.env.NODE_ENV === "production",
        httpOnly: true,
        sameSite: "lax",
      },
    },
  },
};

export default arkosConfig;

// src/app.ts
arkos.init({
  authentication: {
    mode: "static",
    login: {
      allowedUsernames: ["email", "username"],
      sendAccessTokenThrough: "both",
    },
    // ... other auth config
  },
});

`authentication.enabled`

Type: boolean
Default: true
Description: Completely disable authentication system and remove auth routes when false

`authentication.mode`

Type: "static" | "dynamic"
Required: Yes
Description: Defines whether to use Static or Dynamic Role-Based Access Control

`authentication.login.allowedUsernames`

Type: string[]
Default: ["username"]
Description: Fields that can be used as username for authentication

`authentication.login.sendAccessTokenThrough`

Type: "cookie-only" | "response-only" | "both"
Default: "both"
Description: How to return access tokens after login

`authentication.rateLimit`

Type: Partial<RateLimitOptions>
Default: { windowMs: 5000, limit: 10 }
Description: Rate limiting for authentication endpoints

`authentication.jwt`

Type: Object containing JWT configuration
Description: JWT token settings

Validation Configuration

v1.4.0+ (Recommended)
v1.3.0

// arkos.config.ts
const arkosConfig: ArkosConfig = {
  validation: {
    resolver: "zod",
    strict: false,
    validationOptions: {
      // Zod or class-validator options
    },
  },
};

export default arkosConfig;

// src/app.ts
arkos.init({
  validation: {
    resolver: "zod",
    validationOptions: {
      // Zod or class-validator options
    },
  },
});

`validation.resolver`

Type: "class-validator" | "zod"
Required: Yes
Description: Validation library to use

`validation.strict`

Type: boolean
Default: false
Description: Require validation configuration for all ArkosRouter endpoints

`validation.validationOptions`

Type: ValidatorOptions or Record<string, any>
Description: Options passed to the validation library

File Upload Configuration

v1.4.0+ (Recommended)
v1.3.0

// arkos.config.ts
const arkosConfig: ArkosConfig = {
  fileUpload: {
    baseUploadDir: "/uploads",
    baseRoute: "/api/uploads",
    expressStatic: {
      maxAge: "1y",
      etag: true,
    },
    restrictions: {
      images: {
        maxCount: 10,
        maxSize: 5 * 1024 * 1024, // 5MB
        supportedFilesRegex: /\.(jpg|jpeg|png|gif|webp)$/,
      },
    },
  },
};

export default arkosConfig;

// src/app.ts
arkos.init({
  fileUpload: {
    baseUploadDir: "/uploads",
    baseRoute: "/api/uploads",
    expressStaticOptions: {
      maxAge: "1y",
      etag: true,
    },
    // ... restrictions
  },
});

`fileUpload.baseUploadDir`

Type: string
Default: "/uploads"
Description: Base directory for file uploads

`fileUpload.baseRoute`

Type: string
Default: "/api/uploads"
Description: Base route for file access

`fileUpload.expressStatic`

Type: Parameters<typeof express.static>[1]
Description: Options for express.static middleware

`fileUpload.restrictions`

Type: Object containing file type restrictions
Description: Upload restrictions for different file types

Middleware Configuration

v1.4.0+ (Recommended)
v1.3.0

// arkos.config.ts
const arkosConfig: ArkosConfig = {
  middlewares: {
    compression: {
      level: 6,
    },
    rateLimit: {
      windowMs: 60000,
      limit: 1000,
    },
    cors: {
      allowedOrigins: ["https://example.com"],
      options: {
        credentials: true,
      },
    },
    expressJson: {
      limit: "10mb",
    },
    cookieParser: ["secret"],
    queryParser: {
      parseNull: true,
      parseBoolean: true,
      parseDoubleUnderscore: true,
    },
    requestLogger: myCustomLogger,
    errorHandler: myCustomErrorHandler,
  },
};

export default arkosConfig;

Disabling Middlewares:

const arkosConfig: ArkosConfig = {
  middlewares: {
    compression: false, // Disable compression
    rateLimit: false, // Disable rate limiting
    requestLogger: false, // Disable request logger
  },
};

export default arkosConfig;

Replacing Middlewares:

const arkosConfig: ArkosConfig = {
  middlewares: {
    cors: myCustomCorsHandler, // Replace with custom handler
    errorHandler: myErrorHandler, // Replace with custom handler
  },
};

export default arkosConfig;

// src/app.ts
arkos.init({
  globalRequestRateLimitOptions: {
    windowMs: 60000,
    limit: 1000,
  },
  jsonBodyParserOptions: {
    limit: "10mb",
  },
  cookieParserParameters: ["secret"],
  compressionOptions: {
    level: 6,
  },
  queryParserOptions: {
    parseNull: true,
    parseBoolean: true,
  },
  cors: {
    allowedOrigins: ["https://example.com"],
    options: {
      credentials: true,
    },
  },
  middlewares: {
    additional: [myCustomMiddleware],
    disable: ["compression", "request-logger"],
    replace: {
      cors: myCustomCorsHandler,
      globalErrorHandler: myCustomErrorHandler,
    },
  },
});

Middleware Options

compression: false | CompressionOptions | ArkosRequestHandler
rateLimit: false | Partial<RateLimitOptions> | ArkosRequestHandler
cors: false | CorsConfig | ArkosRequestHandler
expressJson: false | express.JsonOptions | ArkosRequestHandler
cookieParser: false | Parameters<typeof cookieParser> | ArkosRequestHandler
queryParser: false | QueryParserOptions | ArkosRequestHandler
requestLogger: false | ArkosRequestHandler
errorHandler: false | express.ErrorRequestHandler

Router Configuration

v1.4.0+ (Recommended)
v1.3.0

// arkos.config.ts
const arkosConfig: ArkosConfig = {
  routers: {
    strict: "no-bulk",
    welcomeRoute: (req, res) => {
      res.json({ message: "Custom welcome message" });
    },
  },
};

export default arkosConfig;

// src/app.ts - Register custom routers
import arkos from "arkos";
import customRouter from "./routers/custom.router";
import expressRouter from "./routers/express.router";

arkos.init({
  use: [customRouter, expressRouter], // ArkosRouter or Express Router
});

// src/app.ts
arkos.init({
  routers: {
    strict: "no-bulk",
    additional: [customRouter],
    disable: ["welcome-endpoint"],
    replace: {
      welcomeEndpoint: (req, res) => {
        res.json({ message: "Custom welcome" });
      },
    },
  },
});

`routers.strict`

Type: boolean | "no-bulk"
Default: false
Description: Strict mode for routing security (Disables all auto generated endpoints)

`routers.welcomeRoute`

Type: false | ArkosRequestHandler
Description: Custom welcome endpoint handler or false to disable

Advanced Configuration

v1.4.0+ (Recommended)
v1.3.0

// src/app.ts
import arkos from "arkos";
import customRouter from "./routers/custom.router";

arkos.init({
  use: [customRouter],
  configureApp: async (app) => {
    app.set("trust proxy", 1);
    // Custom app configuration
  },
  configureServer: (server) => {
    server.timeout = 30000;
    // Custom server configuration
  },
});

// src/app.ts
arkos.init({
  routers: {
    additional: [customRouter],
  },
  configureApp: async (app) => {
    app.set("trust proxy", 1);
  },
  configureServer: (server) => {
    server.timeout = 30000;
  },
});

`use`

Type: (IArkosRouter | express.Router | ArkosRequestHandler | ArkosErrorRequestHandler)[]
Description: Custom routers and middlewares to add to the application

`configureApp`

Type: (app: express.Express) => any
Description: Function to configure the Express app instance

`configureServer`

Type: (server: http.Server) => any
Description: Function to configure the HTTP server instance

Email Configuration

v1.4.0+ (Recommended)
v1.3.0

// arkos.config.ts
const arkosConfig: ArkosConfig = {
  email: {
    name: "My App",
    host: "smtp.example.com",
    port: 587,
    secure: false,
    auth: {
      user: process.env.EMAIL_USER,
      pass: process.env.EMAIL_PASSWORD,
    },
  },
};

export default arkosConfig;

// src/app.ts
arkos.init({
  email: {
    name: "My App",
    host: "smtp.example.com",
    port: 587,
    secure: false,
    auth: {
      user: process.env.EMAIL_USER,
      pass: process.env.EMAIL_PASSWORD,
    },
  },
});

`email.host`

Type: string
Required: Yes
Description: SMTP host

`email.port`

Type: number
Default: 465
Description: SMTP port

`email.secure`

Type: boolean
Default: true
Description: Use secure connection

`email.auth.user`

Type: string
Required: Yes
Description: SMTP username

`email.auth.pass`

Type: string
Required: Yes
Description: SMTP password

`email.name`

Type: string
Description: Display name for sent emails

Swagger Configuration

v1.4.0+ (Recommended)
v1.3.0

// arkos.config.ts
const arkosConfig: ArkosConfig = {
  swagger: {
    enableAfterBuild: true,
    endpoint: "/api/docs",
    mode: "zod",
    strict: false,
    options: {
      definition: {
        info: {
          title: "My API",
          version: "1.0.0",
          description: "API documentation",
        },
        servers: [{ url: "http://localhost:3000" }],
      },
      deepLinking: true,
      tryItOutEnabled: true,
    },
    scalarApiReferenceConfiguration: {
      theme: "bluePlanet",
    },
  },
};

export default arkosConfig;

// src/app.ts
arkos.init({
  swagger: {
    enableAfterBuild: true,
    endpoint: "/api/docs",
    mode: "zod",
    // ... other options
  },
});

`swagger.enableAfterBuild`

Type: boolean
Default: false
Description: Enable API documentation after build

`swagger.endpoint`

Type: string
Default: "/api/api-docs"
Description: Swagger UI endpoint

`swagger.mode`

Type: "prisma" | "class-validator" | "zod"
Required: Yes
Description: Schema generation mode

`swagger.strict`

Type: boolean
Default: false
Description: Strict schema validation

Request Configuration

v1.4.0+ (Recommended)
v1.3.0

// arkos.config.ts
const arkosConfig: ArkosConfig = {
  request: {
    parameters: {
      allowDangerousPrismaQueryOptions: false,
    },
  },
};

export default arkosConfig;

// src/app.ts
arkos.init({
  request: {
    parameters: {
      allowDangerousPrismaQueryOptions: false,
    },
  },
});

`request.parameters.allowDangerousPrismaQueryOptions`

Type: boolean
Default: false
Description: Allow passing Prisma query options in request parameters

Debugging Configuration

Available from v1.4.0-beta

// arkos.config.ts
const arkosConfig: ArkosConfig = {
  debugging: {
    requests: {
      level: 1,
      filter: ["Query", "Body"],
    },
    dynamicLoader: {
      level: 2,
      filters: {
        modules: ["user", "product"],
        components: ["router", "service"],
      },
    },
  },
};

export default arkosConfig;

Environment Variables

Arkos.js supports the following environment variables:

Variable	Description	Default	Required
`PORT`	Application port number	`8000`	No
`NODE_ENV`	Application environment mode (`development`, `production`, `test`)	`development`	No
`HOST`	Host to bind the server to	`localhost`	No
`DATABASE_URL`	Database connection string	-	Yes
`JWT_SECRET`	Secret key for JWT token signing and verification	-	Yes (if using authentication)
`JWT_EXPIRES_IN`	JWT token expiration time (e.g., "30d", "2h", "3600")	`30d`	No
`JWT_COOKIE_SECURE`	Whether JWT cookie is sent only over HTTPS	`true` in production, `false` in development	No
`JWT_COOKIE_HTTP_ONLY`	Whether JWT cookie is HTTP-only (inaccessible to JavaScript)	`true`	No
`JWT_COOKIE_SAME_SITE`	SameSite attribute for JWT cookie (`lax`, `strict`, `none`)	`"none"` in production, `"lax"` in development	No
`EMAIL_HOST`	SMTP server host for email service	-	No
`EMAIL_PORT`	SMTP server port	`465`	No
`EMAIL_SECURE`	Use secure SMTP connection	`true`	No
`EMAIL_USER`	SMTP authentication username/email	-	No
`EMAIL_PASSWORD`	SMTP authentication password	-	No
`EMAIL_NAME`	Display name for sent emails	-	No

Complete Example

v1.4.0+ (Recommended)
v1.3.0

// arkos.config.ts
import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  port: 3000,
  host: "0.0.0.0",
  welcomeMessage: "Welcome to Our API",

  authentication: {
    enabled: true,
    mode: "static",
    jwt: {
      secret: process.env.JWT_SECRET,
      expiresIn: "7d",
    },
  },

  validation: {
    resolver: "zod",
    strict: false,
  },

  fileUpload: {
    baseUploadDir: "/uploads",
    restrictions: {
      images: {
        maxCount: 5,
        maxSize: 5 * 1024 * 1024,
      },
    },
  },

  middlewares: {
    cors: {
      allowedOrigins: ["https://myapp.com"],
    },
    rateLimit: {
      windowMs: 60000,
      limit: 500,
    },
  },

  routers: {
    strict: "no-bulk",
  },

  email: {
    host: process.env.EMAIL_HOST,
    auth: {
      user: process.env.EMAIL_USER,
      pass: process.env.EMAIL_PASSWORD,
    },
  },

  swagger: {
    mode: "zod",
    enableAfterBuild: false,
  },
};

export default arkosConfig;

// src/app.ts
import arkos from "arkos";
import analyticsRouter from "./routers/analytics.router";

arkos.init({
  use: [analyticsRouter],
  configureApp: (app) => {
    app.set("trust proxy", 1);
  },
});

// src/app.ts
import arkos from "arkos";
import analyticsRouter from "./routers/analytics.router";

arkos.init({
  port: 3000,
  host: "0.0.0.0",
  welcomeMessage: "Welcome to Our API",

  authentication: {
    mode: "static",
    jwt: {
      secret: process.env.JWT_SECRET,
      expiresIn: "7d",
    },
  },

  validation: {
    resolver: "zod",
  },

  fileUpload: {
    baseUploadDir: "/uploads",
    restrictions: {
      images: {
        maxCount: 5,
        maxSize: 5 * 1024 * 1024,
      },
    },
  },

  globalRequestRateLimitOptions: {
    windowMs: 60000,
    limit: 500,
  },

  cors: {
    allowedOrigins: ["https://myapp.com"],
  },

  routers: {
    strict: "no-bulk",
    additional: [analyticsRouter],
  },

  email: {
    host: process.env.EMAIL_HOST,
    auth: {
      user: process.env.EMAIL_USER,
      pass: process.env.EMAIL_PASSWORD,
    },
  },

  swagger: {
    mode: "zod",
    enableAfterBuild: false,
  },

  configureApp: (app) => {
    app.set("trust proxy", 1);
  },
});

Configuration Precedence

Configuration values are loaded in this order (highest priority first):

Values passed directly to arkos.init() (v1.4) or in arkos.config.ts (v1.4)
Environment variables
Default values provided by Arkos.js

Key Changes From v1.4.0-beta​

File Structure Changes​

Configuration Structure​

ArkosInitConfig (arkos.init())​

ArkosConfig (arkos.config.ts)​

Configuration Properties​

Basic Application Settings​

welcomeMessage​

port​

host​

Authentication Configuration​

authentication.enabled​

authentication.mode​

authentication.login.allowedUsernames​

authentication.login.sendAccessTokenThrough​

authentication.rateLimit​

authentication.jwt​

Validation Configuration​

validation.resolver​

validation.strict​

validation.validationOptions​

File Upload Configuration​

fileUpload.baseUploadDir​

fileUpload.baseRoute​

fileUpload.expressStatic​

fileUpload.restrictions​

Middleware Configuration​

Middleware Options​

Router Configuration​

routers.strict​

routers.welcomeRoute​

Advanced Configuration​

use​

configureApp​

configureServer​

Email Configuration​

email.host​

email.port​

email.secure​

email.auth.user​

email.auth.pass​

email.name​

Swagger Configuration​

swagger.enableAfterBuild​

swagger.endpoint​

swagger.mode​

swagger.strict​

Request Configuration​

request.parameters.allowDangerousPrismaQueryOptions​

Debugging Configuration​

Environment Variables​

Complete Example​

Configuration Precedence​

Related Guides​