Skip to content

After Scaffolding a Plugin — What Next? ​

Help query: "I have a scaffolded new plugin what do I do next?" / "Plugin scaffold next steps" / "My new plugin doesn't show up"

Volt does not ship a generator today, but the situation is the same whether you copied hello.rs, duplicated pane.rs, or an external tool dropped a stub module: a file on disk is not enough. The host only sees packages listed from user/lib.rs.

Follow this order.

1. Confirm the module exports package() ​

Your file must expose:

rust
pub fn package() -> PluginPackage { /* ... */ }

At minimum include a unique name, auto_load: true while developing, one command, and optionally a keybinding. See Create a plugin for a full stub.

2. Register the module in user/lib.rs ​

Two edits are required:

rust
pub mod my_plugin; // near the other pub mod lines
rust
pub fn packages() -> Vec<PluginPackage> {
    let mut pkgs = vec![
        // ...
        my_plugin::package(),
    ];
    pkgs.extend(lang::packages());
    pkgs
}

If you only did one of these, the crate may compile while the plugin still never loads.

3. Wire optional host callbacks ​

Ask whether your scaffold needs more than metadata:

FeatureWhere to wire
Buffer evaluate handlerUserLibraryImpl::run_plugin_buffer_evaluator in user/lib.rs
Autocomplete provideruser/autocomplete.rs → backends()
Hover providerHover registration used by your buffer kind
Custom run_volt_commandUserLibraryImpl::run_volt_command if you handle named commands
YAML settingsuser/config.yaml + user/config.rs
Language grammaruser/lang/mod.rs packages() and syntax_languages()

Skipping this step is the usual reason a buffer opens but evaluate / completions do nothing.

4. Build the user package ​

bash
cargo build -p volt-user

From a release User Source Tree:

bash
cargo build --release -p volt-user
# or run workspace.compile inside Volt

Full details: Build the user package.

5. Verify registration ​

bash
cargo run -p volt -- --bootstrap-demo

Confirm your package name appears in the printed list.

Then smoke-test:

bash
cargo run -p volt -- --shell-hidden
cargo run -p volt

Exercise the command from the palette (F3 / :) and any chord you bound.

6. Iterate safely ​

  1. Change Rust → rebuild volt-user (or workspace.compile)
  2. Change YAML/themes → save and rely on hot reload
  3. Before sharing: cargo xtask clippy and cargo xtask test

7. Common "scaffold done but broken" fixes ​

SymptomFix
Package missing from bootstrap demoMissing packages() entry or pub mod
Command missing from paletteRebuild not picked up; wrong library loaded
Keybinding does nothingWrong PluginKeymapScope or Vim mode filter
Evaluate does nothingHandler not matched in run_plugin_buffer_evaluator
Completions missingProvider not added to autocomplete::backends()
Clippy / CI failsRemove todo! / unwrap!; run cargo xtask clippy

More: Troubleshooting.

  1. Plugin concepts — know the vocabulary
  2. Finish registration + build (this page)
  3. Copy patterns from plugin catalog modules closest to your goal (pane for hooks, calculator for buffers, lang/* for languages)
  4. Edit builtins when you are modifying an existing package instead of adding one

Volt — modal editor platform · docs optimized for in-editor help search