A Stacktape stage is a named deployment of your project — such as dev, staging, or production. Each stage creates
a fully isolated set of AWS resources under its own CloudFormation stack. One codebase, multiple stages: develop against
cheap resources, test against a staging replica, and deploy production with full redundancy — all from the same
configuration file.
Why stages exist
Most teams need at least two separate copies of their infrastructure: one for development and one for production.
Without stages, you'd maintain parallel config files, duplicate resources manually, or rely on brittle naming
conventions. Stages solve this by making the environment a first-class parameter of your configuration. You write one
stacktape.ts, branch on the stage value where sizing, secrets, or features differ, and let Stacktape create fully
independent stacks per stage.
Because every stage produces its own CloudFormation stack with its own resources, a development deploy does not touch
production databases, functions, or storage — each stage's resources are independently provisioned. Stages can fit CI/CD workflows; for example, a team might deploy main to production and feature branches to short-lived stages.
How stages work
Stack naming
Stacktape derives the CloudFormation stack name from your project name and stage:
A project named my-api deployed to stage dev creates a stack called my-api-dev. The same project deployed to
production creates my-api-production. Each stage creates a separate CloudFormation stack with separately provisioned resources — databases, Lambda functions, queues, and storage are all independent between stages.
Stage name constraints
A stage name has at least 2 characters and contains only lowercase letters, numbers and hyphens. The project name, a hyphen and the stage form the CloudFormation stack name, which can have at most 128 characters. Examples of valid stage names: dev, staging, production, pr-42, dev-john.
Keep stage names short. The combined project name + stage forms the CloudFormation stack name and the names of AWS resources. When a resource name would be longer than AWS allows, Stacktape shortens it and adds a short hash. The stack works the same, but these names are harder to recognize in the AWS console.
Deploying a stage
Pass the --stage flag to stacktape deploy to target a specific stage.
Deploy a development stage:
Deploy production:
Each command creates (or updates) a completely separate CloudFormation stack with its own resources. Deleting a stage removes only that stage's resources — other stages are unaffected.
Production and non-production stages
Stacktape treats production stages differently in a few places: production error groups enter the incident queue, deleting a production stack needs a stronger Console permission, and security findings are rated for production. A database open to the internet, for example, is HIGH in production and LOW in a dev stage.
A stage is production when stackConfig.stageType is production. Without that setting, the type you chose when you created the stage in the Stacktape Console decides. Otherwise Stacktape decides from the stage name: prod, production, prd and live, alone, as a segment (prod-eu, client-a-prod) or followed by a number (prod2), count as production, and names with a rehearsal marker (pre-prod, prod-test, staging-live) do not. deploy reads the Console's type; a plain validate does not contact the Console and uses the config and the name. Set stageType when your production stage has another name, such as main:
Stage-aware configuration
The defineConfig callback receives a stage parameter. Use standard TypeScript logic — conditionals, lookup objects, helper functions — to vary your config per stage.
In this example, the production stage gets a larger database instance with multi-AZ redundancy, more Lambda memory, and
tighter log levels — while development stages use minimal resources to keep costs low. The $Secret directive
can reference a different secret name per stage, such as db-password-dev and db-password-production, when you
create separate secrets for those stages. See Secrets for how to create and manage secrets.
Config callback parameters
The defineConfig callback receives an object whose stage property is the stage name passed via --stage. See the configuration files page for the full defineConfig API and any other properties exposed on the callback object.
Using $Stage() in directives
When composing directive strings that need the stage value at deploy time (rather than at config-evaluation time), use
the $Stage() directive. This is mainly useful in YAML configs or when building
CloudFormation-level expressions. In TypeScript configs, you can typically use the stage parameter directly since it's
already available as a JavaScript variable.
Common patterns
Multi-tier environments
Most production teams use three tiers: dev for daily work, staging for pre-release validation, and production for
live traffic. Use a lookup object to map each stage to its resource configuration.
The fallback tiers[stage] || tiers.dev means any unrecognized stage name (like feat-xyz) inherits the dev
tier. This keeps feature branch stages cheap by default.
Feature branch stages
Create a temporary stage for any feature branch. Deploy it, test it, and delete it when the branch merges.
Deploy a feature branch stage:
Delete the stage after the branch merges:
Feature branch stages are disposable by design. Each one gets its own database, its own API endpoint, and its own resources. Keep stage names short — abbreviate branch names if needed.
Preview environments for pull requests
Stages are a good fit for per-PR preview environments. See GitOps with Console and Stacks per git branch pattern for setup details.
Conditional resources
Since defineConfig is plain TypeScript, you can conditionally include or exclude resources per stage. This is useful
for skipping expensive resources in ephemeral stages, or adding production-only safeguards like a
web application firewall.
In this example, PR preview stages skip the database entirely (the API could use an external or shared database instead), and only production gets a WAF. This pattern keeps preview stages fast to deploy and cheap to run.
Stage-specific secrets
Store separate Stacktape secrets for each stage. Use
stacktape secret set to create them, and the
$Secret directive to reference them in config.
Create separate secrets for each stage — for example, db-password-dev and db-password-production — using stacktape secret set:
Run the command once per secret. See the CLI reference for available options.
Then reference the stage-specific secret in your config using the stage parameter:
With stage === 'dev', the config passes db-password-dev to $Secret; with stage === 'production', it passes db-password-production. Never share production secrets with development stages.
See Secrets for the full guide.
Stage-specific domains
Assign different custom domains per stage to give each environment a clean URL. Production uses the apex domain; other stages use subdomains.
This produces:
| Stage | Domain |
|---|---|
production | api.example.com |
staging | staging.api.example.com |
dev | dev.api.example.com |
Custom domains are managed separately. See custom domains and stacktape domain add for setup.
Sharing resources across stages
Sometimes you want to share certain resources (like a database) across stages. Use a separate "shared infrastructure" project deployed as its own stack, then reference its outputs from other projects.
The shared infrastructure project deploys resources that other projects reference:
A consuming project references the shared stack's outputs using the $CfStackOutput directive, which resolves at CloudFormation deploy time. A $StackOutput directive is also available for resolving values locally at config-evaluation time. The referenced stack must already be deployed. Manage shared infrastructure carefully — consuming stacks depend on its outputs. See directives for details on cross-stack references.
This keeps a single database instance serving multiple services within the same stage, reducing cost in development while still allowing full isolation between stages. See directives for more about cross-stack references.
Setting defaults
If you always deploy to the same stage and region during development, use stacktape defaults set to set default values for stage and region. See the CLI reference for details.
Once configured, you can deploy without passing --stage and --region:
Override the defaults when deploying to a different stage:
Managing deployed stages
Listing stacks
Use stacktape stack list to list deployed stacks in a region. See the CLI reference for available options.
Deleting a stage
Use stacktape delete to delete a stage's stack.
Deletion removes the stage's CloudFormation stack. Other stages remain completely unaffected.
You cannot run stacktape deploy on a stage that is currently running in dev mode.
Stop dev mode first with stacktape dev stop, then deploy.
Best practices
Use consistent stage names. Pick a naming convention — dev, staging, production — and stick to it across all
projects. Consistent names simplify CI/CD pipelines and make $Secret('db-password-' + stage) patterns predictable.
Keep dev stages minimal. Use the smallest instance sizes and lowest scaling in development. The multi-tier lookup pattern shown above makes this automatic and keeps development costs low without manual intervention.
Make staging mirror production. The whole point of a staging stage is to catch issues before production. Use the same instance types, same scaling ranges, and same configuration — just with test data and lower traffic.
Separate secrets per stage. Never reuse production credentials in development. Stage-interpolated secret names
(db-password-dev, db-password-production) enforce this by convention.
Delete ephemeral stages promptly. Feature branch and PR preview stages accumulate if not cleaned up. See
GitOps with Console and Stacks per git branch pattern for setting up preview-stage workflows, or manually run
stacktape delete.
Add safeguards in production. Enable multi-AZ for databases, add a web application firewall, configure alarms, and set budgets. Use conditional resource inclusion to add these only in production.
Stages and Environments FAQ
How do I access the stage name in my config?
The defineConfig callback receives an object with a stage property. Use standard TypeScript logic to branch on the stage value — ternary operators, lookup objects, or if statements all work. In directive strings that need the stage at CloudFormation deploy time, use the $Stage() directive.
Can I include resources only in certain stages?
Yes. Since defineConfig returns a plain JavaScript object, you can conditionally add keys to the resources object using if statements or any other control flow. Resources not included in the returned object are simply not created for that stage. This is commonly used to skip databases in preview stages or add WAFs only in production.
Are stages fully isolated from each other?
Each stage creates its own CloudFormation stack with its own AWS resources — separate databases, separate Lambda functions, separate S3 buckets, and so on. Stacktape provisions each stage's resources independently and does not share data between stages unless you explicitly configure it (e.g., by referencing another stack's outputs via the $StackOutput directive). Deploying or deleting one stage has no effect on other stages.
What happens when I deploy to an existing stage?
Deploying to an existing stage updates that stage's CloudFormation stack rather than creating a new one. CloudFormation computes the diff between the current and desired state and applies only the changes needed. Deleting a stage removes only that stage's stack — other stages are unaffected.
Can different stages use different AWS regions?
Yes. The region is a separate parameter from the stage, so you can deploy dev to eu-west-1 and production to us-east-1. The stack name is derived from {projectName}-{stage}, and region-scoped resources (like secrets and ACM certificates) must exist in the target region. Create stage-appropriate secrets in each region you deploy to.
How do I keep development costs low across stages?
Vary resource sizing by stage. Branch on the stage parameter to give dev and preview stages the smallest instance sizes and lowest scaling, while production gets larger instances and multi-AZ — the multi-tier lookup pattern shown above makes this automatic. You can also conditionally skip expensive resources (like a database) in ephemeral pr-* stages, or have several services in the same stage share one database via the $CfStackOutput directive.