Wondering what’s next for npm?Check out our public roadmap! »

    script-launcher

    1.35.1 • Public • Published

    Script Launcher

    NPM version GitHub last commit Downloads Dependency status Dev Dependency status License

    Enhance your package.json scripts with features like: menus, functions, arrays, concurrency and many more. The features of Script Launcher are specialized in such a way, that working with Mac, Linux and Windows can be seamless experience.

    alt text

    Table of Contents

    Installation

    Install script-launcher as a development dependency in your project.

    npm install script-launcher --save-dev

    Use launch init to create a starter configuration based on one of the available templates.

    npx launch init basic

    If not already done so, change your package.json start script, so it will start Script Launcher. If you do not want to change your start script, you can also add custom run scripts for starting Script Launcher.

    Example: package.json

    {
        ...
        "scripts": {
            "start": "launch",
            ...
        },
        ...
    }
    

    You are now ready to start use Script Launcher by running: npm start or npm start serve:dev.

    Usage examples

    Show menu

    npm start

    You can also show the menu by running: npx launch

    Output:
    ✔ Select action › serve
    ✔ Select environment › acc
    ✔ Are you sure … yes
    
    Executing: npm start serve:acc
    
    Serve acc command.
    
     

    Start a specific launcher script

    npm start serve:dev
    npm start build:production

    Basically you can now use npm start instead of npm run.

    Output:
    Serve dev command.
    Build production command.
    
     

    List available launcher scripts

    npx launch list
    Output:
    build:acc
    build:dev
    build:production
    serve:acc
    serve:dev
    serve:production
    
     

    Start a specific launch script, by using the npm run

    For a cusom run script to work, you have to add a script to your package.json file, make sure there is a similar named script in your launcher-config.json file.

    Example: package.json

    {
        ...
        "scripts": {
            "lint": "launch",
            "test": "launch",
            ...
        },
        ...
    }
    

    Example: launcher-config.json

    {
      "scripts": {
        "lint": "echo Linting code...",
        "test": "echo Testing code..."
      }
    }

    Example run commands

    npm run lint
    npm run test

    Migrate package.json scripts

    Make sure all your repository changes are fully committed so you can undo the changes easily if they do not suit your needs. Remove or rename the start script in your package.json file.

    Now your are ready to migrate your package.json scripts to launcher-config.json scripts. By executing the command:

    npx launch migrate

    Migrate using parameter migration option:

    npx launch migrate --params

    Motivation

    In a traditional package.json you can only run scripts on a per line basis. With larger projects that have multiple environments, this can quickly become a hassle and difficult to maintain, like the example below:

    // Traditional package.json scripts //
    {
      "scripts": {
        "build:uva:dev": "ng build uva -c=dev --prod",
        "build:uva:tst": "ng build uva -c=tst --prod",
        "build:uva:acc": "ng build uva -c=acc --prod",
        "build:uva:prd": "ng build uva -c=prd --prod",
        "build:hva:dev": "ng build hva -c=dev --prod",
        "build:hva:tst": "ng build hva -c=tst --prod",
        "build:hva:acc": "ng build hva -c=acc --prod",
        "build:hva:prd": "ng build hva -c=prd --prod",
        "deploy:uva:dev": "npm run build:uva:dev && firebase deploy --public dist/uva --project status-uva-dev",
        "deploy:uva:tst": "npm run build:uva:tst && firebase deploy --public dist/uva --project status-uva-tst",
        "deploy:uva:acc": "npm run build:uva:acc && firebase deploy --public dist/uva --project status-uva-acc",
        "deploy:uva:prd": "npm run build:uva:prd && firebase deploy --public dist/uva --project status-uva-prd",
        "deploy:hva:dev": "npm run build:hva:dev && firebase deploy --public dist/hva --project status-hva-dev",
        "deploy:hva:tst": "npm run build:hva:tst && firebase deploy --public dist/hva --project status-hva-tst",
        "deploy:hva:acc": "npm run build:hva:acc && firebase deploy --public dist/hva --project status-hva-acc",
        "deploy:hva:prd": "npm run build:hva:prd && firebase deploy --public dist/hva --project status-hva-prd",
        "deploy:dev": "npm run deploy:uva:dev && npm run deploy:hva:dev",
        "deploy:tst": "npm run deploy:uva:tst && npm run deploy:hva:tst",
        "deploy:acc": "npm run deploy:uva:acc && npm run deploy:hva:acc",
        "deploy:prd": "npm run deploy:uva:prd && npm run deploy:hva:prd"
      }
    }

    With script-launcher you have the benefits of using variables, script references and many more features, so you can make the above example easier to maintain:

    // Example when using the Script Launcher migrate command:
    // npx launch migrate --params
    {
      "scripts": {
        "build:$project:$config": "ng build $project -c=$config --prod",
        "deploy:$project:$config": [
          "build:$project:$config",
          "firebase deploy --public dist/$project --project status-$project-$config"
        ],
        "deploy:$config": [
          "deploy:uva:$config",
          "deploy:hva:$config"
        ]
      }
    }

    To start this example you would use: npm start build:uva:tst, npm start deploy:prd etc.

    It's also possible to extend the example with an interactive menu, so a new developer can get start on your project more easily:

    {
      "menu": {
        "description": "deploy organization",
        "uva:University of Amsterdam.": {
          "description": "deploy environment",
          "acceptance": "deploy:uva:acc",
          "production": "deploy:uva:tst"
        },
        "hva:Amsterdam University of Applied Sciences.": {
          "description": "deploy environment",
          "acceptance": "deploy:hva:acc",
          "production": "deploy:hva:tst"
        }
      },
      "options": {
        "menu": {
          "defaultChoice": "hva:acc"
        }
      }
    }

    You would use: npm start to start the menu.

    Implementation examples

    To test an example, copy the json content from the example to the file named launcher-config.json and run the script.

    Sequential scripts

    This example uses square brackets to start multiple script one by one. This feature will make long script lines more readable.

    Create file: launcher-config.json

    {
      "scripts": {
        "build-stuff": [
          "echo Build step 1",
          "echo Build step 2",
          "echo Build step 3"
        ]
      }
    }

    Run: npm start build-stuff

    Output:
    Build step 1
    Build step 2
    Build step 3
    
     

    Change directory

    Specify an existing directory as an script command and it will change to that directory for the next scripts it executes. This can be handy if your script have to be run from within a different location.

    Create file: launcher-config.json

    {
      "scripts": {
        "build-stuff": [
          "node_modules/script-launcher",
          "echo *.js"
        ]
      }
    }

    Run: npm start build-stuff

    Output:
    common.js config-loader.js executor.js launch-menu.js launch.js logger.js scripts.js spawn-process.js variables.js
    
     

    Parameters and functions

    Use the dollar-sign in the script id and command, to specify script function parameter. You can specify a default value by using the equal sign. This feature makes it possible to start one script with different parameters.

    Create file: launcher-config.json

    {
      "scripts": {
        "serve:$project=uva:$config=dev": "echo ng serve $project -c=$config"
      }
    }

    Run: npm start serve , npm start serve::tst or npm start serve:hva:prd etc.

    Output:
    ng serve uva -c=dev
    
    ng serve uva -c=tst
    
    ng serve hva -c=prd
    
     

    Reference scripts

    Use an existing script id in the command section to execute another script in your config file. This feature makes it possible to reuse scripts from another script, with different arguments if desired.

    Create file: launcher-config.json

    {
      "scripts": {
        "build:$project:$config": "echo ng build $project -c=$config",
        "deploy:$project:$config": [
          "build:$project:$config",
          "echo firebase deploy --public dist/$project -P $project-$config"
        ],
        "deploy:$config": [
          "deploy:uva:$config",
          "deploy:hva:$config"
        ]
      }
    }

    Run: npm start deploy:tst

    Output:
    ng build uva -c=tst
    firebase deploy --public dist/uva -P uva-tst
    ng build hva -c=tst
    firebase deploy --public dist/hva -P hva-tst
    
     

    Reference scripts by using wildcards

    Use wildcards '*' to select multiple scripts. Wildcards cannot be used for selecting function by there parameters, this will result in a parameter containing the wildcard..

    Create file: launcher-config.json

    {
      "scripts": {
        "build:css": "echo Building: .css files",
        "build:js": "echo Building: .js files",
        "build:html": "echo Building: .html files",
        "build:all": {
          "concurrent": [
            "build:*"
          ]
        }
      }
    }

    Run: npm start build:* , npm start build:all or npx launch --concurrent build:*

    Output:
    Building: .css files
    Building: .js files
    Building: .html files
    
     

    Environment and command line argument values

    Use the dollar-sign in the script command, to references command line arguments and environment variables on Linux, Mac and windows in a consistent manner. It is also possible to set environment variables and use aliases.

    For compatibility reasons: when using a script id that is equal to the command being executed, all arguments are appended automatically.

    Create file: launcher-config.json

    {
      "scripts": {
        "build-stuff": [
          "environment=my-env",
          "package=$npm_package",
          "echo Package version: $package_version",
          "echo Package version: $npm_package_version",
          "echo Argument 1 : $1",
          "echo Argument 2 : $2",
          "echo",
          "echo All arguments: $*",
          "echo Offset arguments: $2*",
          "echo Environment : $environment"
        ],
        "echo": "echo"
      }
    }

    In this example node will be an alias for $npm_config_node. So $node_version corresponds to $npm_config_node_version

    Run: npm start build-stuff arg1 arg2 arg3 or npm start echo arg1 arg2 arg3

    Output:
    Package version: 1.35.1
    Package version: 1.35.1
    Argument 1 : arg1
    Argument 2 : arg2
    All arguments: arg1 arg2 arg3
    Offset arguments: arg2 arg3
    Environment : my-env
    
    arg1 arg2 arg3
    
     

    Environment String Manipulation and Expanding Variables

    Pattern Description
    ${var:num1:num2} Substring
    ${var/pattern/string} Find and replace (only replace first occurrence)
    ${var//pattern/string} Find and replace all occurrences
    ${var,} Convert first character to lowercase.
    ${var,,} Convert all characters to lowercase.
    ${var^} Convert first character to uppercase.
    ${var^^} Convert all character to uppercase..

    Create file: launcher-config.json

    {
      "scripts": {
        "build-stuff": [
          "var=app-uva=hva-prd",
          "echo ${var::-8}",
          "echo ${var:8}",
          "echo ${var:4:7}",
          "echo ${var/-/=}",
          "echo ${var//-/=}",
          "echo ${var^^}",
          "echo ${var^}",
          "var=APP-UVA=HVA-PRD",
          "echo ${var,,}",
          "echo ${var,}",
          "echo ${*^^}",
          "echo ${2*,}"
        ]
      }
    }

    Run: npm start build-stuff arg1 ARG2 arg3

    Output:
    app-uva
    hva-prd
    uva=hva
    app=uva=hva-prd
    app=uva=hva=prd
    APP-UVA=HVA-PRD
    App-uva=hva-prd
    app-uva=hva-prd
    aPP-UVA=HVA-PRD
    ARG1 ARG2 ARG3
    aRG2 arg3
    
     

    Launch arguments, command arguments, parameters and arguments

    • Launch arguments: These are values passed to laucher directly, for example: launch init or launch version
    • Command arguments: These are values passed from the command line that was used to start the script, for example: npm start build my-arg1 my-arg2
    • Function arguments: These are values passed from scripts to a function. Arguments are accessed by a number, for example: $1
    • Parameters: These are for passing a fixed set of values to a function. Parameters are accessed by their name, for example: $project

    Create file: launcher-config.json

    {
      "scripts": {
        "myFunc:$funcParam1:$funcParam2": [
          "echo Function Parameter 1: $funcParam1",
          "echo Function Parameter 2: $funcParam2",
          "echo Function Arguments 1: $1",
          "echo Function Arguments 2: $2",
          "echo Function All arguments: $*"
        ],
        "build-stuff:$myParam1:$myParam2": [
          "--",
          "echo Main Parameter 1: $myParam1",
          "echo Main Parameter 2: ${myParam2}",
          "echo Main Arguments 1: $1",
          "echo Main Arguments 2: $2",
          "echo Main All arguments: $*",
          "echo Main Offset arguments: $2*",
          "--",
          "myFunc:$myParam1:funcParam funcArg $1",
          "--"
        ]
      }
    }

    Run: npm start build-stuff:param1:param2 arg1 arg2 arg3

    Output:
    --------------------------------
    Main Parameter 1: param1
    Main Parameter 2: param2
    Main Arguments 1: arg1
    Main Arguments 2: arg2
    Main All arguments: arg1 arg2 arg3
    Main Offset arguments: arg2 arg3
    --------------------------------
    Function Parameter 1: param1
    Function Parameter 2: funcParam
    Function Arguments 1: funcArg
    Function Arguments 2: arg1
    Function All arguments: funcArg arg1
    --------------------------------
    
     

    Escaping characters

    Use a backslash in the script command, to escaping variables.

    Create file: launcher-config.json

    {
      "scripts": {
        "escaping": [
          "echo '\\$1                    ' : '$1'",
          "echo '\\$npm_package_version  ' : '$npm_package_version'",
          "echo '\\${1}                  ' : '${1}'",
          "echo '\\${npm_package_version}' : '${npm_package_version}'"
        ]
      }
    }

    Run: npm start escaping arg1

    Output:
    $1                     : arg1
    $npm_package_version   : 1.35.1
    ${1}                   : arg1
    ${npm_package_version} : 1.35.1
    
     

    Environment values and special commands

    Pattern Type Description
    launch_version Environment Launcher Version number
    launch_platform Environment Operating system platform
    launch_time_start Environment Start time
    launch_time_current Environment Current time
    launch_time_elapsed Environment Elapsed time
    launch_style_blue Environment Blue text
    launch_style_bold Environment Bold text
    launch_style_cyan Environment Cyan text
    launch_style_dim Environment Dim text
    launch_style_green Environment Green text
    launch_style_normal Environment Nomal text
    launch_style_red Environment Red text
    launch_style_yellow Environment Yellow text
    "echo" Command Output an empty line
    "" Command Output an empty line
    "--" Command Line with the width of the terminal
    " || true" Command Added at the end of a command to suppress errors
    "#" Command Added at the begining for a line to disable execution
    "|?" Command Grep like functionality

    Create file: launcher-config.json

    {
      "scripts": {
        "build-stuff": {
          "condition": "echo grep example |? example",
          "sequential-then": [
            "echo ${launch_style_bold}Version:$launch_style_normal $launch_version",
            "echo ${launch_style_bold}Platform:$launch_style_normal $launch_platform",
            "echo ${launch_style_bold}Time:$launch_style_normal $launch_time_start",
            "--",
            "echo Color: ${launch_style_blue}Blue$launch_style_normal",
            "echo Color: ${launch_style_bold}Bold$launch_style_normal",
            "echo",
            "echo Color: ${launch_style_cyan}Cyan$launch_style_normal",
            "echo Color: ${launch_style_dim}Dim$launch_style_normal",
            "",
            "# The error of the next action will be suppressed",
            "exit 1 || true",
            "echo Color: ${launch_style_green}Green$launch_style_normal",
            "echo Color: ${launch_style_red}Red$launch_style_normal",
            "echo Color: ${launch_style_yellow}Yellow$launch_style_normal",
            "--",
            "echo ${launch_style_bold}Current:$launch_style_normal $launch_time_current",
            "echo ${launch_style_bold}Elapsed:$launch_style_normal $launch_time_elapsed"
          ]
        }
      }
    }

    Run: npm start build-stuff

    Output:
    grep example
    Version: 1.35.1
    Platform: linux
    Time: 2019-09-16 10:33:20.628
    --------------------------------
    Color: Blue
    Color: Bold
    Color: Cyan
    Color: Dim
    
    Color: Green
    Color: Red
    Color: Yellow
    --------------------------------
    Current: 2019-09-16 10:33:42.285
    Elapsed: 137ms
    
     

    Glob patterns

    Script Launcher makes use of the Glob package, so you can use any of the supported glob patterns in your scripts.

    Create file: launcher-config.json

    {
      "scripts": {
        "build-stuff": [
          "node_modules/script-launcher",
          "echo Javascript files files: *.js",
          "echo Markdown files: **/*.md"
        ]
      }
    }

    Run: npm start build-stuff

    Output:
    Javascript files files: common.js config-loader.js executor.js launch-menu.js launch.js logger.js scripts.js spawn-process.js variables.js
    Markdown files: README.md
    
     

    Concurrent scripts

    This example uses the concurrent keyword to run multiple script in parallel and the sequential keyword to start multiple script one by one. This feature is convenient in a development environment, when you want to start development server in the background.

    Use the limit argument or option to limit the number of commands to execute in parallel..

    Create file: launcher-config.json

    {
      "scripts": {
        "sleep:$time": "node -e \"setTimeout(() => {}, $time)\"",
        "background:$job:$time": [
          "echo Background job : $job",
          "sleep:$time",
          "echo Completed job : $job"
        ],
        "build-stuff": {
          "concurrent": [
            "background:1:3000",
            "background:2:5000"
          ],
          "sequential": [
            "echo Sequential job : 3",
            "sleep:1000",
            "echo Sequential job : 4",
            "sleep:1000"
          ]
        }
      }
    }

    Run: npm start build-stuff

    Output:
    Background job : 1
    Background job : 2
    Sequential job : 3
    Sequential job : 4
    Completed job : 1
    Completed job : 2
    
     

    Inline script blocks

    This example uses the inline script blocks to run multiple script in parallel and to run multiple script one by one.

    Create file: launcher-config.json

    {
      "scripts": {
        "sleep:$time": "node -e \"setTimeout(() => {}, $time)\"",
        "background:$job:$time": [
          "echo Background job : $job",
          "sleep:$time",
          "echo Completed job : $job"
        ],
        "build-stuff": [
          [
            "background:1:3000",
            "background:2:5000"
          ],
          {
            "sequential": [
              "echo Sequential job : 3",
              "sleep:1000",
              "echo Sequential job : 4",
              "sleep:1000"
            ]
          }
        ]
      }
    }

    Run: npm start build-stuff

    Output:
    Background job : 1
    Background job : 2
    Completed job : 1
    Completed job : 2
    Sequential job : 3
    Sequential job : 4
    
     

    Confirmation prompt

    Confirmation prompts can be used for asking a confirmation to continue. Use the confirm argument to auto confirm.

    Create file: launcher-config.json

    {
      "scripts": {
        "build-stuff": {
          "confirm": "Are you sure you want to continue",
          "sequential-then": "echo You are sure!",
          "sequential-else": "echo You are not sure!"
        }
      }
    }

    Run: npm start build-stuff , npx launch build-stuff confirm or npx launch build-stuff --confirm=false

    Output:
    ✔ Are you sure you want to continue ... yes
    You are sure!
    
    ✔ Are you sure you want to continue ... yes
    You are sure!
    
    ✔ Are you sure you want to continue ... no
    You are not sure!
    
     

    Condition and exclusion constraints

    • condition: Must evaluate to true or 0 for the corresponding script block to be executed.
    • exclusion: Must evaluate to false or !0 for the corresponding script block to be executed.

    The value of the condition and exclusion statement can be a string or an array of strings containing a JavaScript expression returning a Boolean, directory name or a shell command.

    Create file: launcher-config.json

    {
      "scripts": {
        "build-stuff": [
          {
            "exclusion": "node_modules_test",
            "sequential-then": [
              "echo npm install",
              "mkdir node_modules_test"
            ]
          },
          {
            "condition": "node_modules_test",
            "sequential-then": [
              "echo npm start",
              {
                "condition": "'$launch_platform'==='win32'",
                "sequential": "echo Test platform type.",
                "sequential-then": "rmdir node_modules_test",
                "sequential-else": "rm -d node_modules_test"
              }
            ]
          }
        ]
      },
      "options": {
        "logLevel": 2
      }
    }

    Run: npm start build-stuff

    Output:
    /bin/sh: 1: node_modules_test: not found
    npm install
    npm start
    Test platform type.
    
     

    Repeaters (String)

    The repeater statement must contain a reference to a settings array. The corresponding script block will be executed for each instance in the settings array.

    Example using a string array. Create file: launcher-config.json

    {
      "scripts": {
        "ping": [
          {
            "repeater": "$launch_setting_servers",
            "sequential": [
              "echo Action: $launch_setting_command $_"
            ]
          }
        ]
      },
      "settings": {
        "command": "ping",
        "servers": [
          "www.google.com",
          "duckduckgo.com",
          "bing.com"
        ]
      }
    }

    Run: npm start ping

    Output:
    Action: ping www.google.com
    Action: ping duckduckgo.com
    Action: ping bing.com
    
     

    Repeaters (Object)

    Example using an object array. Create file: launcher-config.json

    {
      "scripts": {
        "ping": [
          {
            "repeater": "$launch_setting_servers",
            "sequential": [
              "echo $_name",
              "--",
              "echo Action: $launch_setting_command $_host",
              ""
            ]
          }
        ]
      },
      "settings": {
        "command": "ping",
        "servers": [
          {
            "name": "Google",
            "host": "www.google.com"
          },
          {
            "name": "DuckDuckGo",
            "host": "duckduckgo.com"
          },
          {
            "name": "Bing",
            "host": "bing.com"
          }
        ]
      }
    }

    Run: npm start ping

    Output:
    Google
    --------------------------------
    Action: ping www.google.com
    
    DuckDuckGo
    --------------------------------
    Action: ping duckduckgo.com
    
    Bing
    --------------------------------
    Action: ping bing.com
    
    
     

    Interactive menu

    Use the menu section to create an interactive landing menu, so a new developer can get start on your project more easily.

    • description keyword is used as a description of presented values.
    • Use a colon to separate the menu item name and description.

    The options.menu.timeout can be used to auto close the menu after a specified time. Use the Menu options section for more information on all the available options.

    Create file: launcher-config.json

    {
      "scripts": {
        "serve:$project:dev": {
          "concurrent": [
            "echo Start development server",
            "echo ng serve $project -c=dev"
          ]
        },
        "serve:$project:$config": "echo ng serve $project -c=$config"
      },
      "menu": {
        "description": "organization",
        "uva:University of Amsterdam.": {
          "description": "environment",
          "development": "serve:uva:dev",
          "acceptance": "serve:uva:acc",
          "production": "serve:uva:prd"
        },
        "hva:Amsterdam University of Applied Sciences.": {
          "description": "environment",
          "development:Builds and serves your app for development.": "serve:hva:dev",
          "acceptance:Builds and serves your app for acceptance.": "serve:hva:acc",
          "production:Builds and serves your app for production.": "serve:hva:prd"
        }
      },
      "options": {
        "menu": {
          "defaultChoice": "hva:development"
        }
      }
    }

    Run: npm start menu uva:acceptance , npm start menu or npm start

    Output:
    ? Select organization › - Use arrow-keys. Return to submit.
    ❯   uva - University of Amsterdam.
        hva
    
    ✔ Select organization › uva
    ? Select environment › - Use arrow-keys. Return to submit.
        development
    ❯   acceptance
        production
    
    ✔ Select environment › acceptance
    
    Executing: npm start serve:uva:acc
    
    ng serve uva -c=acc
    
    ? Select organization › - Use arrow-keys. Return to submit.
        uva
    ❯   hva - Amsterdam University of Applied Sciences.
    
    ✔ Select organization › hva
    
    Executing: npm start serve:hva:dev
    
    Start development server
    ng serve hva -c=dev
    
     

    Menu save default script

    Use the menu section options to specify a defaultScript, this will disable the interactive menu.

    Best practices is to specify the menu default options in the launcher-custom.json file, and add this file the your .gitignore. Now every developer can customize its menu without interfering with the project defaults.

    Use npm start menu to ignore the defaultScript option, so the menu will be interactive.

    Create file: launcher-config.json

    {
      "scripts": {
        "serve:$environment": "echo Serve script: $environment",
        "build:$environment": "echo Build script: $environment"
      },
      "menu": {
        "description": "organization",
        "uva:University of Amsterdam.": {
          "description": "environment",
          "serve": "serve:uva",
          "build": "build:uva"
        },
        "hva:Amsterdam University of Applied Sciences.": {
          "description": "environment",
          "serve": "serve:hva",
          "build": "build:hva"
        }
      },
      "options": {
        "menu": {
          "defaultScript": "build:hva"
        }
      }
    }

    Run: npm start

    Output:
    Auto menu:                               (Use the menu by running: npm start menu)
    Executing: npm start build:hva
    
    Build script: hva
    
     

    Launcher arguments

    Use the help for a list of available options.

    Run: npx launch --help

    Usage: launch [command] [options...]
    
    Commands:
      init         [template] Create starter config files.
      list         [type] List available launcher scripts.
      migrate      Migrate your package.json scripts.
      help         Show this help.
      version      Outputs launcher version.
    
    Options:
      logLevel=    Set log level.
      config=      Merge in an extra config file.
      confirm=     Auto value for confirm conditions.
      ansi=        Enable or disable ansi color output.
      directory=   The directory from which configuration files are loaded.
      menuTimeout= Set menu timeout in seconds.
      params=      Set the number of parameters to preserve.
      concurrent=  Execute commandline wildcard matches in parallel.
      limit=       Limit the number of commands to execute in parallel.

    Launcher Command: init

    Use the init command to create a starter configuration for you project.

    Run: npx launch init this will list the available templates

    Available templates:
    
    angular
    basic
    blank
    
    Example usage: npx launch init basic

    Run: npx launch init basic this will create a basic starter configuration

    Create starter config: basic
    
    Createing: launcher-config.json
    Createing: launcher-menu.json
    
    Updating package.json.
    
    Start script of package.json updated.

    Launcher Command: migrate

    Use the migrate command to convert your package.json script to a script-launcher configuration. Use the params option the parameterize your script functions.

    Run: npx launch migrate --params=1 this will convert your package.json scripts

    Migrating: package.json
    
    Script to migrate: 12
    Script to update: 2
    
    ✔ Are you sure ... yes
    
    Updating: package.json
    Creating: launcher-menu.json
    Creating: launcher-config.json

    Launcher Command: script

    Start one or more script directly from the command line sequentially or concurrently

    Run: npx launch build:css build:js to start one or more script in sequence

    Building: .css files
    Building: .js files

    Run: npx launch build:css build:js --concurrent to start one ore more script in parallel

    Building: .css files
    Building: .js files

    Launcher Command: list

    Use the list command to display the available scripts. This can be used for enabling tab completion.

    Run: npx launch list complete for listing scripts that can be used for tab completion. This is the default value.

    serve:hva:acc
    serve:hva:dev
    serve:hva:prd
    serve:uva:acc
    serve:uva:dev
    serve:uva:prd

    Run: npx launch list script for listing available scripts.

    serve:$project:$config
    serve:$project:dev

    Run: npx launch list menu for listing available menu scripts.

    serve:hva:acc
    serve:hva:dev
    serve:hva:prd
    serve:uva:acc
    serve:uva:dev
    serve:uva:prd

    Launcher settings

    The launcher settings can be used to specify named values that can be used by the launcher scripts. Consult the repeaters implementation examples section for more information on repeaters.

    Create file: launcher-config.json

    {
      "scripts": {
        "build:$config": [
          "settings=$launch_setting_${config}",
          "echo name: $launch_setting_name",
          "echo version: $settings_version",
          "echo ng build -c=$config --deploy-url $settings_url",
          "",
          {
            "repeater": "$launch_setting_${config}_server",
            "sequential": [
              "echo Deploying to: $_"
            ]
          }
        ]
      },
      "settings": {
        "name": "example",
        "dev": {
          "version": "2.0.0",
          "url": "$launch_setting_name.dev.com",
          "server": [
            "server1.dev.com",
            "server2.dev.com"
          ]
        },
        "acc": {
          "version": "1.9.0",
          "url": "$launch_setting_name.acc.com",
          "server": [
            "server1.acc.com",
            "server2.acc.com"
          ]
        },
        "production": {
          "version": "1.8.0",
          "url": "$launch_setting_name.prd.com",
          "server": [
            "server1.prd.com",
            "server2.prd.com"
          ]
        }
      }
    }

    Run: npm start build:dev , npm start build:acc or npm start build:production

    Output:
    name: example
    version: 2.0.0
    ng build -c=dev --deploy-url example.dev.com
    
    Deploying to: server1.dev.com
    Deploying to: server2.dev.com
    
    name: example
    version: 1.9.0
    ng build -c=acc --deploy-url example.acc.com
    
    Deploying to: server1.acc.com
    Deploying to: server2.acc.com
    
    name: example
    version: 1.8.0
    ng build -c=production --deploy-url example.prd.com
    
    Deploying to: server1.prd.com
    Deploying to: server2.prd.com
    
     

    Launcher options

    The launcher options can be used the customize the default behavior of Script Launcher.

    Launcher files

    The files options can be used to configure the config files to load when starting launcher. When using multiple files they will be merged together in the loading order. Be aware the launcher-config.json is always the first file being loaded even when it is not present in the files list.

    By using this option it's possible the split your configuration over multiple files. It's a good practice is to split your script and menu configurations to their own file. You could also include the package.json file in this list, then you can use the strength of Script Launcher in your package.json file.

    The default value of this list is presented in the following example:

    {
      "scripts": {
        ...
      },
      "options": {
        "files": [
          "launcher-config.json",
          "launcher-scripts.json",
          "launcher-settings.json",
          "launcher-menu.json",
          "launcher-custom.json",
        ]
      }
    }
    

    Script shell

    The script shell options can be used to configure the spawn shell, this value is passed to the options shell of the node child_process.spawn method. If you want to specify a shell for a specific platform, use one of the platform names as a nested object name. If there is no platform name match found the default will be used.

    Example shell option for specific platform

    {
      "scripts": {
        ...
      },
      "options": {
        "script": {
          "shell": {
            "aix":"bash",
            "darwin":"bash",
            "freebsd":"bash",
            "linux":"bash",
            "openbsd":"bash",
            "sunos":"bash",
            "win32":"cmd.exe",
            "default":"bash"
          }
        }
      }
    }
    

    The default value is presented in the following example:

    {
      "scripts": {
        ...
      },
      "options": {
        "script": {
          "shell": true
        }
      }
    }
    

    Glob Options

    Official documentation of the fast-glob options If the nonull script-launcher option is set, and no match was found, then the match contains the original pattern.

    {
      "options": {
        "glob": {
          "nonull": false
        }
      }
    }

    Menu options

    • defaultChoice: Specify the default chosen entries of your menu, separated by a colon.
    • defaultSelect: Specify the default selected entries of your menu, separated by a colon.
    • defaultScript: Auto start a specific script, this will disable the interactive menu.
    • timeout: Auto close/select a menu value after a specified time.
    • confirm: Enable disable menu confirmation prompt.

    The default value is presented in the following example:

    {
      "scripts": {
        ...
      },
      "options": {
        "menu": {
          "defaultChoice": "",
          "defaultSelect": "",
          "defaultScript": "",
          "timeout": 0,
          "confirm" :true
        }
      }
    }
    

    Logging

    The logLevel option is used for configuring the Script Launcher log level, available values are: 0=disabled 1=info 2=log 3=debug

    The default value is presented in the following example:

    {
      "scripts": {
        ...
      },
      "options": {
        "logLevel": 0
      }
    }
    

    Limit Concurrency

    Use the limit option to limit the number of commands to execute in parallel. When using the value 0 the number of available cpus will be used.

    The default value is presented in the following example:

    {
      "scripts": {
        ...
      },
      "options": {
        "limit": 0
      }
    }
    

    Enable tab completion

    To enable tab completion for script-launcher in your current terminal, execute the following commands. This will test if you are using tab completion on npm start if so, it will execute npx launch list completion if not, it will execute the default npm completion function _npm_completion.

    eval "$(npm completion)"
    
    _launch_completion () {
      if [[ $COMP_LINE != "npm start"* ]] ; then
        _npm_completion
      else
        npx --quiet --no-install launch list
      fi
    }
    complete -o default -F _launch_completion npm

    Install

    npm i script-launcher

    DownloadsWeekly Downloads

    185

    Version

    1.35.1

    License

    MIT

    Unpacked Size

    218 kB

    Total Files

    20

    Last publish

    Collaborators

    • avatar