Arkos Configuration

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

Configuration Object Structure

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

    // Authentication configuration
    authentication?: AuthenticationConfig;

    // Validation configuration
    validation?: ValidationConfig;

    // File upload configuration
    fileUpload?: FileUploadConfig;

    // Security configuration
    globalRequestRateLimitOptions?: Partial<RateLimitOptions>;
    cors?: CorsConfig;

    // Middleware configuration
    middlewares?: MiddlewareConfig;

    // Router configuration
    routers?: RouterConfig;

    // Advanced configuration
    configureApp?: (app: express.Express) => any;
    configureServer?: (server: http.Server) => any;

    // Email configuration
    email?: EmailConfig;

    // Swagger/OpenAPI configuration
    swagger?: SwaggerConfig;

    // Request configuration
    request?: RequestConfig;
}

Configuration Properties

Basic Application Settings

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
• Description: Port where the application will run

host

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

Authentication Configuration

interface AuthenticationConfig {
    mode: "static" | "dynamic";
    login?: {
        allowedUsernames?: string[];
        sendAccessTokenThrough?: "cookie-only" | "response-only" | "both";
    };
    passwordValidation?: {
        regex: RegExp;
        message?: string;
    };
    requestRateLimitOptions?: Partial<RateLimitOptions>;
    jwt?: {
        secret?: string;
        expiresIn?: MsDuration | number;
        cookie?: {
            secure?: boolean;
            httpOnly?: boolean;
            sameSite?: "lax" | "strict" | "none";
        };
    };
}

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.passwordValidation

• Type: { regex: RegExp; message?: string }
• Default: { regex: /^(?=.*[A-Z])(?=.*[a-z])(?=.*\d).+$/ }
• Description: Password strength requirements

authentication.requestRateLimitOptions

• Type: Partial<RateLimitOptions>
• Default:

{
  windowMs: 5000,
  limit: 10,
  standardHeaders: "draft-7",
  legacyHeaders: false,
}

• Description: Rate limiting for authentication endpoints

authentication.jwt

• Type: Object containing JWT configuration
• Description: JWT token settings

Validation Configuration

type ValidationConfig =
    | {
          resolver?: "class-validator";
          validationOptions?: ValidatorOptions;
      }
    | {
          resolver?: "zod";
          validationOptions?: Record<string, any>;
      };

validation.resolver

• Type: "class-validator" | "zod"
• Default: "class-validator"
• Description: Validation library to use

validation.validationOptions

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

File Upload Configuration

interface FileUploadConfig {
    baseUploadDir?: string;
    baseRoute?: string;
    expressStaticOptions?: Parameters<typeof express.static>[1];
    restrictions?: {
        images?: {
            maxCount?: number;
            maxSize?: number;
            supportedFilesRegex?: RegExp;
        };
        videos?: {
            maxCount?: number;
            maxSize?: number;
            supportedFilesRegex?: RegExp;
        };
        documents?: {
            maxCount?: number;
            maxSize?: number;
            supportedFilesRegex?: RegExp;
        };
        files?: {
            maxCount?: number;
            maxSize?: number;
            supportedFilesRegex?: RegExp;
        };
    };
}

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.expressStaticOptions

• Type: Parameters<typeof express.static>[1]
• Default:

{
  maxAge: "1y",
  etag: true,
  lastModified: true,
  dotfiles: "ignore",
  fallthrough: true,
  index: false,
  cacheControl: true,
}

• Description: Options for express.static middleware

fileUpload.restrictions

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

Security Configuration

globalRequestRateLimitOptions

• Type: Partial<RateLimitOptions>
• Default:

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

• Description: Global rate limiting settings

interface CorsConfig {
    allowedOrigins?: string | string[] | "*";
    options?: cors.CorsOptions;
    customHandler?: cors.CorsOptionsDelegate;
}

cors.allowedOrigins

• Type: string | string[] | "*"
• Default: "*" in development, domain-specific in production
• Description: Allowed origins for CORS

cors.options

• Type: cors.CorsOptions
• Description: Additional CORS options

cors.customHandler

• Type: cors.CorsOptionsDelegate
• Description: Custom CORS handler function

Middleware Configuration

interface MiddlewareConfig {
    additional?: express.RequestHandler[];
    disable?: (
        | "compression"
        | "global-rate-limit"
        | "auth-rate-limit"
        | "cors"
        | "express-json"
        | "cookie-parser"
        | "query-parser"
        | "request-logger"
        | "global-error-handler"
    )[];
    replace?: {
        compression?: express.RequestHandler;
        globalRateLimit?: express.RequestHandler;
        authRateLimit?: express.RequestHandler;
        cors?: express.RequestHandler;
        expressJson?: express.RequestHandler;
        cookieParser?: express.RequestHandler;
        queryParser?: express.RequestHandler;
        requestLogger?: express.RequestHandler;
        globalErrorHandler?: express.ErrorRequestHandler;
    };
}

middlewares.additional

• Type: express.RequestHandler[]
• Description: Additional custom middlewares to add

middlewares.disable

• Type: Array of middleware names
• Description: Built-in middlewares to disable

middlewares.replace

• Type: Object containing replacement middlewares
• Description: Replace built-in middlewares with custom implementations

Router Configuration

interface RouterConfig {
    strict?: boolean | "no-bulk";
    additional?: express.Router[];
    disable?: (
        | "auth-router"
        | "prisma-models-router"
        | "file-upload"
        | "welcome-endpoint"
    )[];
    replace?: {
        authRouter?: (
            config: ArkosConfig
        ) => express.Router | Promise<express.Router>;
        prismaModelsRouter?: (
            config: ArkosConfig
        ) => express.Router | Promise<express.Router>;
        fileUpload?: (
            config: ArkosConfig
        ) => express.Router | Promise<express.Router>;
        welcomeEndpoint?: express.RequestHandler;
    };
}

routers.strict

• Type: boolean | "no-bulk"
• Default: false
• Description: Strict mode for routing security

routers.additional

• Type: express.Router[]
• Description: Additional custom routers to add

routers.disable

• Type: Array of router names
• Description: Built-in routers to disable

routers.replace

• Type: Object containing replacement routers
• Description: Replace built-in routers with custom implementations

Advanced Configuration

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

interface EmailConfig {
    host: string;
    port?: number;
    secure?: boolean;
    auth: {
        user: string;
        pass: string;
    };
    name?: string;
}

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

interface SwaggerConfig {
    enableAfterBuild?: boolean;
    endpoint?: string;
    mode: "prisma" | "class-validator" | "zod";
    strict?: boolean;
    options?: {
        definition?: {
            openapi?: string;
            info?: {
                title?: string;
                version?: string;
                description?: string;
            };
            servers?: {
                url: string;
                description?: string;
            }[];
            paths?: OpenAPIV3.PathsObject;
            termsOfService?: string;
            contact?: {
                name?: string;
                url?: string;
                email?: string;
            };
            license?: {
                name: string;
                url?: string;
            };
            tags?: {
                name: string;
                description?: string;
            }[];
            components?: {
                securitySchemes?: Record<string, any>;
                schemas?: Record<string, any>;
            };
            security?: Array<Record<string, string[]>>;
        };
        apis?: string[];
        deepLinking?: boolean;
        tryItOutEnabled?: boolean;
        persistAuthorization?: boolean;
    };
    scalarApiReferenceConfiguration?: Partial<ApiReferenceConfiguration>;
}

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

interface RequestConfig {
    parameters?: {
        allowDangerousPrismaQueryOptions?: boolean;
    };
}

request.parameters.allowDangerousPrismaQueryOptions

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

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

Configuration Precedence

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

1. Values passed directly to arkos.init()
2. Environment variables
3. Default values provided by Arkos.js

Example Configuration

import arkos from "arkos";

arkos.init({
    port: 3000,
    host: "0.0.0.0",
    authentication: {
        mode: "static",
        jwt: {
            secret: process.env.JWT_SECRET,
            expiresIn: "7d",
        },
    },
    validation: {
        resolver: "zod",
    },
    cors: {
        allowedOrigins: ["https://example.com", "https://api.example.com"],
    },
    routers: {
        strict: true,
    },
    configureApp: (app) => {
        app.set("trust proxy", 1);
    },
});