Configuration

VentureKit uses a layered configuration system that separates concerns cleanly:

Layer	File	Purpose	Changes per environment?
Base	config/base.ts	Project identity	No
Infrastructure	vk.config.ts (flat fields)	Databases, storage, auth pools, queues	Sizing overrides per env
Environment	config/dev.ts, config/prod.ts	Resource sizing, scaling	Yes

Shared infrastructure definitions (names, types, purposes) live directly on vk.config.ts. Per-environment overrides (sizing, behavior) go in config/dev.ts and config/prod.ts. Everything is merged at deploy time into a single ResolvedConfig with no undefined values.

No more config/security.ts

Earlier releases had a fourth Security layer (SecurityConfig with scopes and appClients). It was removed in 0.0.2+: user pools and their app clients are declared as auth intents on vk.config.ts, and authorization scopes are enforced server-side by the runtime — scopes: [...] on a handler — rather than provisioned as Cognito OAuth resource servers. Delete config/security.ts and the security key from defineVenture() when upgrading.

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)

Infrastructure Definitions

Declarative infrastructure intents — declare what you need, not how to build it. Shared definitions go directly on defineVenture() in vk.config.ts, and per-environment overrides go in config/dev.ts / config/prod.ts:

// vk.config.ts — shared definitions (names, types, purposes)
export default defineVenture({
  base,
  databases: [
    { id: 'main', type: 'postgres', name: 'mydb' },
  ],
  storage: [
    { id: 'uploads', purpose: 'uploads' },
  ],
  auth: [
    { id: 'main', signInWith: ['email'], allowSignUp: true, mfa: 'optional' },
  ],
  envs: { dev, prod },
});

// config/prod.ts — per-env overrides (sizing, behavior)
export const prod: EnvConfigInput = {
  preset: 'medium',
  databases: [
    { id: 'main', size: 'large', highAvailability: true, backups: true },
  ],
  storage: [
    { id: 'uploads', cdn: true },
  ],
};

Overrides are matched by id and shallow-merged with the shared definitions at deploy time.

See Infrastructure Intents for all available intent types.

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: 'free',
  api: {
    cors: {
      allowOrigins: ['http://localhost:3000', 'http://localhost:5173'],
    },
  },
};

config/prod.ts

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

export const prod: EnvConfigInput = {
  preset: 'medium',
  api: {
    cors: {
      allowOrigins: ['https://app.example.com'],
      allowCredentials: true,
    },
  },
  identity: { featurePlan: 'essentials' },   // Cognito per-MAU tier, see below
};

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.

Identity

featurePlan — the Cognito User Pool tier applied to every auth[] pool of the stage: 'lite' ($0.0055/MAU beyond 10,000 free MAUs), 'essentials' ($0.015/MAU, same free tier; adds managed-login branding, passwordless, email MFA), or 'plus' ($0.020/MAU with no free tier; adds threat protection). Presets resolve free/nano/micro to lite and medium/large to essentials; no preset provisions plus — opt in explicitly.

Data Safety

dataSafety — 'relaxed', 'standard' or 'strict' retention/deletion policy for stateful resources. Well-known stages get defaults (dev relaxed, stage standard, prod strict); custom stage names (preview, qa, …) fall back to 'standard' unless set explicitly. See Data Safety.

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 { dev } from './config/dev';
import { prod } from './config/prod';

export default defineVenture({
  base,
  databases: [
    { id: 'main', type: 'postgres', name: 'app' },
  ],
  storage: [
    { id: 'uploads', purpose: 'uploads' },
  ],
  auth: [
    { id: 'main', signInWith: ['email'], allowSignUp: true },
  ],
  envs: { dev, prod },
});

Shared infrastructure definitions live directly on defineVenture(). Environment configs (config/dev.ts, config/prod.ts) override only what differs per environment.

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 + resolved environment into ResolvedConfig
5. Validate the entire configuration

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

const config = resolveConfig(base, '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                         # Runs with stage 'local' (the vk dev default)
VENTURE_STAGE=prod vk deploy   # Uses prod config