Configuration

VentureKit uses a three-layer configuration system that separates concerns cleanly:

Layer	File	Purpose	Changes per environment?
Base	config/base.ts	Project identity	No
Security	config/security.ts	OAuth scopes, app clients	No
Environment	config/dev.ts, config/prod.ts	Resource sizing, scaling	Yes

These layers are merged at deploy time into a single ResolvedConfig with no undefined values.

Base Config

Project identity that never changes between environments:

config/base.ts

import type { BaseConfig } from '@venturekit/core';

export const base: BaseConfig = {
  name: 'my-api',          // Lowercase, no spaces, used in resource naming
  displayName: 'My API',   // Display name for UI/logs
  region: 'eu-west-1',     // AWS region (same for all environments)
};

Validation rules:

• name must start with a lowercase letter, contain only [a-z0-9-], max 32 characters
• displayName is required
• region must be a valid AWS region format (e.g., eu-west-1)

Security Config

Authentication and authorization settings, shared across all environments:

config/security.ts

import type { SecurityConfig } from '@venturekit/core';

export const security: SecurityConfig = {
  scopes: [
    { name: 'api.read', description: 'Read API data' },
    { name: 'api.write', description: 'Write API data' },
  ],
  appClients: [
    {
      name: 'web-app',
      allowedScopes: ['api.read', 'api.write'],
      supportsRefreshTokens: true,
    },
    {
      name: 'admin-dashboard',
      allowedScopes: ['api.read', 'api.write', 'admin'],
      supportsRefreshTokens: true,
      generateSecret: true,  // Server-side client
    },
  ],
  mfa: 'optional',           // 'off' | 'optional' | 'required'
  passwordPolicy: {
    minLength: 8,
    requireUppercase: true,
    requireNumbers: true,
  },
};

Validation rules:

• At least one scope is required
• At least one app client is required
• All allowedScopes must reference defined scopes

Environment Config

Resource sizing that changes per environment. Start with a preset and override as needed:

config/dev.ts

import type { EnvConfigInput } from '@venturekit/core';

export const dev: EnvConfigInput = {
  preset: 'nano',
  dataSafety: 'relaxed',
  lambda: {
    logRetentionDays: 3,
  },
  api: {
    cors: {
      allowOrigins: ['http://localhost:3000', 'http://localhost:5173'],
    },
  },
};

config/prod.ts

import type { EnvConfigInput } from '@venturekit/core';

export const prod: EnvConfigInput = {
  preset: 'medium',
  dataSafety: 'strict',
  lambda: {
    memoryMb: 512,
    timeoutSec: 15,
    logRetentionDays: 90,
    tracingEnabled: true,
  },
  api: {
    throttleRateLimit: 100,
    throttleBurstLimit: 200,
    cors: {
      allowOrigins: ['https://app.example.com'],
      allowCredentials: true,
    },
  },
  observability: {
    alarmsEnabled: true,
    tracingEnabled: true,
    detailedMetricsEnabled: true,
  },
};

Configurable Sections

Lambda

memoryMb (128–10240), timeoutSec (1–900), vpcEnabled, logRetentionDays, tracingEnabled, architecture (arm64 | x86_64), runtime, IAM policies.

API Gateway

throttleRateLimit, throttleBurstLimit, cors (origins, methods, headers, credentials), customDomain (domain name, certificate ARN).

VPC

maxAzs (1–3), natGateways, subnets, security group rules.

Observability

alarmsEnabled, tracingEnabled, detailedMetricsEnabled, log group config, metrics config.

WebSocket

enabled, routeSelectionExpression, idleTimeoutSec, throttleRateLimit, throttleBurstLimit.

VentureKit Config File

The vk.config.ts at your project root wires everything together:

import { defineVenture } from '@venturekit/infra';
import { base } from './config/base';
import { security } from './config/security';
import { dev } from './config/dev';
import { prod } from './config/prod';

export default defineVenture({
  base,
  security,
  envs: { dev, prod },
  routesDir: 'src/routes',

  // Optional: declarative infrastructure
  infrastructure: {
    databases: [{ id: 'main', type: 'postgres', size: 'small', name: 'mydb' }],
    storage: [{ id: 'uploads', purpose: 'uploads', cdn: true }],
  },
});

Config Resolution

At deploy time, VentureKit resolves the full configuration:

1. Select the environment from VENTURE_STAGE (defaults to dev)
2. Look up the matching preset (if specified)
3. Merge preset defaults with explicit overrides
4. Combine base + security + resolved environment into ResolvedConfig
5. Validate the entire configuration

import { resolveConfig } from '@venturekit/core';

const config = resolveConfig(base, security, 'prod', prodInput);
// Returns a ResolvedConfig with all fields defined — no undefined values

Environment Selection

The VENTURE_STAGE environment variable controls which config is used:

vk dev                         # Uses dev config
VENTURE_STAGE=stage vk deploy  # Uses stage config
VENTURE_STAGE=prod vk deploy   # Uses prod config