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

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;
}

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

`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

`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

`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

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

`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

`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

`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

`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

`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

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

On this page