A stacktape.ts file defines your AWS infrastructure — APIs, functions, databases, containers — using typed TypeScript classes. Stacktape reads this file when you deploy, run dev mode, or manage resources, and creates the corresponding AWS resources in your account. Create one from scratch, bootstrap from a starter, or let stacktape init analyze your repository.
stacktape init in your repository. It reads the code and proposes the infrastructure, or starts a new project from a starter template. Either way, understanding the config format below will help you customize what you get.Install the package
Install the stacktape package for typed resource classes and directives such as $Secret and $ResourceParam. You get full IDE autocompletion and type checking as you write your config.
Your first stacktape.ts
Create a stacktape.ts file in your project root. This example deploys a Lambda function behind an HTTP API Gateway — a common starting point for REST APIs:
Here's what each piece does:
defineConfigwraps your config in a function Stacktape calls at command time. It provides a context object with deployment details — stage, region, project name — you can use for dynamic configuration.- Resource classes like
LambdaFunctionandHttpApiGatewaydefine Stacktape resources. Stacktape creates and manages the corresponding AWS infrastructure. Each class accepts a typed configuration object with autocompletion in VS Code, WebStorm, and other TypeScript-capable editors. JsBundleLambdaPackagingtells Stacktape to bundle the Lambda from a JavaScript or TypeScript entry file. See JS Bundle for Lambda for details.HttpApiIntegrationroutes HTTP requests through the API Gateway to the function. ThehttpApiGatewayNamevalue ('api') points the function at theapigateway created above.- The returned
resourcesobject is required. The object keys name the resources thatconnectTouses to wire up access between resources and that$ResourceParam()uses to reference outputs from other resources.
The handler at ./src/handler.ts is standard application code:
Adapt config per stage
The defineConfig callback receives a context object you can use to vary infrastructure per stage. Since the config is TypeScript, conditionals, loops, shared modules, and any npm package work naturally. This example adds a relational database and connects it to a Lambda function, using the stage parameter to vary the database instance size between production and development:
In this example, connectTo: ['database'] grants apiHandler network access to the resource named database and injects connection details as environment variables — Stacktape injects names like STP_DATABASE_CONNECTION_STRING and STP_DATABASE_HOST. See connecting resources for the variables injected per resource type.
The stage parameter lets you write standard TypeScript conditionals to vary any property per stage. Use the $Secret directive for credentials like masterUserPassword to keep secrets out of your config file.
Context properties
The context object passed to the defineConfig callback includes:
| Property | Type | Description |
|---|---|---|
stage | string | Current stage name (e.g., dev, production) |
region | string | AWS region (e.g., us-east-1, eu-west-1) |
projectName | string | Project name, always set when the config declares it (project settings) |
command | string | CLI command being run (deploy, delete, dev, etc.) |
cliArgs | Readonly<Record<string, unknown>> | Options of the current command, such as stage or configPath |
The defineConfig callback reference lists every context property and explains how command-line options and your own values reach the config.
Quick-start with stacktape init
stacktape init reads an existing repository and writes a config for it, after you review the
proposed infrastructure in its wizard. In an empty directory, it starts a new project from a starter template:
This is the fastest path from zero to a working project. Keep the config it writes in version control, so infrastructure changes are reviewed with code changes.
Beyond resources
The resources section is the only required part of a Stacktape config, but several optional sections are available as your project grows: hooks for running scripts automatically before or after deploy, delete, dev, or bucket sync operations; scripts for runnable tasks like database migrations (three types: local-script, local-script-with-bastion-tunneling, and bastion-script); variables for reusable values; directives for custom deploy-time logic; and deployment settings for rollback behavior and termination protection. See configuration files for the complete reference.
Next step
You have a config that defines what to deploy. Next, use dev mode to iterate locally — edit your code and see changes without waiting for full deployments.