docs: environment plugins #6702
Merged
Conversation
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
Contributor
There was a problem hiding this comment.
Pull Request Overview
This PR adds comprehensive documentation for environment plugins, a previously underdocumented feature of mise. The changes establish environment plugins as a first-class plugin type with dedicated guidance comparable to tool and backend plugins.
Key Changes:
- Creates a complete environment plugin development guide with examples, best practices, and testing instructions
- Expands the environments documentation to better explain how plugin-provided directives work
- Updates the plugins overview to include environment plugins alongside tool and backend plugins
Reviewed Changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| docs/env-plugin-development.md | New comprehensive guide covering environment plugin creation, structure, examples, and best practices |
| docs/plugins.md | Adds environment plugins section with overview and links to detailed guide |
| docs/environments/index.md | Expands plugin-provided directives section with detailed explanations and practical examples |
Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
|
|
||
| ## Quick Start | ||
|
|
||
| The fastest way to create an environment plugin is to use the [mise-env-plugin-template](https://github.com/jdx/mise-env-sample): |
There was a problem hiding this comment.
The link text says 'mise-env-plugin-template' but the URL points to 'mise-env-sample', and line 382 confirms the correct repository name is 'mise-env-sample'. Either the link text should be 'mise-env-sample' or a separate template repository exists at the URL shown in the text.
Suggested change
| The fastest way to create an environment plugin is to use the [mise-env-plugin-template](https://github.com/jdx/mise-env-sample): | |
| The fastest way to create an environment plugin is to use the [mise-env-sample](https://github.com/jdx/mise-env-sample): |
docs/environments/index.md
Outdated
|
|
||
| ### Creating Environment Plugins | ||
|
|
||
| See [Environment-Only Plugins](/plugins#environment-only-plugins) in the Plugins documentation for a complete guide to creating your own environment plugins. |
There was a problem hiding this comment.
The anchor link '#environment-only-plugins' does not match the actual section heading in docs/plugins.md, which is '## Environment Plugins' (would create anchor '#environment-plugins'). This will result in a broken link.
Suggested change
| See [Environment-Only Plugins](/plugins#environment-only-plugins) in the Plugins documentation for a complete guide to creating your own environment plugins. | |
| See [Environment Plugins](/plugins#environment-plugins) in the Plugins documentation for a complete guide to creating your own environment plugins. |
3d488d2 to
df4245e
Compare
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
Add dedicated "Environment Plugin Development" guide with complete examples and best practices for creating plugins that provide environment variables and PATH modifications without managing tool versions. Changes: - Created docs/env-plugin-development.md: - Complete guide to creating environment plugins - When to use environment plugins vs other plugin types - Directory structure and required files - Full code examples for MiseEnv and MisePath hooks - Best practices (defaults, validation, error handling, caching) - Testing and debugging instructions - Real-world examples (secret managers, dynamic environments) - Migration guide from tool plugins - Updated docs/plugins.md: - Replaced lengthy inline section with concise summary - Links to dedicated env-plugin-development.md page - Maintains consistent structure with backend/tool plugin docs - Expanded docs/environments/index.md: - Better explanation of plugin-provided env._ directives - How the directive system works (step-by-step flow) - Multiple practical examples - Configuration options and ctx.options usage - Cross-references to plugin development guide This addresses the documentation gap where environment plugins existed and worked but were poorly documented, making them hard to discover. References mise-env-sample repository throughout as working example. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
df4245e to
f661219
Compare
Hyperfine Performance
|
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2025.10.13 x -- echo |
18.0 ± 0.4 | 17.4 | 20.4 | 1.00 |
mise x -- echo |
18.1 ± 0.4 | 17.5 | 22.9 | 1.01 ± 0.03 |
mise env
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2025.10.13 env |
17.5 ± 0.5 | 16.8 | 21.9 | 1.00 |
mise env |
18.1 ± 0.7 | 16.9 | 20.9 | 1.04 ± 0.05 |
mise hook-env
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2025.10.13 hook-env |
18.0 ± 0.8 | 17.0 | 22.0 | 1.02 ± 0.08 |
mise hook-env |
17.7 ± 1.1 | 17.0 | 39.6 | 1.00 |
mise ls
| Command | Mean [ms] | Min [ms] | Max [ms] | Relative |
|---|---|---|---|---|
mise-2025.10.13 ls |
15.3 ± 0.4 | 14.7 | 20.1 | 1.00 |
mise ls |
15.3 ± 0.3 | 14.6 | 16.5 | 1.00 ± 0.03 |
xtasks/test/perf
| Command | mise-2025.10.13 | mise | Variance |
|---|---|---|---|
| install (cached) | 199ms | ✅ 105ms | +89% |
| ls (cached) | 63ms | 64ms | -1% |
| bin-paths (cached) | 71ms | 70ms | +1% |
| task-ls (cached) | 509ms | 481ms | +5% |
✅ Performance improvement: install cached is 89%
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
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.
Summary
Changes
New File:
docs/env-plugin-development.mdComplete guide for creating environment plugins:
Updated:
docs/plugins.mdenv-plugin-development.mdpageUpdated:
docs/environments/index.mdExpanded "Plugin-provided env._ Directives" section:
ctx.optionsusage patternsProblem This Solves
Environment plugins existed and worked in mise but were poorly documented:
Test Plan
mise run docs:build)References
🤖 Generated with Claude Code
Note
Adds an Environment Plugin Development guide, expands env._ directive docs with examples, updates plugins overview, and links the new page in the sidebar.
docs/env-plugin-development.mdmetadata.lua,hooks/mise_env.lua,hooks/mise_path.lua), configuration viaenv._.<plugin>, examples (e.g., Vault), best practices, testing, and migration from tool plugins.docs/plugins.mddocs/environments/index.mdenv._Directives” with how it works, configuration viactx.options, and practical examples.docs/.vitepress/config.tsWritten by Cursor Bugbot for commit a7ec1ba. This will update automatically on new commits. Configure here.