Hooks

By default, Volta fetches Node, npm, and Yarn from public sources and registries (https://nodejs.org, https://yarnpkg.com, https://www.npmjs.com). However, depending on your environment, it may be necessary to tell Volta to instead download from a different source (e.g. npm Enterprise for internal tools). To accommodate that, Volta provides hooks into the download process.

Where to specify hooks

Hooks are always set in a file named hooks.json. This file can be in one of two places, depending on the scope you want those hooks to have:

Hooks file format

The contents of hooks.json must be an object, with optional keys for each type of tool (currently node, npm, and yarn). Each tool has 3 actions that can each have a hook applied to them:

Finally, each action has 3 possible hooks (described below) that can be used (only one of which can be specified for each action at any time). An example hooks.json file is:

{
    "node": {
        "index": {
            "bin": "/usr/local/node-lookup"
        },
        "latest": {
            "prefix": "http://example.com/node/"
        },
        "distro": {
            "template": "http://example.com/{{os}}/{{arch}}/node-{{version}}.tar.gz"
        }
    },
    "npm": {
        "index": {
            "prefix": "http://example.com/npm/"
        },
        "latest": {
            "bin": "~/npm-latest"
        },
        "distro": {
            "template": "http://example.com/npm/npm-{{version}}.tgz"
        }
    },
    "yarn": {
        "index": {
            "template": "http://example.com/yarn/{{os}}/{{arch}}/yarn-{{version}}.tgz"
        },
        "latest": {
            "prefix": "http://example.com/yarnpkg/"
        },
        "distro": {
            "bin": "~/yarn-distro"
        }
    }
}

Hook types

prefix Hooks

The prefix hook is a straightforward URL replacement. The URL will be built using the specified prefix, followed by the public file name for that action. For example, using the above hooks.json, we have a prefix hook specified for determining the latest yarn version. By default, Volta would fetch the latest version by making a request to https://yarnpkg.com/latest-version. Using the hook, Volta would instead try to access http://example.com/yarnpkg/latest-version, appending latest-version onto the specified prefix of http://example.com/yarnpkg/.

template Hooks

The template hook allows you to specify the template for a URL, with wildcards that will be replaced. The available wildcards are:

Using the node.distro hook from the example above, when fetching node@10.15.3 on a 64-bit Linux system, Volta would attempt to download the tarball from: http://example.com/linux/x64/node-10.15.3.tar.gz

bin Hooks

The bin hook is an all-purpose hook that will call out to an external script to determine the URL. The value is a path to an executable script that will be called, and the URL will be read from the stdout of that script. The stderr of the script will be shown to the user, so it can be used to show progress bars or waiting spinners if desired. If the path to the script is relative then it will be resolved relative to the hooks.json file in which it is specified. In this context, a relative path means that the path begins with ./ or ../ on Linux/MacOS and begins with .\ or ..\ on Windows. Lastly, for distro action hooks, the requested version of the tool will be passed as the first argument to that script.

Using the yarn.distro hook from the example hooks.json, when fetching yarn@1.13.0, Volta will call ~/yarn-distro "1.13.0" and attempt to download the tarball from the URL that is returned by that hook.