Getting Started

Configuration

Arkos provides a comprehensive configuration system that lets you customize every aspect of your application. Since v1.4.0, configuration is split between static settings in arkos.config.ts and runtime setup in src/app.ts.

Configuration Overview

In v1.6+, Arkos uses defineConfig for full type safety and IDE autocomplete:

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

export default defineConfig({
  middlewares: {
    cors: { allowedOrigins: "*" },
  },
  authentication: {
    mode: "static",
  },
  validation: {
    resolver: "zod",
  },
});
src/app.ts
import arkos from "arkos";
import analyticsRouter from "./routers/analytics.router";

const app = arkos();

app.use(analyticsRouter);

app.listen();

In v1.4–v1.5, static configuration lives in arkos.config.ts and runtime setup in arkos.init():

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

const arkosConfig: ArkosConfig = {
  middlewares: {
    cors: { allowedOrigins: "*" },
  },
  authentication: {
    mode: "static",
  },
  validation: {
    resolver: "zod",
  },
};

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);
  },
  configureServer: (server) => {
    server.setTimeout(30000);
  },
});

In v1.3, all configuration is passed directly to arkos.init() in src/app.ts:

src/app.ts
import arkos from "arkos";

arkos.init({
  cors: { allowedOrigins: "*" },
  authentication: { mode: "static" },
  validation: { resolver: "zod" },
  routers: { additional: [customRouter] },
  middlewares: { additional: [customMiddleware] },
});

For the full list of all available configuration options see Arkos Configuration.

Basic Application Settings

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

export default defineConfig({
  welcomeMessage: "Welcome to My API",
  port: 8000,
  host: "localhost",
  globalPrefix: "/api",
});
arkos.config.ts
import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  welcomeMessage: "Welcome to My API",
  port: 8000,
  host: "localhost",
};

export default arkosConfig;
src/app.ts
arkos.init({
  welcomeMessage: "Welcome to My API",
  port: 8000,
  host: "localhost",
});

Authentication

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

export default defineConfig({
  authentication: {
    mode: "static",
    login: {
      allowedUsernames: ["email", "username"],
      sendAccessTokenThrough: "both",
    },
    jwt: {
      secret: process.env.JWT_SECRET,
      expiresIn: "30d",
      cookie: {
        secure: true,
        httpOnly: true,
        sameSite: "lax",
      },
    },
  },
});
arkos.config.ts
import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  authentication: {
    mode: "static",
    login: {
      allowedUsernames: ["email", "username"],
      sendAccessTokenThrough: "both",
    },
    jwt: {
      secret: process.env.JWT_SECRET,
      expiresIn: "30d",
      cookie: {
        secure: true,
        httpOnly: true,
        sameSite: "lax",
      },
    },
  },
};

export default arkosConfig;
src/app.ts
arkos.init({
  authentication: {
    mode: "static",
    login: {
      allowedUsernames: ["email", "username"],
      sendAccessTokenThrough: "both",
    },
    jwt: {
      secret: process.env.JWT_SECRET,
      expiresIn: "30d",
    },
  },
});

See Authentication Setup for full details.

Validation

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

export default defineConfig({
  validation: {
    resolver: "zod", // or "class-validator"
  },
});
arkos.config.ts
import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  validation: {
    resolver: "zod",
  },
};

export default arkosConfig;
src/app.ts
arkos.init({
  validation: {
    resolver: "class-validator",
    validationOptions: {
      whitelist: true,
      forbidNonWhitelisted: true,
    },
  },
});

See Validation Setup for full details.

File Upload

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

export default defineConfig({
  fileUpload: {
    baseUploadDir: "./uploads",
    baseRoute: "/api/files",
    restrictions: {
      images: {
        maxCount: 10,
        maxSize: 5 * 1024 * 1024,
        supportedFilesRegex: /\.(jpg|jpeg|png|gif)$/i,
      },
      documents: {
        maxCount: 5,
        maxSize: 10 * 1024 * 1024,
        supportedFilesRegex: /\.(pdf|doc|docx)$/i,
      },
    },
  },
});
arkos.config.ts
import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  fileUpload: {
    baseUploadDir: "./uploads",
    baseRoute: "/api/files",
    restrictions: {
      images: {
        maxCount: 10,
        maxSize: 5 * 1024 * 1024,
        supportedFilesRegex: /\.(jpg|jpeg|png|gif)$/i,
      },
    },
  },
};

export default arkosConfig;
src/app.ts
arkos.init({
  fileUpload: {
    baseUploadDir: "./uploads",
    restrictions: {
      images: {
        maxCount: 10,
        maxSize: 5 * 1024 * 1024,
      },
    },
  },
});

See File Upload Setup for full details.

Middlewares

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

export default defineConfig({
  middlewares: {
    rateLimit: { windowMs: 60 * 1000, limit: 100 },
    cors: {
      allowedOrigins: ["https://myapp.com"],
      options: { credentials: true },
    },
    compression: { level: 6 },
    expressJson: { limit: "10mb" },
    requestLogger: false,
  },
});

Custom middlewares and routers are registered via app.use() in src/app.ts:

src/app.ts
import arkos from "arkos";
import myMiddleware from "./middlewares/my-middleware";
import analyticsRouter from "./routers/analytics.router";

const app = arkos();

app.use(myMiddleware);
app.use(analyticsRouter);

app.listen();
arkos.config.ts
import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  middlewares: {
    rateLimit: { windowMs: 60 * 1000, limit: 100 },
    cors: {
      allowedOrigins: ["https://myapp.com"],
      options: { credentials: true },
    },
    compression: { level: 6 },
  },
};

export default arkosConfig;
src/app.ts
import arkos from "arkos";
import myMiddleware from "./middlewares/my-middleware";

arkos.init({
  use: [myMiddleware],
});
src/app.ts
arkos.init({
  middlewares: {
    additional: [customMiddleware],
  },
  globalRequestRateLimitOptions: {
    windowMs: 60 * 1000,
    limit: 100,
  },
  cors: {
    allowedOrigins: ["https://myapp.com"],
  },
});

See Global Middlewares for the full list and options.

Routers

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

export default defineConfig({
  routers: {
    strict: true,
    welcomeRoute: false,
  },
});
arkos.config.ts
import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  routers: {
    strict: true,
    welcomeRoute: false,
  },
};

export default arkosConfig;
src/app.ts
arkos.init({
  routers: {
    strict: true,
    additional: [customRouter],
  },
});

Advanced Runtime Configuration

These options live in src/app.ts regardless of version since they require access to the live Express app or HTTP server:

src/app.ts
import arkos from "arkos";
import helmet from "helmet";

const app = arkos();

app.set("trust proxy", 1);
app.use(helmet());

app.listen();

For WebSocket support or custom HTTP server access:

src/app.ts
import arkos from "arkos";
import http from "http";
import { Server } from "socket.io";

const app = arkos();

async function start() {
  await app.build();

  const server = http.createServer(app);
  const io = new Server(server);

  app.listen(server);
}

start();
src/app.ts
import arkos from "arkos";

arkos.init({
  configureApp: (app) => {
    app.set("trust proxy", 1);
    app.set("view engine", "ejs");
  },
  configureServer: (server) => {
    server.setTimeout(30000);
  },
});
src/app.ts
import arkos from "arkos";

arkos.init({
  configureApp: (app) => {
    app.set("trust proxy", 1);
  },
  configureServer: (server) => {
    server.setTimeout(30000);
  },
});

Environment Variables

Arkos picks up several environment variables automatically:

.env
# Database
DATABASE_URL=postgresql://username:password@localhost:5432/dbname

# JWT
JWT_SECRET=your-super-secret-jwt-key
JWT_EXPIRES_IN=30d
JWT_COOKIE_SECURE=true
JWT_COOKIE_HTTP_ONLY=true
JWT_COOKIE_SAME_SITE=lax

# Server
PORT=8000
NODE_ENV=development
HOST=localhost

# Email
EMAIL_HOST=smtp.gmail.com
EMAIL_PORT=465
EMAIL_SECURE=true
EMAIL_USER=you@example.com
EMAIL_PASSWORD=your-smtp-password
EMAIL_NAME=Your App

Arkos loads environment variables in this order (highest priority first):

  1. Process environment variables (system-level)
  2. .env
  3. .env.local
  4. .env.[NODE_ENV].local
  5. .env.[NODE_ENV]
  6. .env.defaults

Complete Example

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

export default defineConfig({
  port: 8000,
  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,
      },
    },
  },
  middlewares: {
    cors: { allowedOrigins: ["https://myapp.com"] },
    rateLimit: { windowMs: 60000, limit: 500 },
    compression: { level: 6 },
  },
  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,
  },
});
src/app.ts
import arkos from "arkos";
import analyticsRouter from "./routers/analytics.router";

const app = arkos();

app.set("trust proxy", 1);
app.use(analyticsRouter);

app.listen();
arkos.config.ts
import { ArkosConfig } from "arkos";

const arkosConfig: ArkosConfig = {
  port: 8000,
  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,
      },
    },
  },
  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,
    },
  },
};

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);
  },
  configureServer: (server) => {
    server.setTimeout(30000);
  },
});
src/app.ts
import arkos from "arkos";
import analyticsRouter from "./routers/analytics.router";

arkos.init({
  port: 8000,
  welcomeMessage: "Welcome to Our API",
  authentication: {
    mode: "static",
    jwt: {
      secret: process.env.JWT_SECRET,
      expiresIn: "7d",
    },
  },
  validation: { resolver: "zod" },
  fileUpload: {
    baseUploadDir: "/uploads",
  },
  routers: {
    strict: "no-bulk",
    additional: [analyticsRouter],
  },
  configureApp: (app) => {
    app.set("trust proxy", 1);
  },
});

Project Structure

Previous Page

Deployment

Next Page

On this page

Configuration OverviewBasic Application SettingsAuthenticationValidationFile UploadMiddlewaresRoutersAdvanced Runtime ConfigurationEnvironment VariablesComplete Example