Configuring Project Scripts for Users

Note:
This article focuses on configuring scripts to run in Codux. For information on running scripts in Codux, refer here.
Scripts run for a wide range of reasons, and are often necessary as part of a workflow. Codux makes it easy for all users to run scripts on demand, whenever needed through the Scripts panel on the left of the screen. All you have to do is to configure the scripts configuration key!

scripts 

  • Description: Configures scripts for project users to run from Codux or to run automatically through triggered actions.
  • Type: Object {}
Each object within this key corresponds to a script that can be executed through the Codux user interface. Users simply need to choose a configured script, and the interface will display a dialog for running it. You can also create triggers to launch the run dialog when certain events take place, like when the user first opens the project after cloning, pulls changes, and so on.
Scripts panel, listing Configured and Package JSON script titles and descriptions.
In the image above, there are two lists of scripts:
  • Configured Scripts: The subject of this article, configured in codux.config.json.
  • Package JSON Scripts: These are generated automatically in the package.json file located in the root directly that Codux is running on, and don't need configuring on codux.config.json.

Add a script 

To add a script for project users, create an object in the scripts configuration object like this:
1
2
3
4
5
6
7
8
9
{  
    "$schema": "https://wixplosives.github.io/codux-config-schema/codux.config.schema.json",
    "scripts": {
        "install": {
            "title": "Install",
            "description": "Run install",
            "command": "npm i",
        },
        …
}
Every configured script in codux.config.json may have the following properties:
  • title (string): An optional, but recommended parameter to give the script a title in the UI. The title shows in the left panel and in the script dialog window.
  • description (string): An optional, but recommended parameter to give the script a description in the UI. The description also shows in the left panel and in the script popup.
  • command (string): For simple scripts (see next section). This is the command that the script runs when executed.
  • run (Array<string>): For batch scripts (see next section). This property contains an array of simple scripts to run in sequence.
  • trigger (Array<string> ["setup", "pull", "checkout"]): Runs scripts after certain Git commands initiate in Codux. Options are "setup" for when the user opens the project for the first time, "pull" for when branch commits sync, and "checkout" for when switching branches.
Important!
A trigger can only run one simple script or one batch of scripts. If you want more than one script to run following a trigger, add them all to a single batch script. Only the bottom-most triggered script in codux.config.json will run in response to a trigger.
Here's sample configuration that includes a batch script, as well as triggers:
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
{  
    "$schema": "https://wixplosives.github.io/codux-config-schema/codux.config.schema.json",
    "scripts": {
        "install": {
            "title": "Install",
            "description": "Run install",
            "command": "npm i",
        },
        "build": {
            "title": "Build Project",
            "description": "Build the project",
            "command": "npm run build"
        },
        "install & build": {
            "title": "Initialize Project",
            "description": "Install dependencies and build project",
            "run": ["install", "build"],
            "trigger": ["checkout", "pull", "setup"]
        },
    …
}
Notice that the batch script's run property contains references to the two simple scripts configured above it. Use the key name of these scripts to reference them in the batch script. This allows the batch script to execute the actions defined in the referenced scripts.

Simple vs Batch Scripts 

Configured scripts come in two flavors:
  • Simple scripts: Simple commands to execute, such as yarn build or npm install. Scripts in codux.config.json are simple scripts when they have a command parameter instead of a run parameter.
  • Batch scripts: A batch of commands to execute in sequence. Scripts in codux.config.json are batch scripts when they have the run parameter rather than command.
You can tell how many scripts a batch script contains by looking at its title in Codux. When you run a batch script, you'll see each of the scripts it includes in the dialog.
Codux batch script run dialog
Tip!
Batches can also contain other batches, making it easy to reuse smaller ones, and to automate large parts of a workflow that may have been previously inaccessible to less-technical users.

Automatic Dependencies Installation 

Codux comes with a hard-coded build script that installs all the required dependencies for the project if the project's root directory is missing a node_modules folder and no scripts are defined in codux.config.json. To customize this build script, or to bypass this behavior to better fit the installation of your project, add the scripts configuration key to codux.config.json and configure it accordingly.
IN THIS ARTICLE
Previous article
Next article