Resources

A Stacktape resource is a named piece of infrastructure — an API, a database, a container service, a queue — that Stacktape provisions and manages in your AWS account. You define resources in the resources object of your configuration, and Stacktape handles the underlying AWS setup: CloudFormation resources, IAM permissions, networking, and environment variable injection.

Why resources exist

AWS has hundreds of services, each with dozens of configuration knobs. Stacktape resources are opinionated abstractions that bundle the AWS primitives you need into a single declaration. A web service runs a container workload using Fargate by default (with EC2 available through the container resources configuration) — you declare the container, scaling, and networking in one block without manually configuring task definitions, target groups, or IAM roles.

You stay in control of the underlying AWS resources through overrides, but you don't need to think about them until you have an edge case that the abstraction doesn't expose directly.

Defining resources

Resources live in the resources object returned from defineConfig. Each key becomes the resource's name — used in connectTo environment variable prefixes (e.g., STP_MY_API_ARN) and in resource references like $ResourceParam('myApi', 'url').

export default defineConfig(() => {
  const uploads = new Bucket({});

  const orderQueue = new SqsQueue({});

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

  return {
    resources: { uploads, orderQueue, api }
  };
});

The resource name you choose matters:

  • It determines the prefix for injected environment variables (e.g., a resource named uploads produces STP_UPLOADS_NAME, STP_UPLOADS_ARN).
  • It's used in $ResourceParam('uploads', 'arn') references across your config.
  • Changing a resource name affects every reference to it — $ResourceParam lookups, connectTo listings, and injected environment variable prefixes.

Pick short, descriptive, camelCase names. Resource names must be alphanumeric — letters and numbers only (matching /^[a-z0-9]+$/i). Hyphens, underscores, and special characters are not allowed. Stacktape validates this at deploy time and rejects invalid names.

Resource categories

Stacktape groups resources by purpose. Each category maps to a set of AWS services underneath.

CategoryResourcesAWS services
ComputeLambda function, web service, private service, worker service, multi-container workload, batch job, edge functionLambda, ECS Fargate/EC2, AWS Batch, Lambda@Edge
FrontendStatic hosting, Next.js, Astro, Nuxt, SvelteKit, SolidStart, TanStack Start, RemixS3, CloudFront, Lambda
DatabasesRelational database, Aurora DSQL, DynamoDB, Redis, MongoDB Atlas, Upstash Redis, OpenSearchRDS, Aurora, Aurora DSQL, DynamoDB, ElastiCache, OpenSearch Service
StorageS3 bucket, EFS filesystemS3, EFS
NetworkingHTTP API Gateway, WebSocket API Gateway, AppSync API, Application Load Balancer, Network Load Balancer, CDN, custom domainsAPI Gateway, AppSync, ALB, NLB, CloudFront, Route 53, ACM
MessagingEvent bus, SQS queue, SNS topic, Kinesis stream, Kafka cluster, Email senderEventBridge, SQS, SNS, Kinesis, MSK Serverless, SES
OrchestrationState machineStep Functions
SecurityUser auth pool, Web application firewall, Bastion hostCognito, WAF, EC2 (bastion)
AdvancedCustom resources, deployment scripts, CDK constructs, raw CloudFormationAny AWS resource

Connecting resources

Most applications need resources to talk to each other — a Lambda function querying a database, a container writing to a bucket. Stacktape handles this through the connectTo property, which automatically:

  • Grants the correct IAM permissions (read/write to S3, CRUD on DynamoDB, invoke on Lambda).
  • Opens security group rules for VPC-protected resources like relational databases and Redis.
  • Injects environment variables with connection details in the STP_[RESOURCE_NAME]_[PARAM] format.
export default defineConfig(() => {
  const invoiceBucket = new Bucket({});

  const processOrder = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/process-order.ts'
    }),
    connectTo: [invoiceBucket]
  });

  return {
    resources: { invoiceBucket, processOrder }
  };
});

In this example, the processOrder function receives STP_INVOICE_BUCKET_NAME and STP_INVOICE_BUCKET_ARN as environment variables automatically. No manual IAM policies or security group rules needed.

In the TypeScript defineConfig style, pass the resource variables directly in the connectTo array ([invoiceBucket], not ['invoiceBucket']). Stacktape resolves these to the underlying resource names automatically. In YAML config, connectTo accepts an array of resource name strings. Common workload resource types inject variables such as:

Resource typeInjected variables
BucketNAME, ARN
DynamoDbTableNAME, ARN, STREAM_ARN
RelationalDatabaseCONNECTION_STRING, JDBC_CONNECTION_STRING, HOST, PORT (Aurora also adds READER_CONNECTION_STRING, READER_JDBC_CONNECTION_STRING, READER_HOST)
RedisHOST, READER_HOST, PORT
MongoDbAtlasClusterCONNECTION_STRING
UpstashRedisHOST, PORT, PASSWORD, REST_TOKEN, REST_URL, REDIS_URL
SqsQueueARN, NAME, URL
SnsTopicARN, NAME
EventBusARN
FunctionARN
UserAuthPoolID, CLIENT_ID, ARN
BatchJobJOB_DEFINITION_ARN, STATE_MACHINE_ARN
PrivateServiceADDRESS
WebServiceURL
EmailSenderIDENTITY, IDENTITY_ARN, REGION, CONFIGURATION_SET_NAME, FEEDBACK_TOPIC_ARN
KafkaClusterARN, NAME, BOOTSTRAP_SERVERS

All variable names follow the pattern STP_[RESOURCE_NAME]_[PARAM]. For the full per-resource reference, see Connecting resources.

Use the native Email sender resource for SES. It verifies or reuses the identity, injects the sending values, and scopes permissions to that exact identity and configuration set.

Resource references with directives

Beyond connectTo, you can reference any resource's parameters anywhere in your config using the $ResourceParam directive. This is useful for wiring values that connectTo doesn't cover — like passing a queue URL to a Step Functions state machine definition or embedding a bucket name in a custom environment variable.

export default defineConfig(() => {
  const orderQueue = new SqsQueue({});

  const worker = new LambdaFunction({
    packaging: new JsBundleLambdaPackaging({
      entryfilePath: './src/worker.ts'
    }),
    environment: { QUEUE_URL: "$ResourceParam('orderQueue', 'url')" }
  });

  return {
    resources: { orderQueue, worker }
  };
});

The environment property accepts an array of { name, value } objects. Use $ResourceParam inside the value to reference any parameter from another resource.

See Directives for all built-in directives and Referenceable parameters for the full list of parameters each resource exposes.

How resources map to AWS

Each Stacktape resource produces one or more CloudFormation resources. When you run stacktape deploy, Stacktape resolves your configuration (variables, directives, secrets), translates each resource into CloudFormation definitions with the necessary IAM roles and security groups, and submits the resulting template to AWS for provisioning.

You can inspect the generated template with stacktape synth before deploying. After deploying, use stacktape status to see deployed resource details.

Stacktape automatically adds projectName, stage, and stackName tags to every AWS resource in your stack. Custom tags defined in stackConfig.tags are merged on top — useful for cost tracking and access control in AWS Cost Explorer. Tag names starting with stp: are reserved for Stacktape's own tags, and a config that uses one fails validation.

Overrides

Most Stacktape resources expose an overrides property that lets you modify the underlying CloudFormation resources directly. This is the escape hatch for edge cases where Stacktape's abstraction doesn't expose a specific AWS property you need. A few resource types that don't map to CloudFormation (such as MongoDB Atlas clusters) do not support overrides.

Overrides use dot-notation paths to target specific CloudFormation properties on child resources. You can find resource logical IDs with stacktape status.

For full details, see Overrides and escape hatches.

The stack as a unit

All resources defined in one configuration file deploy together as a single CloudFormation stack. This means:

  • They share a lifecycle — deploy, update, and delete together.
  • By default, Stacktape creates a VPC for stacks that need VPC networking. You can share or reuse a VPC across stacks with stackConfig.vpc.reuseVpc.
  • Cross-resource references resolve at deploy time.
  • A failed deployment keeps what it created or updated, and the next deployment continues from the failure. With deploymentConfig.autoRollback, it rolls back all changes instead.

One stack per stage is the standard pattern. A typical project has a dev stage for development and a production stage for live traffic — same config, different stages, separate AWS resources.

Resources vs cloudformationResources

The resources section uses Stacktape's typed abstractions — you get IntelliSense, automatic IAM wiring, connectTo integration, and managed lifecycle. The cloudformationResources section accepts raw CloudFormation resource definitions for anything Stacktape doesn't abstract.

Raw CloudFormation resources don't participate in connectTo. If you need to expose values from raw resources to other stacks, define a stackConfig.outputs entry with export: true and reference it from another stack with the $CfStackOutput() directive.

Renaming a resource in your config is a destructive operation for stateful resources. If you rename a database resource from ordersDb to mainDatabase, CloudFormation interprets this as "delete ordersDb, create mainDatabase" — losing all data. Use deploymentConfig.terminationProtection to guard against accidental stack deletion, and CloudFormation stack policies via overrides to prevent replacement of specific resources.

Resources FAQ

How many resources can I put in one stack, and when should I split?

Each Stacktape resource produces multiple CloudFormation resources underneath (IAM roles, security groups, log groups, etc.), so there is a practical ceiling on how many fit in one stack. A typical web application (API + database + queue + bucket) stays well within limits, so start with one stack per service boundary. Split into separate projects when you hit CloudFormation limits, when teams need independent deploy cycles, or when blast-radius concerns justify isolation.

Do resources cost money when idle?

It depends on the resource type. Serverless resources like Lambda functions and DynamoDB tables (on-demand mode) follow a pay-per-request model. Container-based services (web service, private service, worker service) run continuously and incur charges based on allocated CPU and memory. Relational databases and Redis caches charge while the instance is running. Check each resource's dedicated page for pricing details specific to that resource type.

Can I reference resources across different stacks?

Yes. Use stackConfig.outputs with export: true to expose values from one stack, then reference them from another stack using the $CfStackOutput directive. This pattern is common for shared infrastructure like VPCs or databases used by multiple services.

Can I use AWS services that Stacktape doesn't have a built-in resource for?

Yes. Use raw CloudFormation resources via the cloudformationResources section, or embed CDK constructs for higher-level abstractions. Both approaches let you add any AWS resource while keeping it in the same stack and deployment lifecycle.

How does Stacktape handle VPC networking?

Stacktape creates a VPC automatically when your stack includes resources that need private networking, such as relational databases and Redis caches. Resources that don't need VPC access (Lambda functions, DynamoDB, S3 buckets) work without one. You can share or reuse a VPC across stacks with stackConfig.vpc.reuseVpc.