Development mode lets you run your application locally while connected to real (or emulated) cloud resources. This gives you fast iteration without deploying on every change.
How It Works
When you run stacktape dev:
- Databases run locally in Docker containers (Postgres, MySQL, Redis, DynamoDB)
- Lambda functions run locally with hot-reload, but can still be triggered via deployed API Gateway
- Container workloads run locally with live reload
- Frontend apps (Next.js, hosting buckets) run their dev servers locally
All resources receive the correct environment variables and can communicate with each other just like in production.
Quick Start
Resource Selection
When you run stacktape dev without arguments, you'll see an interactive picker:
Select the resources you want to run locally using spacebar, then press Enter.
Local Database Emulation
Stacktape automatically spins up Docker containers for your databases:
| Resource Type | Local Emulation |
|---|---|
relational-database (Postgres) | PostgreSQL in Docker |
relational-database (MySQL) | MySQL in Docker |
redis-cluster | Redis in Docker |
dynamo-db-table | DynamoDB Local in Docker |
Make sure Docker is running before starting dev mode. Stacktape will pull the necessary images automatically.
Database Connection
Your application receives the same environment variables it would in production:
In dev mode, these point to localhost with the emulated database.
Lambda Function Development
Lambda functions run locally with hot-reload:
- Your function code is watched for changes
- On change, the function is rebuilt automatically
- The next invocation uses the updated code
Triggering Functions
Functions connected to an HTTP API Gateway can be triggered through:
- The deployed API Gateway URL (requests are tunneled to your local function)
- Direct local invocation
Tunneling
By default, Stacktape creates a tunnel so that deployed API Gateways can invoke your local Lambda functions. This is useful for:
- Testing webhooks locally
- Debugging production-like request flows
- Sharing your local dev environment
Disable tunneling if not needed:
Container Workload Development
Container-based resources (web-service, worker-service, multi-container-workload) run locally using Docker:
- Your container is built and started
- File changes trigger a rebuild
- Environment variables are injected automatically
The container runs with the same configuration as it would on AWS ECS.
Frontend Development
Next.js
Next.js apps run their standard dev server:
Environment variables from your Stacktape config are injected, including references to other resources.
Hosting Buckets (Static Sites)
Static sites with a dev configuration run their specified dev command:
Dev Mode Commands
While dev mode is running, you can use keyboard commands:
| Command | Action |
|---|---|
rs | Rebuild all workloads |
rs <name> | Rebuild specific workload |
c or clear | Clear logs |
q or quit | Exit dev mode |
Dev vs Legacy Mode
Stacktape dev has two modes:
Normal Mode (Default)
- Creates a minimal "dev stack" with only necessary cloud resources
- Databases run locally in Docker
- Lambda functions connect to local databases via tunnels
- Fastest iteration, lowest AWS costs
Legacy Mode
- Requires an already-deployed production stack
- All resources run on AWS (no local emulation)
- Lambda functions deploy to AWS on each change
- Useful when you need real AWS resources
Example Workflow
A typical development workflow:
Troubleshooting
"Docker is not running"
Dev mode requires Docker for local database emulation. Start Docker Desktop and try again.
"Port already in use"
Another process is using the required port. Either stop that process or Stacktape will automatically try alternative ports.
"Tunnel connection failed"
The tunnel to your local machine couldn't be established. Check your firewall settings or use --noTunnel if you don't need external access.