mantle.config.ts Reference

Project configuration for Mantle, declared via defineConfig() from @mantleframework/core.

// mantle.config.ts
import { defineConfig } from '@mantleframework/core'

export default defineConfig({
  name: 'my-api',
})

The CLI reads this file at build and deploy time. It does not affect Lambda runtime behavior.

---

Top-Level Options

Option	Type	Required	Description
name	string	yes	Project name. Used as prefix for Terraform resource naming.
database	object	—	Database provider config.
auth	object	—	Auth provider config.
features	object	—	Feature flags for observability and resilience.
backend	object	—	Remote Terraform state backend (S3).
customVariables	array	—	Additional Terraform variables appended to variables.tf.
storage	array	—	S3 storage buckets to provision.
eventbridge	object	—	EventBridge custom bus configuration.
cors	object	—	CORS policy for API Gateway responses.
queues	array	—	SQS queues to provision.
dynamodb	array	—	DynamoDB tables to provision.
websocket	object	—	WebSocket API Gateway configuration.
observability	object	—	ADOT and metrics configuration.
secrets	object	—	SOPS-encrypted secrets configuration.
sns	object	—	SNS topics and platform applications.
cloudfront	object	—	CloudFront distribution fronting API Gateway.
authorizer	object	—	API Gateway custom authorizer cache settings.
layers	array	—	Custom Lambda layers.
containerRegistry	object	—	ECR container registry configuration.

---

Database

database: { provider: 'aurora-dsql' }

Option	Type	Description
provider	'aurora-dsql' | 'aurora-serverless-v2' | 'neon'	Database provider.

---

Backend (Terraform State)

backend: {
  s3: {
    bucket: 'my-tfstate',
    key: 'infra.tfstate',
    region: 'us-east-1',
  }
}

Option	Type	Description
s3.bucket	string	S3 bucket name.
s3.key	string	State file key.
s3.region	string	Bucket region.
s3.encrypt	boolean	Enable server-side encryption.
s3.dynamodbTable	string	DynamoDB table name for state locking.
s3.workspaceKeyPrefix	string	Key prefix for Terraform workspaces.

---

EventBridge

eventbridge: {
  bus: 'MyBus',
  sqsTargets: [
    {
      detailType: 'OrderCreated',
      queue: 'OrderQueue',
    }
  ]
}

Option	Type	Description
bus	string	Custom event bus name.
sqsTargets	array	EventBridge rules that route events to SQS queues.
sqsTargets[].detailType	string	EventBridge detail-type to match.
sqsTargets[].queue	string	Queue name (must match an entry in queues).
sqsTargets[].inputTransformer	object	Reshape event before delivery. Has inputPaths and inputTemplate.

---

Storage (S3)

storage: [
  { name: 'assets', cloudfront: true, intelligentTiering: true }
]

Option	Type	Default	Description
name	string	—	Bucket logical name.
bucketNameOverride	string	—	Full bucket name as Terraform expression, bypasses name prefix.
cloudfront	boolean	false	Provision a CloudFront distribution.
cloudfrontPriceClass	string	—	CloudFront price class.
corsOrigins	string[]	—	CORS allowed origins for the bucket.
corsMethods	string[]	—	CORS allowed methods.
intelligentTiering	boolean	false	Enable S3 Intelligent-Tiering.
versioning	boolean	false	Enable object versioning.
assets	string[]	—	Static asset keys to upload. Source path: static/{key} at project root.

---

Queues (SQS)

queues: [
  { name: 'OrderQueue', visibilityTimeoutSeconds: 300 }
]

Option	Type	Default	Description
name	string	—	Queue name. Must match the queue option in defineSqsHandler.
delaySeconds	number	0	Delivery delay in seconds.
maxMessageSize	number	262144	Max message size in bytes.
retentionSeconds	number	345600	Message retention in seconds (4 days).
visibilityTimeoutSeconds	number	30	Visibility timeout in seconds.
enableDlqAlarm	boolean	true	Enable CloudWatch alarm for DLQ message depth.

---

DynamoDB

dynamodb: [
  {
    name: 'idempotency',
    hashKey: 'id',
    attributes: [{ name: 'id', type: 'S' }],
    ttlAttribute: 'expiration',
  }
]

Option	Type	Default	Description
name	string	—	Table logical name.
tableNameOverride	string	—	Full table name as Terraform expression.
hashKey	string	—	Partition key attribute name.
rangeKey	string	—	Sort key attribute name.
attributes	array	—	Attribute definitions. Each has name and type (S, N, B).
billingMode	string	PAY_PER_REQUEST	PAY_PER_REQUEST or PROVISIONED.
ttlAttribute	string	—	Attribute name for TTL-based expiry.
pointInTimeRecovery	boolean	false	Enable PITR.
globalSecondaryIndexes	array	—	GSI definitions. Each has name, hashKey, rangeKey?, projectionType?.

---

WebSocket

websocket: {
  routeSelectionExpression: '$request.body.action',
  stageName: 'live',
}

Option	Type	Default	Description
routeSelectionExpression	string	$request.body.action	Route selection expression.
stageName	string	live	API Gateway stage name.
throttlingBurstLimit	number	100	Burst limit.
throttlingRateLimit	number	50	Rate limit (requests/second).

---

Observability

observability: {
  adot: true,
  metricsNamespace: 'MyApp',
}

Option	Type	Default	Description
adot	boolean	false	Attach AWS Distro for OpenTelemetry (ADOT) layer to all Lambdas.
metricsNamespace	string	—	CloudWatch metrics namespace. Injected as METRICS_NAMESPACE env var.
commonEnv	Record<string, string>	—	Additional env vars injected into all Lambdas via locals.tf.

---

CORS

cors: {
  origins: ['https://app.example.com'],
  methods: ['GET', 'POST'],
  maxAge: 86400,
}

Option	Type	Default	Description
origins	string[]	—	Allowed origins. Empty = no CORS headers (secure default).
methods	string[]	['GET','POST','PUT','DELETE','PATCH','OPTIONS']	Allowed HTTP methods.
headers	string[]	['Content-Type','Authorization']	Allowed request headers.
maxAge	number	86400	Preflight cache max-age in seconds.

---

Secrets (SOPS)

secrets: {
  provider: 'sops',
  filePattern: 'secrets.{env}.enc.yaml',
}

Option	Type	Default	Description
provider	'sops'	—	Secrets provider. Only sops is supported.
filePattern	string	secrets.{env}.enc.yaml	Encrypted file pattern. {env} is replaced with staging or prod.

Per-Lambda secrets are mapped in defineLambda({ secrets: { ENV_VAR: 'sops.key.path' } }).

---

SNS

sns: {
  topics: [{ name: 'notifications' }],
  platformApplications: [
    {
      name: 'my-app',
      platform: 'APNS_SANDBOX',
      credentialSecret: 'apns.privateKey',
      principalSecret: 'apns.certificate',
    }
  ],
}

Option	Type	Description
topics[].name	string	Topic name. Wired as env var.
platformApplications[].name	string	Application name.
platformApplications[].platform	'APNS' | 'APNS_SANDBOX' | 'GCM'	Push platform.
platformApplications[].credentialSecret	string	SOPS key path for the platform credential.
platformApplications[].principalSecret	string	SOPS key path for the platform principal.
platformApplications[].resourceName	string	Override for the Terraform resource identifier.

---

CloudFront (API Distribution)

cloudfront: {
  apiDistribution: {
    geoRestriction: { type: 'whitelist', locations: ['US', 'CA'] },
    forwardedHeaders: ['Authorization', 'X-API-Key'],
    cacheTtl: { default: 0, min: 0, max: 0 },
  }
}

Option	Type	Description
apiDistribution.geoRestriction	object	type: whitelist or blacklist. locations: ISO 3166-1 alpha-2 codes.
apiDistribution.forwardedHeaders	string[]	Headers forwarded to the origin.
apiDistribution.cacheTtl	object	Cache TTL settings: default, min, max in seconds.

---

Custom Lambda Layers

layers: [
  {
    name: 'ffmpeg',
    path: 'layers/ffmpeg',
    compatibleArchitectures: ['x86_64'],
    description: 'ffmpeg binary',
  }
]

Option	Type	Default	Description
name	string	—	Layer name. Referenced in defineLambda({ layers: ['local.ffmpeg_layer_arn'] }).
path	string	—	Path to layer source directory, relative to project root.
compatibleArchitectures	string[]	['arm64']	arm64 and/or x86_64.
compatibleRuntimes	string[]	—	Compatible runtimes (e.g. ['nodejs24.x']). Omit for binary-only layers.
description	string	—	Human-readable description.

---

Custom Terraform Variables

customVariables: [
  {
    name: 'api_quota_limit',
    type: 'number',
    description: 'Daily API quota',
    default: '10000',
  }
]

Option	Type	Description
name	string	Variable name.
type	string	Terraform type expression: string, number, bool, list(string), etc.
description	string	Variable description.
default	string	Default value as Terraform expression string. Omit for required variables.
sensitive	boolean	Mark as sensitive (redacted in plan output).
validation	object	condition: Terraform expression. errorMessage: shown on violation.

---

Authorizer

authorizer: { cacheTtl: 0 }

Option	Type	Default	Description
cacheTtl	number	300	Token cache TTL in seconds. 0 disables caching and identity source validation.

---

Extended CLI Config

For CI, hooks, and conventions settings, use defineToolingConfig from @mantleframework/cli/config instead of defineConfig. See the CLI reference for details.