Configuration Files

Stacktape configuration defines your infrastructure as code in a single file. You declare resources — APIs, databases, containers, functions — and Stacktape provisions them on AWS. The configuration supports two formats: TypeScript (recommended) and YAML. Both produce identical infrastructure; the choice affects your authoring experience.

Choosing a format

TypeScript is the recommended format for most teams. It provides full type safety, IDE autocompletion, conditional logic, loops, and the ability to split configuration across multiple files with standard imports. YAML works for straightforward projects where configuration is static and short.

FeatureTypeScriptYAML
Type checking✓✕
IDE autocompletionFullWith VS Code extension
Conditional logicNative (if/else, ternary)Via directives only
Loops / dynamic resourcesNative (for, map)✕
Code reuseImports, functions, modulesVariables only
Refactoring support✓✕
Multi-file configs✓✕
Use TypeScript when your configuration involves per-stage differences, dynamic resource creation, or shared patterns across projects. Use YAML for prototypes or small projects with a fixed set of resources.

When to use TypeScript

Most teams should default to TypeScript. It catches configuration errors before deployment, enables per-stage branching without separate config files, and supports extracting shared patterns into reusable modules. If your project has more than a handful of resources, or if you deploy to multiple stages with different sizing, TypeScript eliminates duplication and reduces misconfiguration risk.

When to use YAML

YAML is appropriate for very small, static projects or when your team strongly prefers declarative-only configuration. A single Lambda function with an API gateway, or a static hosting bucket with a custom domain — these are cases where YAML's simplicity is an advantage. If you keep the same resource names and properties, TypeScript can represent the same configuration shape as YAML, so you can move to TypeScript later when you outgrow YAML (needing conditionals, loops, or multi-file organization).

TypeScript configuration

Create a stacktape.ts file in your project root. Install the stacktape package as a dev dependency to get types and resource classes.

npm install stacktape --save-dev

The TypeScript config uses defineConfig as its entry point. You instantiate resource classes, configure them with typed properties, and return them from the callback.

export default defineConfig(({ stage }) => {
  const api = new HttpApiGateway({
    cors: { enabled: true }
  });

  const handler = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/handler.ts'
    }),
    events: [
      new HttpApiIntegration({
        httpApiGatewayName: 'api',
        method: 'GET',
        path: '/'
      })
    ]
  });

  return {
    resources: { api, handler }
  };
});

The defineConfig callback

The defineConfig function receives a callback whose argument provides deploy-time context. Use these values for per-stage branching without separate config files.

PropertyTypeDescription
stagestringCurrent stage name (e.g. dev, production)
regionstringAWS region for this deployment (e.g. eu-west-1)
projectNamestringProject name: --project, the settings object, or the machine-wide default
commandstringThe CLI command being run (deploy, delete, dev, etc.)
cliArgsReadonly<Record<string, unknown>>The options of the current command, as typed on the command line. See Command-line options in the config
awsProfilestringThe local AWS profile the command uses
user{ id, name, email } or undefinedThe signed-in Stacktape user. Local commands such as package, synth and validate have none

Command-line options in the config

cliArgs holds the options you passed to the current command, keyed by their camelCase option names. Some options have a different internal name: --config arrives as configPath and --project as projectName. Options you did not type are usually not in it, but projectName and region declared in the config are, so do not treat their presence as a command-line override. Every value is unknown, so check its type before you use it.

cliArgs accepts only the command's own options. Pass your own values after -- and read them with the $CliArgs() directive instead. Write each one as --name value; the form --name=value is not split into a name and a value.

stacktape deploy --stage dev --region eu-west-1 --config stacktape.ts -- --seed demo

For this command, cliArgs is { stage: 'dev', region: 'eu-west-1', configPath: 'stacktape.ts' }, and $CliArgs('seed') resolves to 'demo':

import { defineConfig, LambdaFunction, JsBundleLambdaPackaging } from 'stacktape';

export default defineConfig(({ cliArgs }) => {
  const handler = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({ entryfilePath: './src/handler.ts' }),
    environment: {
      // Passed with --config; 'stacktape.ts' when the option was not typed.
      CONFIG_FILE: typeof cliArgs.configPath === 'string' ? cliArgs.configPath : 'stacktape.ts',
      // Passed after --; 'none' when it is missing.
      SEED: "$CliArgs('seed', 'none')"
    }
  });

  return { resources: { handler } };
});

Project name and region

Declare the project name and region in the first argument of defineConfig. Commands run inside the project then need only --stage: stacktape deploy --stage dev, stacktape logs api --stage dev, stacktape status --stage dev.

export default defineConfig({ projectName: 'my-app', region: 'eu-west-1' }, ({ stage }) => ({

Stacktape reads these two values before it runs the config, because choosing credentials and the AWS region comes first. Write them as plain strings: a variable, an environment variable or another computed value is rejected with the supported form. Return everything else from the callback; the callback always receives the effective projectName and region.

A --project or --region flag overrides the config for one command. Without a value in the config, the region comes from AWS_DEFAULT_REGION, the machine-wide default (stacktape defaults set region) and then the AWS profile, in that order. Commands that do not use the config, such as stacktape secret get, take only the region from it and never fail because of it.

Conditional logic and loops

Because the config is standard TypeScript, you can use any language feature to create resources dynamically. Branch on stage to size resources differently for production vs development, or loop over a list to generate multiple similar resources.

export default defineConfig(({ stage }) => {
  const database = new RelationalDatabase({
    engine: new RdsEnginePostgres({
      version: '16',
      primaryInstance: {
        instanceSize: 'db.t4g.micro'
      }
    }),
    credentials: {
      masterUserPassword: $Secret('db-password')
    }
  });

  const usersHandler = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/handlers/users.ts'
    }),
    connectTo: [database]
  });

  return {
    resources: { database, usersHandler }
  };
});

Splitting config across files

For large configurations, extract resource factory functions into separate .ts files and import them in stacktape.ts — a standard TypeScript module pattern. For example, define a createDatabase function in config/database.ts that accepts a stage parameter and returns a RelationalDatabase instance, then import it in your main config. The following example shows this pattern with the helper function defined inline for illustration:

const createDatabase = (stage: string) =>
new RelationalDatabase({
  engine: new RdsEnginePostgres({
    version: '16',
    primaryInstance: {
      instanceSize: stage === 'production' ? 'db.t4g.medium' : 'db.t4g.micro'
    }
  }),
  credentials: {
    masterUserPassword: $Secret('db-password')
  }
});

export default defineConfig(({ stage }) => {
  const database = createDatabase(stage);
  return { resources: { database } };
});

In practice, you would move createDatabase to a separate file (e.g. config/database.ts), export it, and import { createDatabase } from './config/database' in your stacktape.ts. The pattern works identically — the helper returns a resource class instance that you include in the resources object.

IDE experience

With TypeScript, your editor provides autocompletion for every property, inline JSDoc documentation on hover, go-to-definition for resource types, and real-time error highlighting. Typos in property names or invalid values are caught before you deploy. The stacktape package ships its own type definitions — no additional @types package is needed.

YAML configuration

For simpler projects, create a stacktape.yml file in your project root.

YAML uses a type + properties structure for each resource. The type corresponds to the TypeScript resource class, and properties correspond to the constructor argument.

The Stacktape VS Code extension provides autocompletion, syntax validation, and inline documentation for YAML configuration files.

When YAML falls short

YAML configuration cannot express conditional logic natively — you need directives for deploy-time interpolation. There are no loops, so you cannot generate resources dynamically. Large YAML configs tend to become repetitive because there is no import mechanism; variables provide limited reuse. If you find yourself working around these constraints, switch to TypeScript.

Config file structure

Regardless of format, every Stacktape configuration has the same logical structure. The only required field is resources.

Top-level fieldPurpose
resourcesYour infrastructure: functions, containers, databases, buckets, etc.
variablesReusable values referenced with $Var().variableName. In TypeScript, ordinary constants are often simpler when deploy-time resolution is not needed
hooksRun scripts before/after deploy, delete, or dev commands
scriptsShell commands or code files you can run manually or via hooks
directivesCustom deploy-time functions that compute config values dynamically
deploymentConfigRollback behavior, termination protection, artifact retention
stackConfigTags, custom outputs, VPC configuration
providerConfigCredentials for third-party services (MongoDB Atlas, Upstash)
cloudformationResourcesRaw CloudFormation resources (escape hatch)

The following example shows a configuration with multiple resources wired together using connectTo. For additional top-level fields like scripts and hooks, see Hooks and scripts.

export default defineConfig(({ stage }) => {
  const database = new RelationalDatabase({
    engine: new RdsEnginePostgres({
      version: '16',
      primaryInstance: { instanceSize: 'db.t4g.micro' }
    }),
    credentials: {
      masterUserPassword: $Secret('db-password')
    }
  });

  const api = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/handler.ts'
    }),
    connectTo: [database]
  });

  return {
    resources: { database, api }
  };
});

Config file detection

Stacktape auto-detects a configuration file named stacktape.ts, stacktape.yml, stacktape.yaml, or stacktape.js in your project root (or in --cwd). You can point to a different location with the --config option. See the deploy command reference for details.

When the directory holds more than one of these files, for example a stacktape.yml left next to its stacktape.ts rewrite, a command that loads the config stops with CONFIG_FILE_AMBIGUOUS instead of guessing. Pass the one to use with --config, or delete or rename the file you no longer use. Each file can name another project, stage or region, so Stacktape does not pick one by precedence.

stacktape deploy --stage production --config ./infrastructure/stacktape.ts

Directives in configuration

Both TypeScript and YAML configurations support directives — built-in functions that resolve values at deploy time. In TypeScript, directives are imported as functions from the stacktape package. In YAML, all directives use a $DirectiveName() string syntax.

Common built-in directives available as TypeScript functions from the stacktape package:

DirectivePurpose
$Secret()Reference a Stacktape secret
$ResourceParam()Reference a deployed resource's parameter
$Stage()Returns the current stage name
$Region()Returns the current AWS region
$Format()String interpolation with deploy-time values
$Var()Reference a value from the variables section
$File()Include contents of a file at deploy time

In TypeScript configs, you can often use normal constants instead of $Var(), standard import/readFileSync instead of $File(), and template literals instead of $Format(). The directive functions are available when you need deploy-time resolution behavior that cannot be replaced by build-time TypeScript evaluation.

See Directives for the full list of available directives and detailed usage.

How TypeScript maps to YAML

YAML resources use a type plus properties shape. In TypeScript, the equivalent resource is represented by a resource class whose constructor receives the corresponding property shape. Nested objects in YAML (packaging modes, engines, integrations) also use type + properties; in TypeScript, these correspond to nested class constructors.

The table below shows the mapping between TypeScript classes and YAML types. This is not exhaustive — see individual resource pages for the full set of options.

TypeScript classYAML type
LambdaFunctionfunction
EdgeLambdaFunctionedge-lambda-function
WebServiceweb-service
PrivateServiceprivate-service
WorkerServiceworker-service
MultiContainerWorkloadmulti-container-workload
BatchJobbatch-job
NextjsWebnextjs-web
RelationalDatabaserelational-database
DynamoDbTabledynamo-db-table
Redisredis
MongoDbAtlasClustermongo-db-atlas-cluster
UpstashRedisupstash-redis
OpenSearchDomainopen-search-domain
HttpApiGatewayhttp-api-gateway
ApplicationLoadBalancerapplication-load-balancer
NetworkLoadBalancernetwork-load-balancer
Bucketbucket
HostingBuckethosting-bucket
EfsFilesystemefs-filesystem
SqsQueuesqs-queue
SnsTopicsns-topic
EventBusevent-bus
UserAuthPooluser-auth-pool
WebAppFirewallweb-app-firewall
Bastionbastion
StateMachinestate-machine

Configuration Files FAQ

Should I use TypeScript or YAML for my Stacktape config?

Use TypeScript for most projects. It catches configuration errors before deployment, provides full IDE support, and lets you use conditional logic and loops for per-stage differences. YAML is appropriate for very small, static projects with a fixed set of resources, or when your team strongly prefers declarative-only configuration. Both produce identical infrastructure — the choice only affects your authoring experience.

Can I switch from YAML to TypeScript?

YAML and TypeScript represent the same logical config shape: named resources with resource-specific properties. Rename your stacktape.yml to stacktape.ts and rewrite the resources using the defineConfig pattern and resource classes, keeping resource names and property values stable. Then run stacktape synth to verify the output before deploying.

Can I use JavaScript instead of TypeScript?

Yes — Stacktape accepts stacktape.js files using the same defineConfig pattern. However, you lose type checking and IDE autocompletion. TypeScript is strongly recommended. The stacktape package ships its own type definitions, so no additional @types package is needed.

How do I pass per-stage values without duplicating config?

In TypeScript, use the stage parameter from the defineConfig callback to branch conditionally (stage === 'production' ? 'db.t4g.medium' : 'db.t4g.micro'). In YAML, use the variables section combined with directives like $Stage() for stage-aware interpolation.

How do I keep secrets out of my config file?

Use the $Secret() directive to reference a Stacktape secret instead of hardcoding sensitive values like database passwords or API keys. The reference resolves securely at deploy time, so the actual value never appears in your config or version control. In TypeScript, import $Secret from the stacktape package; in YAML, use the $Secret() string syntax. See Secrets for how to create and manage secrets.

How do I validate my configuration before deploying?

In TypeScript, the type system catches most errors in your editor. For both formats, run stacktape synth to compile your configuration before deploying.

Can I use raw CloudFormation alongside Stacktape resources?

Yes. The cloudformationResources top-level field accepts raw CloudFormation resource definitions merged into the template alongside Stacktape-managed resources. This is an escape hatch for AWS services Stacktape doesn't have a built-in resource type for. See Raw CloudFormation resources for details.