This is a GitHub template for building a mise backend plugin using the vfox-style backend architecture.

Backend plugins in mise extend the standard tool plugin system to manage multiple tools using the plugin:tool format. They're perfect for:

• Package managers (npm, pip, cargo, gem)
• Tool families (multiple related tools from one ecosystem)
• Custom installations that need to manage many tools

Unlike tool plugins that manage one tool, backend plugins can install and manage multiple tools like npm:prettier, npm:eslint, cargo:ripgrep, etc.

1. Click "Use this template" button on GitHub
2. Name your repository (e.g., mise-mybackend or vfox-mybackend)
3. Clone your new repository
4. Follow the setup instructions below

git clone https://github.com/jdx/mise-backend-plugin-template mise-mybackend
cd mise-mybackend
rm -rf .git
git init

Search and replace these placeholders throughout the project:

• <BACKEND> → your backend name (e.g., npm, cargo, pip)
• <GITHUB_USER> → your GitHub username or organization
• <TEST_TOOL> → a real tool name your backend can install (for testing)

Files to update:

• metadata.lua - Update name, description, author, homepage
• hooks/*.lua - Replace placeholders and implement your backend logic
• mise-tasks/test - Update test tool name and commands
• README.md - Update this file with your backend's information

Backend plugins require three main hooks:

Lists available versions for a tool in your backend.

function PLUGIN:BackendListVersions(ctx)
    local tool = ctx.tool
    -- Your logic to fetch versions for the tool
    -- Return: {versions = {"1.0.0", "1.1.0", "2.0.0"}}
end

Examples:

• API-based: Query npm registry, PyPI, crates.io APIs
• Command-based: Run npm view <tool> versions, pip index versions <tool>
• File-based: Parse registry files or manifests

Installs a specific version of a tool.

function PLUGIN:BackendInstall(ctx)
    local tool = ctx.tool
    local version = ctx.version  
    local install_path = ctx.install_path
    -- Your logic to install the tool
    -- Return: {}
end

Examples:

• Package manager: npm install <tool>@<version>, pip install <tool>==<version>
• Download & extract: Download binary/archive and extract to install_path
• Build from source: Clone repository, checkout version, build and install

Sets up environment variables for a tool.

function PLUGIN:BackendExecEnv(ctx)
    local install_path = ctx.install_path
    -- Your logic to set up environment
    -- Return: {env_vars = {{key = "PATH", value = install_path .. "/bin"}}}
end

Examples:

• Basic: Add bin/ directory to PATH
• Complex: Set tool-specific environment variables, library paths
• Ecosystem-specific: Like node_modules/.bin for npm, site-packages for Python

Your backend may need to handle different operating systems:

-- Available in all hooks via RUNTIME object
if RUNTIME.osType == "Darwin" then
    -- macOS-specific logic
elseif RUNTIME.osType == "Linux" then  
    -- Linux-specific logic
elseif RUNTIME.osType == "Windows" then
    -- Windows-specific logic
end

Provide meaningful error messages:

function PLUGIN:BackendListVersions(ctx)
    local tool = ctx.tool
    
    if not tool or tool == "" then
        error("Tool name cannot be empty")
    end
    
    -- ... your implementation ...
    
    if #versions == 0 then
        error("No versions found for " .. tool)
    end
    
    return {versions = versions}
end

1. Install pre-commit hooks (optional but recommended):

hk install

This sets up automatic linting and formatting on git commits.

1. Link your plugin for development:

mise plugin link --force <BACKEND> .

2. Test version listing:

mise ls-remote <BACKEND>:<some-tool>

3. Test installation:

mise install <BACKEND>:<some-tool>@latest

4. Test execution:

mise exec <BACKEND>:<some-tool>@latest -- <some-tool> --version

5. Run tests:

mise run test

6. Run linting:

mise run lint

7. Run full CI suite:

mise run ci

This template uses hk for modern linting and pre-commit hooks:

• Automatic formatting: stylua formats Lua code
• Static analysis: luacheck catches Lua issues
• GitHub Actions linting: actionlint validates workflows
• Pre-commit hooks: Runs all checks automatically on git commit

Manual commands:

hk check      # Run all linters (same as mise run lint)
hk fix        # Run linters and auto-fix issues

Enable debug output:

mise --debug install <BACKEND>:<tool>@<version>

• metadata.lua – Backend plugin metadata and configuration
• hooks/backend_list_versions.lua – Lists available versions for tools
• hooks/backend_install.lua – Installs specific versions of tools
• hooks/backend_exec_env.lua – Sets up environment variables for tools
• .github/workflows/ci.yml – GitHub Actions CI/CD pipeline
• mise.toml – Development tools and configuration
• mise-tasks/ – Task scripts for testing
• hk.pkl – Modern linting and pre-commit hook configuration
• .luacheckrc – Lua linting configuration
• stylua.toml – Lua formatting configuration

-- backend_list_versions.lua
function PLUGIN:BackendListVersions(ctx)
    local cmd = require("cmd")
    local json = require("json")
    local result = cmd.exec("mypm view " .. ctx.tool .. " versions --json")
    return {versions = json.decode(result)}
end

-- backend_install.lua  
function PLUGIN:BackendInstall(ctx)
    local cmd = require("cmd")
    cmd.exec("mypm install " .. ctx.tool .. "@" .. ctx.version .. " --prefix " .. ctx.install_path)
    return {}
end

-- backend_exec_env.lua
function PLUGIN:BackendExecEnv(ctx)
    return {
        env_vars = {
            {key = "PATH", value = ctx.install_path .. "/bin"}
        }
    }
end

-- backend_list_versions.lua
function PLUGIN:BackendListVersions(ctx)
    local http = require("http")
    local json = require("json")
    local resp = http.get({url = "https://api.github.com/repos/owner/" .. ctx.tool .. "/releases"})
    local releases = json.decode(resp.body)
    local versions = {}
    for _, release in ipairs(releases) do
        table.insert(versions, release.tag_name:gsub("^v", ""))
    end
    return {versions = versions}
end

-- backend_install.lua
function PLUGIN:BackendInstall(ctx)
    local platform = RUNTIME.osType:lower()
    local arch = RUNTIME.archType
    local url = "https://github.com/owner/" .. ctx.tool .. "/releases/download/v" .. ctx.version .. 
                "/" .. ctx.tool .. "-" .. platform .. "-" .. arch .. ".tar.gz"
    
    local http = require("http")
    local temp_file = ctx.install_path .. "/tool.tar.gz"
    http.download({url = url, output = temp_file})
    
    local cmd = require("cmd")
    cmd.exec("cd " .. ctx.install_path .. " && tar -xzf tool.tar.gz")
    cmd.exec("rm " .. temp_file)
    return {}
end

• vfox-npm - Backend for npm packages
• Study existing mise backends: npm, cargo, pip, gem

Backend plugins have access to these built-in modules:

• cmd - Execute shell commands
• http - HTTP client for downloads and API calls
• json - JSON parsing and encoding
• file - File system operations

1. Ensure all tests pass: mise run ci
2. Create a GitHub repository for your plugin
3. Push your code
4. Test with: mise plugin install mybackend https://github.com/user/mise-mybackend
5. (Optional) Request to transfer to mise-plugins organization
6. Add to the mise registry via PR

• Backend Plugin Development - Complete guide
• Backend Architecture - How backends work
• Lua modules reference - Available modules
• mise-plugins organization - Community plugins

MIT