Hooks allow you to execute a custom command or script before or after a specified Stacktape command.
Example use cases:
- Building, validating, or linting your application before deployment.
- Running unit tests before deployment.
- Executing database migrations after deployment.
- Cleaning up a database before deletion.
How to use hooks
You can reference scripts defined in the scripts section of your stacktape.yml file within
a hook. Scripts can also be executed manually. For more information, see the
scripts documentation.
When a script is executed, it receives the following environment variables:
STP_HOOK_TYPE:beforeorafterSTP_COMMAND: The Stacktape command that was used
These are in addition to the environment variables specified in the script definition and those injected when using
connectTo.
NamedScriptLifecycleHookAPI referenceParent:HooksscriptNameRequired
Script Name
Type: string
The name of the script to execute. The script must be defined in the scripts section of your configuration.
skipOnCI
Skip this hook in CI/CD environments (CodeBuild, GitHub Actions, GitLab CI).
Type: boolean
Useful for hooks that only make sense locally (e.g., opening a browser, interactive prompts).
skipOnLocal
Skip this hook when running locally; only run in CI/CD.
Type: boolean
Useful for CI-only tasks (e.g., uploading test reports, notifying Slack).
Hookable events
HooksAPI referencebeforeDeploy
Scripts to run before deploying. Common use: build frontend, lint code.
Type: Array of NamedScriptLifecycleHook
afterDeploy
Scripts to run after deploying. Common use: run database migrations, seed data.
Type: Array of NamedScriptLifecycleHook
beforeDelete
Scripts to run before deleting the stack. Common use: export data, clean up external resources.
Type: Array of NamedScriptLifecycleHook
Only runs when --configPath and --stage are provided to the delete command.
afterDelete
Scripts to run after deleting the stack.
Type: Array of NamedScriptLifecycleHook
Only runs when --configPath and --stage are provided to the delete command.
beforeBucketSync
Scripts to run before syncing bucket contents.
Type: Array of NamedScriptLifecycleHook
afterBucketSync
Scripts to run after syncing bucket contents.
Type: Array of NamedScriptLifecycleHook
beforeDev
Scripts to run before starting dev mode.
Type: Array of NamedScriptLifecycleHook
afterDev
Scripts to run after dev mode exits.
Type: Array of NamedScriptLifecycleHook
Before-command hooks
These hooks are executed before the specified command, but after the configuration has been successfully loaded.
A before-command hook is only executed if the configuration is loaded successfully and the hooks are registered. The hook will not be executed if there is an error in your CLI arguments or in your configuration file.
After-command hooks
These hooks are executed after the specified command has finished successfully. Common use cases for after-command hooks include database migration or seeding, and API or endpoint testing.