Stacktape hooks and scripts automate tasks around your deployment lifecycle — compiling assets before deploy, running database migrations after deploy, exporting data before deletion. Scripts are reusable commands defined in your config; hooks wire them to lifecycle events so they run automatically.
Scripts
A Stacktape script is a named task in the scripts section of your config. Scripts can run shell commands or JS/TS/Python files. Use connectTo to auto-inject resource connection details as environment variables. Run scripts manually with stacktape script run or attach them to hooks for automatic execution.
Stacktape supports three script types, each suited to different execution and network requirements:
| Type | Runs on | Best for |
|---|---|---|
local-script | Your machine or CI runner | Builds, migrations using local tools, seeding, linting |
local-script-with-bastion-tunneling | Your machine, tunneled through a bastion host | Running local tools against private VPC resources (databases, Redis) |
bastion-script | The bastion EC2 instance in your VPC | Direct VPC network access without local tool requirements |
local-script is the right default for most tasks. Use bastion tunneling when your resources have no public endpoint and you need local CLI tools like prisma or psql. Use bastion scripts when you need direct VPC access and only need basic shell commands.
Local script
A local script runs wherever the Stacktape CLI runs — your laptop during development, or the CI runner in a pipeline. This is the most common script type, covering builds, database migrations, linting, and data seeding.
Scripts can run shell commands or JS/TS/Python files. The examples below use executeCommand; see the configuration reference for the full set of execution properties.
The seedBucket script uses connectTo to receive the same bucket connection details as the api function — injected as environment variables like STP_UPLOADS_NAME. See connecting resources for the full list of variables injected per resource type. The buildFrontend script runs in a subdirectory using cwd. A local script's stdioMode controls its terminal: capture (the default) shows its output in Stacktape's progress output, inherit hands it the terminal, including input, for interactive programs, and ignore discards its output. In captured output and in a failed script's error, Stacktape replaces the secret values it injected into the script, from $Secret, $SsmParam or the secret parameters of connectTo resources, with [redacted].
Local script with bastion tunneling
When your database or Redis cache has no public endpoint, local-script-with-bastion-tunneling runs locally and tunnels connections to VPC-only resources through a bastion host. This lets you keep using local CLI tools (Prisma, psql, redis-cli) against resources that aren't publicly reachable.
Stacktape runs the script locally while routing network traffic to connected resources through the bastion host.
Bastion script
A bastion script runs directly on the bastion EC2 instance inside your VPC, with output streaming back to your terminal in real-time. Use this when you need direct network access to VPC resources without running any tools locally.
A bastion script runs on the bastion host inside your VPC. If your command needs extra tools, make sure they are available on that host (as shown above with yum install) or use local-script-with-bastion-tunneling to keep using your local toolchain.
Running scripts manually
Run any defined script with stacktape script run:
See the script run CLI reference for the complete command options.
Hooks
Hooks attach scripts to deployment lifecycle events so they run automatically. Define hooks in the top-level hooks section by referencing one or more script names from your scripts section.
The buildFrontend script runs before every deployment, compiling the frontend into ./frontend/dist where the hosting bucket picks it up. The openDocs script opens the deployed URL after deploy but skips in CI environments (using skipOnCI). Note: the open command is macOS-specific — replace with xdg-open on Linux or start on Windows.
To run database migrations, use a release command rather than a hook: it runs inside the VPC before any workload gets the new code, and a failure stops the deploy. An afterDeploy hook runs after the new code is live, so its failure fails the command but does not undo the deployment.
Lifecycle events
Hooks correspond to the before and after phases of the deploy, delete, dev, and bucket sync commands:
| Hook | When it fires | Common use |
|---|---|---|
beforeDeploy | Before deployment starts | Builds, linting, tests, asset preparation |
afterDeploy | After deployment completes | Seeding, cache warming, notifications |
beforeDelete | Before stack deletion | Data exports, backups |
afterDelete | After stack deletion | External cleanup, notifications |
beforeBucketSync | Before syncing bucket contents | Pre-processing assets |
afterBucketSync | After syncing bucket contents | Cache invalidation, notifications |
beforeDev | Before dev mode starts | Dependency installation, local setup |
afterDev | After dev mode exits | Cleanup |
Delete hook behavior depends on how the delete command is invoked. See the delete CLI reference for details.
When a hook fails
A failed hook stops the command with an error, and the hooks listed after it don't run. A beforeDeploy failure therefore stops the deploy before anything changes.
An afterDeploy hook runs after the deployment finished. When it fails, the stack stays deployed on the new version and nothing is rolled back, but stacktape deploy exits with an error, so a CI job fails. Fix the problem and run the script again with stacktape script run.
In the Console, Slack and email, the deploy is still reported as succeeded, because the new version is live. Everyone who is notified about failed deploys also gets a "Deployed, but a hook failed" message that names the hook.
Set onFailure: continue on a hook whose failure should not fail the command, such as a notification. The failure is then printed as a warning:
A hook cannot roll a deployment back. To keep the old version when a check fails, run the check where it can stop the rollout: a release command runs before any workload gets the new code, and a deployment script with deploymentConfig.autoRollback: true rolls back the infrastructure changes of its deploy.
Conditional execution
Hook entries can use skipOnCI and skipOnLocal to control where they run.
skipOnCI: true— skips the hook in CI/CD environments such as GitHub Actions or GitLab CI. Useful for interactive or local-only actions like opening a browser.skipOnLocal: true— skips the hook when running locally; runs only in CI/CD. Useful for CI-only tasks like uploading test reports or sending notifications.
The hooks example above demonstrates skipOnCI — the openDocs script runs locally after deploy but is skipped in CI pipelines.
Environment variables in scripts
Scripts commonly receive environment variables from connectTo and environment, configured inside the script's properties.
connectTo auto-injects connection details for each listed resource as environment variables. The exact variables depend on the resource type — see connecting resources for the full per-resource injection table.
environment lets you define additional variables explicitly. Values support directives like $Secret(), $ResourceParam(), and $Var(), so you can inject secrets and computed values at execution time.
assumeRoleOfResource injects temporary AWS credentials matching the IAM role of a deployed resource, granting the script the same permissions as that resource. The resource must be deployed before the script runs. Most AWS SDKs and CLIs automatically pick up the injected credentials.
Deployment scripts
Deployment scripts are a separate Stacktape resource that runs as an AWS Lambda function in your stack, rather than on your local machine. Consider deployment scripts when you need cloud-based execution independent of the developer's machine. See the deployment script resource page for VPC and networking behavior. For most tasks — builds, migrations with local tools, seeding — hooks with local scripts are simpler and more flexible.
Hooks and Scripts FAQ
How do I run a database migration on deploy?
Set releaseCommand on a container service, a function or a server-rendered site. It runs inside the VPC before any workload gets the new code. On a function or site it builds an image of the project, which needs Docker on the machine that deploys.
Without Docker, define a local-script that runs your migration tool and use connectTo to inject the database connection details as environment variables — see connecting resources for the variable names. Attach the script to the afterDeploy hook so it runs automatically. If your database has no public endpoint, use local-script-with-bastion-tunneling instead.
Can I run multiple scripts in a single hook?
Yes. Each hook (beforeDeploy, afterDeploy, etc.) accepts an array of script references. Define them in the execution order you need — for example, run tests before building.
What happens if my afterDeploy hook fails?
The stack stays deployed on the new version, and stacktape deploy exits with an error, so a CI job fails. Hooks listed after the failed one don't run. Fix the problem and run the script again with stacktape script run. To let a hook fail without failing the deploy, set onFailure: continue on it. See When a hook fails.
When should I use hooks vs deployment scripts?
Use hooks with local scripts when you need local tooling (npm, Prisma CLI, psql), filesystem access, or flexibility in execution time. Use deployment scripts when you need direct VPC access without bastion setup, or when you want consistent cloud execution independent of the developer's machine. Most teams use hooks for the majority of their automation.
How do I run a script against a private (VPC-only) database?
Use local-script-with-bastion-tunneling when you need local tools like prisma or psql — it runs the script on your machine while routing connections through a bastion host (you need a bastion resource in your config). Use bastion-script instead when you only need basic shell commands and want to avoid running anything locally. For most workflows, bastion tunneling is the better choice.