Vendorfiles

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

Table of Contents

• Quick Start
• Configuration
  • Basic Setup
  • Custom Output Paths
  • Renaming Files
  • Commit-Based Versioning
  • GitHub Releases
  • Filtering Releases
  • Locking Dependencies
  • Default Options
• Commands
  • Sync
  • Update
  • Outdated
  • Install
  • Uninstall
  • Login
• GitHub Action
• JSON Schema

Quick Start

Install vendorfiles:

npm install -g vendorfiles   # global (recommended for CLI usage)
npm install vendorfiles      # local (for project-specific usage)

Create a vendor.json in 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/.

Configuration

Vendorfiles 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.

Basic Setup

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}/.

Custom Output Paths

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/
        }
    }
}

Renaming Files

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"
                }
            ]
        }
    }
}

Commit-Based Versioning

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 the files array

In the example above, Cooltipz tracks package.json's commits, while Coloris tracks dist/coloris.min.js.

GitHub Releases

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"
                    }
                }
            ]
        }
    }
}

Filtering Releases

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.

Locking Dependencies

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 sync if not already present
• Will be skipped during vendor update
• Will not appear in vendor outdated output

Default Options

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: afde2592a6254be7c14ccac520cb608bd1adbaf9

Individual dependencies can override any default option.

Commands

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.

Sync

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

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

Outdated

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

Install

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"

Uninstall

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

Login

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

GitHub Action

Automate dependency updates with vendorfiles-action which creates pull requests for outdated dependencies.

- uses: Araxeus/vendorfiles-action@v1
  with:
    token: ${{ secrets.GITHUB_TOKEN }}
    package-manager: npm

See the action's readme for more options.

JSON Schema

Validate your vendor.json against the JSON schema to catch configuration errors

If installed locally:

{
    "$schema": "./node_modules/vendorfiles/vendorfiles.schema.json",
    "vendorDependencies": {
        //...
    }
}

From URL

{
    "$schema": "https://raw.githubusercontent.com/Araxeus/vendorfiles/refs/heads/main/vendorfiles.schema.json",
    "vendorDependencies": {
        //...
    }
}