Introduction

Catalyst provides the functionality for automating CLI and terminal command executions during the testing or deployment process in the form of scripts. You can define Catalyst scripts in the catalyst.json file of your Catalyst project directory.

Scripting enables abstraction of the details of processes behind a task runner. This helps you prevent performing iterative tasks manually, and automates the logic that needs to be executed during various stages of the testing or deployment process.

Catalyst supports two kinds of scripts: 

1. Lifecycle Scripts: Scripts that are executed during various lifecycle events 
2. Custom Scripts: Scripts that you can define to be executed when you need 

You can also run a script manually and test it whenever you require, using the CLI.

Lifecycle and Custom Scripts

Before you learn about writing a script, let's discuss the two types of scripts supported in Catalyst.

Catalyst supports the following lifecycle scripts:

1. preserve: The script is run automatically before the catalyst serve command is executed.
2. postserve: The script is run automatically after the catalyst serve command is executed.
3. predeploy: The script is run automatically before the catalyst deploy command is executed.
4. postdeploy: The script is run automatically after the catalyst deploy command is executed.

You can set custom scripts to automatically execute any time you need them to, in the order that you need, by calling them inside the lifecycle scripts. 

Write a Script

You can define and execute scripts for the client and the functions of your project. You can execute Catalyst CLI commands and terminal commands of your local environment through scripts.

You must write the scripts in the scripts field of the functions or client scope in the catalyst.json file present in the root of your project directory. This file contains the configuration and target information of your project directory components. A sample code structure of the catalyst.json configuration file is shown below. 

Sample Script

Let's discuss the script shown in the picture above. The code of this catalyst.json file defines two lifecycle scripts and two custom scripts. The execution of the lifecycle scripts will run the custom scripts. The scripts here are included inside the client's scope, because they are defined for the client component of the project. 

The code is given below:

	{
  "functions": {
    "targets": [
      "catly"
    ],
    "ignore": [],
    "source": "functions"
  },
  "client": {
    "source": "client/app/build",
    "ignore": [],
    "scripts": {
      "packageJson": "cd client && cp client-package.json app/build/",
      "build": "cd client/app && yarn install && yarn build",
      "preserve": "catalyst run client:build && catalyst run client:packageJson",
      "predeploy": "catalyst run client:build && catalyst run client:packageJson"
    }
  }
}

When you execute a custom script inside a lifecycle script using the catalyst run command as shown in the example above, you must specify the component it is being executed for. This is necessary if, for example, there is a cd (change directory) terminal command to be executed. The root of that component's directory will be considered as the directory the change directory command is executed from.

The logic flow of the scripts written above is as follows:

1. When you execute the catalyst serve or catalyst deploy command for the client component, the preserve or predeploy scripts are initiated respectively, before running the command.
2. Both the preserve and predeploy scripts contain the same command executions. The first action is the catalyst run client:build command, which executes the build custom script for the client component. The second action is the catalyst run client:packageJson, which executes the packageJson script for the client component.
3. The build custom script performs the following actions in sequence:
   • The terminal is navigated to the client/app directory.
   • The yarn install command is executed to install Node.js dependencies using the Yarn package manager.
   • The yarn build command is executed to build the client application.
4. The packageJson custom script performs the following actions one after the other:
   • The terminal is navigated to the client directory.
   • The client-package.json file is copied from the client directory and is pasted to the app/build directory. 

After these scripts are executed, the components are served or deployed.

Run a Script

You can also manually run a script whenever you need using the CLI, to test its execution.

You can list the scripts available in the project directory by navigating to the directory and executing either of the following CLI commands:

$ catalyst run-script | run

The CLI will display the lifecycle and custom scripts that are configured and available for each component in the catalyst.json file.

You can directly run a script by executing the run command with the script's name as shown below: 

$ catalyst run-script | run [command]

For example, to run the custom script packageJson, execute the following command from the project directory:

$ catalyst run client:packageJson

This will execute the packageJson script defined in the example.