Hooks

Introduction

Hooks allow you to execute a custom command or script before specified command, after specified command or when a specified command fails.
Example use cases:
- build, validate or lint your application before deployment
- execute database migration after deployment
- send a notification to a Slack channel after a deployment error

Defining script to execute

The script is defined by its name. It must be specified in the scripts section of the configuration file.
Refer to scripts docs to learn how to define the script.
The script will additionally get the following environment variables:
- STP_HOOK_TYPE - before, after or onError
- STP_COMMAND - Stacktape command used

Copy
hooks:
  - triggers: ["before:deploy"]
    scriptName: buildWeb

scripts:
  buildWeb:
    executeCommand: npx gatsby build

Hookable events

before:command hooks

Executed before the command, but AFTER the configuration has been successfully loaded.
Must have the format before:[command].

Executed only if the configuration was successfully loaded and hooks have been registered. The hook won't be executed if there's an error with your CLI arguments or in your configuration.

after:command hooks

Executed after the command has successfully finished.
For convenience, after:deploy hook can reference parameters of your stack resources in its environment variables (using $ResourceParam() and $CfResourceParam() directives).

onError:command hooks

Executed if the command has failed.
onError hooks additionaly get the following environment variables STP_ERROR containing data about the error:
- message: human-readable message
- errorType: type of the error
- hints: (for expected errors only) - list of hints that might help you solve the error.
- errorId: (for unexpected errors only) - you can use this error id to report an issue

Executed only if the configuration was successfully loaded and hooks have been registered. The hook won't be executed if there's an error with your CLI arguments or in your configuration.

API reference

LifecycleHook API reference

triggers

Required

List of events that will trigger this hook

Type: Array of string ENUM

Possible values: after:bucket:syncafter:compile-templateafter:cw:deploy-fastafter:cw:run-localafter:deleteafter:deployafter:fn:deploy-fastafter:fn:developafter:logsafter:package-workloadsafter:preview-changesafter:rollbackafter:stack-infoafter:userpool-create-userafter:userpool-get-tokenbefore:bucket:syncbefore:compile-templatebefore:cw:deploy-fastbefore:cw:run-localbefore:deletebefore:deploybefore:fn:deploy-fastbefore:fn:developbefore:logsbefore:package-workloadsbefore:preview-changesbefore:rollbackbefore:stack-infobefore:userpool-create-userbefore:userpool-get-tokenonError:bucket:synconError:compile-templateonError:cw:deploy-fastonError:cw:run-localonError:deleteonError:deployonError:fn:deploy-fastonError:fn:developonError:logsonError:package-workloadsonError:preview-changesonError:rollbackonError:stack-infoonError:userpool-create-useronError:userpool-get-token

Format is {before or after}:{stacktape command}.
Example: before:deploy

scriptName

Required

Name of the script to execute

Type: string

The specified script must be defined in the scripts section.