velociraptor@1.0.0-beta.18

Velociraptor is a script runner for Deno, inspired by npm's package.json scripts. It offers a similar experience but with out-of-the-box support for declarative deno cli options, environment variables, concurrency and (soon) git hooks.

Motivation
Install
Project status
Script files
Listing scripts
Running scripts
Exporting scripts
Shell scripting
Current working directory
Shell completions
Editor support
Help
Badge
Known limitations
Upcoming features
Contributing
License

Motivation

Deno doesn't have a dedicated package manager like npm. While this simplifies many aspects of development, working without the added tooling that npm comes with (such as scripts) may turn out to be challenging: as projects grow Deno cli commands can become quite long and difficult to track and there's not an easy way to share workflow scripts, git hooks and external tooling with collaborators. Velociraptor tries to provide a relatively lightweight solution to these problems by expanding the concept of npm scripts.

Install

🦕 Deno.land

$ deno install -qA -n vr https://deno.land/x/velociraptor@1.0.0-beta.18/cli.ts

🥚 Nest.land

$ deno install -qA -n vr https://x.nest.land/velociraptor@1.0.0-beta.18/cli.ts

Upgrade

To upgrade from an older version run the above commands with the -f flag.

To get help with the CLI run vr --help, or vr <SUBCOMMAND> --help for specific commands.

Project status

👨‍💻 WIP: until the Deno std library is stable there may be breaking changes here, use carefully and feel free to open an issue if you find a bug.

Script files

To get started, create a file called scripts.yaml or velociraptor.yaml in your project folder:

# scripts.yaml
scripts:
  start: deno run --allow-net server.ts
  test: deno test --allow-net server_test.ts

.json and .ts config files are supported as well:

// scripts.json
{
  "scripts": {
    "start": "deno run --allow-net server.ts",
    "test": "deno test --allow-net server_test.ts"
  }
}

// scripts.ts
import { ScriptsConfiguration } from "https://deno.land/x/velociraptor@1.0.0-beta.18/mod.ts";

export default <ScriptsConfiguration>{
  scripts: {
    start: "deno run --allow-net server.ts",
    test: "deno test --allow-net server_test.ts",
  },
};

Basic scripts

In its simplest form, the scripts property behaves like in package.json: the keys are script names and the values are the command strings.

Compact deno run

When a command starts with a .ts or .js file, deno run is automatically prepended:

scripts:
  start: server.ts # Equivalent to `deno run server.ts`

More script options

Scripts can also be objects:

scripts:
  start:
    desc: Runs the server
    cmd: deno run --allow-net server.ts

In this case the command(s) are specified in the cmd property. Use the desc property to provide a description of what the script does, it'll be shown in the list of available scripts (when running vr without arguments).

👇 The following properties can be specified both in script objects and at top-level, in which case they are applied to all the scripts defined in the file. Deno options are effectively only applied to deno commands that accept them.

Environment variables

Environment variables can be specified in the env mapping. You can also read environment variables from multiple files specified with envFile. envFile can be a single file or a list of files. Environment variables define with env will override environment variables defined with envFile.

# Env vars specified here are sent to
# all the scripts
envFile:
  - .env
env:
  PORT: 8081

scripts:
  start:
    cmd: deno run --allow-net server.ts
    # and these are script-specific
    envFile: .server_env
    env:
      PORT: 8082

The format of the envFile looks like this.

AWS_S3_TOKEN=d84a83539134f28f412c652b09f9f98eff96c9a
SECRET_KEY=7c6c72d959416d5aa368a409362ec6e2ac90d7f
MONGO_URI=mongodb://127.0.0.1:27017
PORT=3001

Exports, quotes and comments are also supported.

export AWS_S3_TOKEN="d84a83539134f28f412c652b09f9f98eff96c9a"
export SECRET_KEY='7c6c72d959416d5aa368a409362ec6e2ac90d7f'
export MONGO_URI=mongodb://127.0.0.1:27017
# export PORT=3001
export PORT=3002

Permissions

Deno permissions can be specified using allow.

# `allow` can be a list of boolean flags
allow:
  - net
  - read

scripts:
  start:
    cmd: server.ts
    allow: # or a map
      net: 127.0.0.1

Watch

Use the watch property to watch for file changes and restart processes automatically.

Only local files from entry point module graph are watched

scripts:
  start:
    cmd: server.ts
    watch: true

Tsconfig

To specify a tsconfig, set the tsconfig property.

scripts:
  start:
    cmd: server.ts
    tsconfig: tsconfig.json

Import maps

Import maps are specified in imap.

scripts:
  start:
    cmd: deno run --unstable server.ts
    imap: importmap.json

🧪 Import maps are currently marked as unstable so the --unstable flag must be provided (see other boolean flags).

Inspect

inspect and inspectBrk correspond to the --inspect and --inspect-brk options.

scripts:
  start:
    cmd: server.ts
    inspect: 127.0.0.1:9229

Lockfile

The lock property sets the namesake deno option.

scripts:
  start:
    cmd: server.ts
    lock: lock.json

⚠️ Setting this option doesn't create a lock file: you will have to create/update it by passing the --lock-write option manually to your script at the appropriate time. More info here.

Reload

Reload source code cache (recompile TypeScript).

scripts:
  start:
    cmd: server.ts
    reload: true                  # Reload everything
    reload: https://deno.land/std # Reload only standard modules
    reload:                       # Reload specific modules
      - https://deno.land/std/fs/utils.ts
      - https://deno.land/std/fmt/colors.ts

Other boolean flags

The --cached-only, --no-check, --no-remote, --quiet, --unstable options can be applied using the following properties:

scripts:
  start:
    cmd: server.ts
    cachedOnly: true
    noCheck: true
    noRemote: true
    quiet: true
    unstable: true

Log

The log property corresponds to deno's --log-level. The allowed values are debug and info.

scripts:
  start:
    cmd: server.ts
    log: debug

Cert

Specify a PEM certificate for http client in cert.

scripts:
  start:
    cmd: server.ts
    cert: certificate.pem

V8 flags

V8 flags can be specified like permissions under the v8Flags property.

v8Flags:
  - expose-gc
  - async-stack-trace

scripts:
  start:
    cmd: server.ts
    v8Flags:
      logfile: v8.log

Compound commands and concurrency

If the script value is an array of commands, the commands are executed serially.

scripts:
  start:
    - deno run one.ts
    - deno run two.ts
  test: # Compound scripts can contain script objects as well
    - deno test test_one.ts
    - cmd: deno test test_two.ts
      tsconfig: tsconfig.json

To declare concurrent commands, list them in the pll property of an object.

scripts:
  start:
    pll:
      - deno run one.ts
      - deno run two.ts

Parallel and serial scripts can be combined as well.

scripts:
  start:
    - pll:
        - deno run one.ts
        - deno run two.ts
    - deno run three.ts

Multiple commands specified in this way are executed separately. If you need to use pipes/redirections you can use your shell's syntax:

scripts:
  start: cat file.ts | deno

Script file model

See ScriptConfiguration for a detailed description of the structure of script files.

Listing scripts

Run

$ vr

to see a list of available scripts.

Running scripts

To run a script, use the run subcommand

$ vr run <SCRIPT> [ADDITIONAL ARGS]...

or, more concisely

$ vr [SCRIPT] [ADDITIONAL ARGS]...

Arg or option	Description
`SCRIPT`	The identifier of the script to run.
`ADDITIONAL ARGS`	Any other argument, passed to the script. Unlike `npm run`, the `--` separator is not needed.

For example, run

$ vr start
# or
$ vr run start

to execute the start script.

If you enabled shell completions, trigger the autocomplete on one of this commands to get the available scripts as suggestions.

Exporting scripts

If you want to use velociraptor to manage your scripts, but you want to be able to execute them in environments where you can't (or don't want to) install vr, the export subcommand may be of help: it allows you to export one or more scripts as standalone executable shell files together with their env variables, Deno cli options etc.:

$ vr export [SCRIPTS]...

Arg or option	Description
`SCRIPTS`	A space-separated list of scripts to export. If omitted, all the declared scripts are exported.
`-o, --out-dir`	The directory where the scripts will be exported (default: `bin`).

For example, run

$ vr export start

to export the start script. Now you can execute it by running

$ ./bin/start [ARGS]...

Scripts exporting currently only supports sh.

Shell scripting

Like in npm scripts, vr commands are executed inside a shell. The shell is determined by the SHELL env variable on Unix-like systems and by ComSpec on Windows, with respectively sh and cmd.exe as fallback values. To customize the shell without changing your default shell env variables you can use the VR_SHELL variable (a full path is required).

The shell requirements are pretty much the same as node's.

Current working directory

Velociraptor searches for script files up the folder tree starting from the directory where the vr command was launched. Scripts are run from the directory where the script file is, independently of the initial location.

Shell completions

To enable shell tab-completion for velociraptor commands, add the corresponding line to your shell's config:

zsh: ~/.zshrc
```
source <(vr completions zsh)
```
bash: ~/.bashrc
```
source <(vr completions bash)
```
fish: ~/.config/fish/config.fish
```
source (vr completions fish | psub)
```

Editor support

VSCode

Velociraptor support for VSCode adds code assistance for script configuration files (both yaml and json).

Help

If you need any help feel free to ask in the chat or on StackOverflow using the velociraptor tag.

Badge

Show your collaborators/users you use velociraptor:

[![vr scripts](https://badges.velociraptor.run/flat.svg)](https://velociraptor.run)

Known limitations

Commands with quotes are currently unusable when the shell is cmd.exe due to the way Rust's std::Command (used by Deno.run()) escapes cli arguments (see here).
As a workaround you can tell Velociraptor to use PowerShell instead of cmd (see Shell scripting) or run your scripts in the Windows Subsystem for Linux.

Upcoming features

Self-update: run vr upgrade to install the latest version.
Husky style git hooks: use the hook property to link a script to a git hook.

Contributing

Feedback and PRs are welcome! Take a look at the contributing guidelines.

License

This project is licensed under the MIT License. See LICENSE for details.