Vendorfiles lets you pull files from GitHub repositories and keep them up to date. Think of it like a package manager, but for individual files — CSS libraries, binaries, config files, whatever you need.
- Download files directly from any GitHub repo
- Grab release assets (including extracting from zip/tar archives)
- Track versions via releases or commit hashes
- Configure with TOML, YAML, JSON, or package.json
- Automate updates with the included GitHub Action
-
Install vendorfiles:
npm install -g vendorfiles
-
Create a
vendor.jsonin your project:{ "vendorDependencies": { "Coloris": { "version": "v0.17.1", "repository": "https://github.com/mdbassit/Coloris", "files": ["dist/coloris.min.js", "dist/coloris.min.css"] } } } -
Run:
vendor sync
That's it! Your files are now in ./vendor/Coloris/.
Global (recommended for CLI usage):
npm install -g vendorfilesLocal (for project-specific usage):
npm install vendorfilesVendorfiles looks for a config file in this order: vendor.toml, vendor.yml, vendor.yaml, vendor.json, package.json.
All examples below are in JSON, but TOML and YAML work too. See the examples folder for more formats.
Define your dependencies under vendorDependencies:
{
"vendorDependencies": {
"Cooltipz": {
"version": "v2.2.0",
"repository": "https://github.com/jackdomleo7/Cooltipz.css",
"files": ["cooltipz.min.css", "LICENSE"]
},
"Coloris": {
"version": "v0.17.1",
"repository": "https://github.com/mdbassit/Coloris",
"files": ["dist/coloris.min.js", "dist/coloris.min.css", "LICENSE"]
}
}
}By default, files are saved to ./vendor/{dependency-name}/.
Change the base vendor folder with vendorConfig:
{
"vendorConfig": {
"vendorFolder": "./my-vendors"
}
}Each dependency can also specify its own output folder. Use {vendorFolder} to reference the base folder:
{
"vendorConfig": {
"vendorFolder": "./my-vendors"
},
"vendorDependencies": {
"Cooltipz": {
"version": "v2.2.0",
"repository": "https://github.com/jackdomleo7/Cooltipz.css",
"files": ["cooltipz.min.css", "LICENSE"],
"vendorFolder": "{vendorFolder}/Cooltipz" // outputs to ./my-vendors/Cooltipz
},
"Coloris": {
"version": "v0.17.1",
"repository": "https://github.com/mdbassit/Coloris",
"files": ["dist/coloris.min.js", "dist/coloris.min.css", "LICENSE"],
"vendorFolder": "{vendorFolder}" // outputs directly to ./my-vendors/
}
}
}Use an object with source: destination to rename or move files:
{
"vendorDependencies": {
"Coloris": {
"version": "v0.17.1",
"repository": "https://github.com/mdbassit/Coloris",
"files": [
"dist/coloris.min.js",
"dist/coloris.min.css",
{
"LICENSE": "../licenses/COLORIS_LICENSE"
}
]
}
}
}By default, versions track GitHub releases. If you need to track a specific file's changes instead, use hashVersionFile:
{
"vendorDependencies": {
"Cooltipz": {
"repository": "https://github.com/jackdomleo7/Cooltipz.css",
"version": "f6ec482ea395cead4fd849c05df6edd8da284a52",
"hashVersionFile": "package.json",
"files": ["cooltipz.min.css", "package.json"]
},
"Coloris": {
"repository": "https://github.com/mdbassit/Coloris",
"version": "v0.17.1",
"hashVersionFile": true,
"files": ["dist/coloris.min.js"]
}
}
}- String value: Track that specific file's latest commit hash
true: Track the first file in thefilesarray
In the example above, Cooltipz tracks package.json's commits, while Coloris tracks dist/coloris.min.js.
Download release assets using {release}/ in the file path. Use {version} to insert the semver version (without v prefix or suffixes like -alpha):
{
"vendorDependencies": {
"fzf": {
"version": "0.38.0",
"repository": "https://github.com/junegunn/fzf",
"files": [
"LICENSE",
"{release}/fzf-{version}-linux_amd64.tar.gz",
{
"{release}/fzf-{version}-windows_amd64.zip": "fzf-windows.zip"
}
]
}
}
}Extracting from archives:
You can extract specific files from zip/tar archives:
{
"vendorDependencies": {
"fzf": {
"version": "0.38.0",
"repository": "https://github.com/junegunn/fzf",
"files": [
"LICENSE",
{
"{release}/fzf-{version}-linux_amd64.tar.gz": ["fzf"],
"{release}/fzf-{version}-windows_amd64.zip": {
"fzf.exe": "my-custom-fzf.exe"
}
}
]
}
}
}Use releaseRegex to control which releases are considered when finding the "latest" version. The regex is tested against release tags/names.
Common patterns:
- Semver only:
"^v\\d+\\.\\d+\\.\\d+$" - Exclude pre-releases:
"^v(?!.*-(?:alpha|beta)).*" - Match title containing "stable":
"stable"
{
"vendorDependencies": {
"fzf": {
"version": "0.38.0",
"repository": "https://github.com/junegunn/fzf",
"releaseRegex": "^v\\d+\\.\\d+\\.\\d+$",
"files": ["{release}/fzf-{version}-linux_amd64.tar.gz"]
}
}
}Note: Use double escaping (
\\d) in JSON strings.
Use locked: true to prevent a dependency from being updated when running vendor update. This is useful when you need to pin a specific version and want to avoid accidental upgrades.
{
"vendorDependencies": {
"Coloris": {
"version": "v0.17.1",
"repository": "https://github.com/mdbassit/Coloris",
"files": ["dist/coloris.min.js", "dist/coloris.min.css"],
"locked": true
}
}
}Locked dependencies:
- Will still be downloaded during
vendor syncif not already present - Will be skipped during
vendor update - Will not appear in
vendor outdatedoutput - Can be unlocked by removing the
lockedoption or setting it tofalse
Use a default or defaultVendorOptions object to share options across all dependencies:
vendorConfig:
vendorFolder: .
default:
vendorFolder: "{vendorFolder}"
repository: https://github.com/nushell/nu_scripts
hashVersionFile: true
vendorDependencies:
nu-winget-completions:
files: custom-completions/winget/winget-completions.nu
version: 912bea4588ba089aebe956349488e7f78e56061c
nu-cargo-completions:
files: custom-completions/cargo/cargo-completions.nu
version: afde2592a6254be7c14ccac520cb608bd1adbaf9Individual dependencies can override any default option.
Usage: vendor command [options]
Commands:
sync|s [options] Sync config file
update|upgrade [names...] Update outdated dependencies
outdated|o List outdated dependencies
install|add [options] <url/name> [version] Install a dependency
uninstall|remove [names...] Uninstall dependencies
login|auth [token] Login to GitHub
help [command] display help for command
Options:
-c, --config [file/folder path] Config file path / Folder containing the config file
-v, --version output the current version
-h, --help display help for command
You can also set the config location via the VENDOR_CONFIG environment variable. The CLI option (-c) takes precedence if both are provided.
Download and sync all dependencies defined in your config file.
Usage: vendor sync|s [options]
Options:
-f, --force Force sync (re-download all files)
-h, --help display help for command
Examples:
vendor sync
vendor sync -f
Update dependencies to their latest version.
Usage: vendor update|upgrade [options] [names...]
Options:
-p|--pr Output pull request text for gh action (default: false)
-h, --help display help for command
Examples:
vendor update # update all
vendor update React # update one
vendor update React Express # update specific ones
Check which dependencies have newer versions available and output a list.
Usage: vendor outdated|o [options]
Options:
-h, --help display help for command
Examples:
vendor outdated
vendor o
Add a new dependency interactively.
Usage: vendor install|add [options] <url/name> [version]
Arguments:
url/name GitHub repo URL, owner/repo, or name to search for
version Version to install
Options:
-n, --name [name] Name to write in dependencies
-f, --files <files...> Files to install
-h, --help display help for command
Examples:
vendor install React -n MyReact -f README.md
vendor add Araxeus/vendorfiles v1.0.0 -f README.md LICENSE
vendor i https://github.com/th-ch/youtube-music -f "{release}/YouTube-Music-{version}.exe"
Remove dependencies from your config and delete their files.
Usage: vendor uninstall|remove [options] [names...]
Arguments:
names Package names to uninstall
Options:
-h, --help display help for command
Examples:
vendor uninstall React
vendor remove React youtube-music
Authenticate with GitHub to increase API rate limits.
Usage: vendor login|auth [options] [token]
Arguments:
token GitHub token (leave empty to login via browser)
Options:
-h, --help display help for command
Examples:
vendor login # opens browser for OAuth
vendor auth <token> # use existing token
Automate dependency updates with vendorfiles-action:
- uses: Araxeus/vendorfiles-action@v1
with:
token: ${{ secrets.GITHUB_TOKEN }}
package-manager: yarnSee the action's readme for more options.