docs: improve plugin documentation with comparisons and template links #7962
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,19 +1,52 @@ | ||
| # asdf Backend | ||
|
|
||
| ::: warning | ||
| asdf plugins are considered legacy. For new tools, prefer [vfox plugins](/dev-tools/backends/vfox.html) which are written in Lua, work cross-platform (including Windows), and have access to built-in modules for HTTP, JSON, HTML parsing, and more. | ||
| ::: | ||
|
|
||
| `asdf` is the original backend for mise. | ||
|
|
||
| It relies on asdf plugins for each tool. asdf plugins are more risky to use because they're typically written by a single developer unrelated to the tool vendor. They also generally do not function on Windows because they're written | ||
| in bash which is often not available on Windows and the scripts generally are not written to be cross-platform. | ||
|
|
||
| asdf plugins are not used for tools inside the [registry](https://github.com/jdx/mise/blob/main/registry/) whenever possible. Sometimes it is not possible to use more secure backends like aqua/github because tools have complex install setups or need to export env vars. | ||
|
|
||
| All of these are hosted in the mise-plugins org to secure the supply chain so you do not need to rely on plugins maintained by anyone except me. | ||
|
|
||
| Because of the extra complexity of asdf tools and security concerns we are actively moving tools in | ||
| the registry away from asdf where possible to backends like aqua and github which don't require plugins. | ||
| That said, not all tools can function with github/aqua if they have a unique installation process or | ||
| need to set env vars other than `PATH`. | ||
|
|
||
| ## Feature Comparison: asdf vs vfox | ||
|
|
||
| | Feature | asdf Plugins | vfox Plugins | | ||
| | ------------------------------- | ------------------ | -------------------- | | ||
| | **Language** | Bash scripts | Lua | | ||
| | **Windows Support** | ❌ | ✅ | | ||
| | **Built-in HTTP module** | ❌ (requires curl) | ✅ | | ||
| | **Built-in JSON module** | ❌ (requires jq) | ✅ | | ||
| | **Built-in HTML parsing** | ❌ | ✅ | | ||
| | **Built-in archive extraction** | ❌ | ✅ | | ||
| | **Built-in semver module** | ❌ | ✅ | | ||
| | **Built-in logging** | ❌ | ✅ | | ||
| | **Post-install hooks** | ❌ | ✅ | | ||
| | **Security attestations** | ❌ | ✅ (cosign, SLSA) | | ||
| | **Multi-tool plugins** | ❌ | ✅ (backend plugins) | | ||
| | **Lock file support** | ❌ | ✅ | | ||
| | **Rolling version checksums** | ❌ | ✅ | | ||
|
|
||
| ## Hook Migration: asdf to vfox | ||
|
|
||
| | asdf Script | vfox Hook | Notes | | ||
| | --------------------------- | ------------------------ | ---------------------------------------------------------------- | | ||
| | `bin/list-all` | `Available` | Return structured version objects instead of plain text | | ||
| | `bin/download` | `PreInstall` | Return URL and checksum; mise handles the download | | ||
| | `bin/install` | `PostInstall` | Runs after mise downloads and extracts the tool | | ||
| | `bin/exec-env` | `EnvKeys` | Return structured key/value pairs instead of `export` statements | | ||
| | `bin/list-legacy-filenames` | `PLUGIN.legacyFilenames` | Set in `metadata.lua` instead of a script | | ||
| | `bin/parse-legacy-file` | `ParseLegacyFile` | Return structured result instead of plain text | | ||
|
|
||
| ## Writing asdf (legacy) plugins for mise | ||
|
|
||
| See the asdf documentation for more information on [writing plugins](https://asdf-vm.com/plugins/create.html). |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -488,7 +488,7 @@ The plugin could detect the current git branch and set `ENVIRONMENT=production` | |
|
|
||
| See [Environment Plugins](/plugins#environment-plugins) in the Plugins documentation for a complete guide to creating your own environment plugins. | ||
|
|
||
| For a working example, see the [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template) repository. | ||
|
|
||
| ## Multiple `env._` Directives | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -5,16 +5,16 @@ Plugins in mise are a way to extend `mise` with new functionality like extra too | |
| Historically it was the only way to add new tools (as the only backend was [asdf](/dev-tools/backends/asdf.html)). | ||
|
|
||
| The way that backend works is every tool has its own plugin which needs to be manually installed. However, now with [core tools](/core-tools.html) | ||
| and backends like [aqua](/dev-tools/backends/aqua.html)/[github](/dev-tools/backends/github.html), plugins are no longer necessary to run most tools in mise. | ||
|
|
||
| Tool plugins should be avoided for security reasons. New tools will not be accepted into mise built with asdf/plugins unless they are very popular and | ||
| aqua/github is not an option for some reason. | ||
|
|
||
| The only exception is if the tool needs to set env vars or has a complex installation process, as plugins can provide functionality like [setting env vars globally](/environments/#plugin-provided-env-directives) without relying on a tool being installed. They can also provide [aliases for versions](/dev-tools/aliases.html#aliased-versions). | ||
|
|
||
| If you want to integrate a new tool into mise, you should either try to get it into the [aqua registry](https://mise.jdx.dev/dev-tools/backends/aqua.html) | ||
| or see if it can be installed with [github](https://mise.jdx.dev/dev-tools/backends/github.html). Then add it to the [registry](https://github.com/jdx/mise/blob/main/registry/). | ||
| Aqua is definitely preferred to github as it has better UX and more features like slsa verification and the ability to use different logic for older versions. | ||
|
|
||
| You can manage all installed plugins in `mise` with [`mise plugins`](/cli/plugins.html). | ||
|
|
||
|
|
@@ -93,7 +93,7 @@ Unlike tool plugins, environment plugins: | |
| - Are activated via `env._.<plugin-name>` syntax | ||
| - Don't manage tool versions or installations | ||
|
|
||
| See [Environment Plugin Development](env-plugin-development.md) for creating environment plugins. The [mise-env-plugin-template](https://github.com/jdx/mise-env-plugin-template) repository provides a ready-to-use starting point. | ||
|
|
||
| ## General Plugin Usage | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,5 +1,9 @@ | ||
| # Tool Plugin Development | ||
|
|
||
| ::: tip | ||
| The [mise-tool-plugin-template](https://github.com/jdx/mise-tool-plugin-template) provides a ready-to-use starting point with LuaCATS type definitions, stylua formatting, and hk linting pre-configured. | ||
| ::: | ||
|
|
||
| Tool plugins use a hook-based architecture to manage individual tools. They are compatible with the standard vfox ecosystem and are perfect for tools that need complex installation logic, environment configuration, or legacy file parsing. | ||
|
|
||
| ## What are Tool Plugins? | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -66,7 +66,7 @@ If you leave out the version, then mise will default to `node@latest`. | |
|
|
||
| ## Dev Tool Backends | ||
|
|
||
| Tools are installed with a variety of backends like `asdf`, `github`, or `vfox`. See [registry](/registry.html) for | ||
| the full list of shorthands like `node` you can use. | ||
|
|
||
| You can also use other backends like `npm` or `cargo` | ||
|
|
||
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This sentence is redundant as the same information is presented in more detail in the
tipblock that follows. To improve clarity and reduce repetition, I suggest removing this line and the following blank line, letting thetipblock introduce the template.