DOCSEARCHbyAlgolia
Submit Docs

mise-vscode

repository·main·Indexed 42 days ago

https://github.com/hverlin/mise-vscode

A Visual Studio Code extension that integrates the mise tool version manager, environment variable manager, and task runner directly into the editor. It provides automatic loading of environment variables from mise.toml, sidebar management for tools, and the ability to orchestrate other VS Code extensions (such as Go, Java, Deno, Bun, and Flutter) to use mise-managed binaries.

Tokens
19.9K
Snippets
54
Records
110
Agent score
51%

What's inside mise-vscode

  1. Overview of mise VS Code features

    main

    The mise-vscode extension provides deep integration with mise within Visual Studio Code through several key capabilities:

    • Tool Management: View, install, remove, or switch versions of mise tools directly in the editor. The extension can automatically configure other VS Code extensions to use these tools.
    • Task Runner: Run tasks defined in mise.toml via the command palette, activity bar, or directly from the file. Includes visual dependency graphs and task snippets.
    • Environment Variables: View and navigate to definitions for environment variables loaded from mise.toml files.
    • mise.toml Language Support: Provides syntax highlighting, autocompletion, go-to-definition, and find references for mise.toml, including support for Tera templates.
    • VS Code Integration: Use mise tasks within launch.json configurations and benefit from automatic tool configuration for supported VS Code extensions.

  2. Manage task output cache

    main

    For tasks with cache = { enabled = true } (requires mise 2026.8.1+), the extension provides a Cache code lens next to the Run action. This allows you to:

    • View the size of stored entries.
    • Explain cache key: Use Mise: Explain task cache key to see what feeds the key without running the task.
    • Run without cache: Use Mise: Run task without its output cache.
    • Clear cache: Use Mise: Clear task output cache to remove entries.

    Task hovers also report cache status (hits/misses and last used time).

  3. Configure automatic loading of environment variables

    main

    The extension automatically loads environment variables provided by mise and updates the VS Code process.

    Potential side effects to note:

    • You may see a warning icon indicating a terminal restart is required when environment variables are updated.
    • If using the VS Code terminal, environment variables will persist even if you cd .. out of the project directory (unless automatic loading is disabled).

    Use mise.updateEnvAutomatically to toggle this behavior.

  4. Use and navigate Task Arguments (usage spec)

    main

    The extension supports the usage spec for task arguments via the usage field:

    • Syntax Highlighting: usage = '''...''' blocks are highlighted using KDL.
    • Context-aware Autocompletion: Provides directives (arg, flag, complete) and valid attributes (help, default, choices, count, negate, etc.).
    • Hover Documentation: Provides documentation for directives and attributes.
    • Variable Completion: Typing $ in a multiline run block suggests $usage_* environment variables derived from the task's arguments and flags.

    This support also extends to file tasks, where #USAGE lines get usage spec highlighting/autocompletion and #MISE lines get TOML highlighting for task configuration keys (e.g., description, alias, depends, sources).

    [tasks.deploy]
usage = '''
arg "<environment>" help="Target environment" {
  choices "dev" "staging" "prod"
}
flag "-v --verbose" help="Enable verbose output"
'''
run = '''
echo "Deploying to ${usage_environment?}"
'''

  5. Autocompletion for tools and task dependencies

    main

    mise-vscode provides several autocompletion features:

    • Tools: Tool names and versions are autocompleted in the tools section of mise.toml. In .tool-versions files, backend prefixes (e.g., core:, npm:, cargo:) are autocompleted, and typing a prefix suggests registry tools (e.g., core:node).
    • Task Dependencies: Code completion is provided for depends, depends_post, and wait_for fields.
    • Task Templates: extends = "template_name" completes task templates declared in the current file or parent config files.

  6. How automatic extension configuration works in multi-root workspaces

    main

    When automatic extension configuration is enabled in a multi-root workspace, mise-vscode configures each folder independently based on its own mise configuration file.

    • Folder-level settings: If a target extension supports folder-level settings, each folder will receive its own configuration. For example, if two folders pin different versions of the same tool, they will each receive their specific version settings.
    • Window-level settings: Settings that only exist per window (and cannot be scoped to a folder) are taken from the currently selected workspace folder.

  7. Use task templates for reusable definitions

    main

    Task templates allow you to define reusable logic in a [task_templates.<name>] section. Tasks can inherit from them using extends = "<name>".

    Extension Features for Templates:

    • Autocompletion: Suggests template names in extends and shows declared fields.
    • Hover: Shows the resolved template for an extends declaration.
    • Go to definition: Navigates from extends to the template definition.
    • Find references: Locates all tasks extending a specific template.
    [task_templates."python:build"]
description = "Build a python package"
run = "uv build"
tools = { python = "3.12", uv = "latest" }

[tasks.build]
extends = "python:build"
run = "uv build --wheel" # overrides the template command

  8. Understand mise extension requirements and shell integration

    main

    The mise-vscode extension is optional; you can use mise in VS Code via shims without this extension.

    Key benefits of using the extension include:

    • No shell profile changes required: You do not need to update your default shell's profile script to use the extension.
    • Automatic detection: The extension automatically detects mise even if it is not activated in your shell.
    • Environment loading: mise environment variables are automatically loaded into your current VS Code session.
    • Extension orchestration: It automatically configures other VS Code extensions to use tools provided by mise.

  9. Manage declarative resources in bootstrap

    main

    Starting with mise 2026.8.2, declarative host provisioning resources appear as distinct sections in the Bootstrap panel. Unlike standard sections that track state, these show the intended action: create, update, remove, or unchanged.

    SectionConfigured in
    Secrets[bootstrap.secrets]
    Accounts[bootstrap.users], [bootstrap.groups] (Linux)
    Files[bootstrap.files], [bootstrap.directories]
    Services[bootstrap.services] (Linux)
    Firewall[bootstrap.linux.firewall] (Linux)
    Compose[bootstrap.compose]

    Behavior Notes

    • Unknown State: If mise cannot inspect a resource (e.g., a Linux-only section on macOS, a missing secret, or Docker not running), it is marked as unknown (neutral) rather than pending.
    • Navigation: Selecting an entry in the panel jumps directly to its declaration in your configuration files.
    • Secrets Security: Secrets are listed by name and the environment variable they read from. The extension never reads the actual secret values.

  10. Syntax highlighting for Tool Stubs and Shebangs

    main

    Tool Stubs

    Files using the #!/usr/bin/env -S mise tool-stub shebang are automatically detected and opened as TOML, providing syntax highlighting even without a .toml extension.

    #!/usr/bin/env -S mise tool-stub

version = "2.96.0"
tool = "github:cli/cli"
bin = "bin/gh"

    Script Shebangs

    If you use multi-line task scripts with a shebang, the extension provides syntax highlighting for the following languages:

    • Python, Node.js, Deno, Bun, Ruby, Bash, and Shell.

  11. How environment variables are loaded into VS Code

    main

    The mise-vscode extension automatically loads all environment variables provided by the mise env command into the current VS Code process.

    Key behaviors:

    • Variables are automatically provided to any newly created terminals, even if mise has not been explicitly activated within that terminal.
    • If the environment variables change, existing terminals may become out of sync. A warning sign will appear next to the terminal name in the terminal panel to indicate that a reload is required.

  12. Manage monorepo tasks and workspace projects

    main

    The extension supports mise monorepo tasks (monorepo_root = true, requires mise 2025.10.3+ and experimental = true).

    Key Features:

    • Fully Qualified Names: Tasks are shown as //projects/frontend:build.
    • Dependency Resolution: Supports local (build), explicit same-project (:build), fully qualified (//projects/frontend:build), wildcards (//projects/...:build), and workspace graph dependencies (^build).
    • package.json Integration: In Node workspaces, scripts are exposed as tasks (e.g., node:frontend#test). To enable this, set task.auto_infer = ["node"] in your root mise.toml (requires mise 2026.8.2+).
    • Workspace Graph: Inferred from Node, Cargo, uv, and Go manifests. For Go, you may need to manually declare edges using [monorepo.projects].
    [settings]
experimental = true
task.auto_infer = ["node"]