Managing Plugins

Accent CMS provides CLI commands to manage plugins without editing files manually, plus development conveniences that keep a broken plugin from taking the site down.

Managing Plugins (CLI)

Scaffolding a New Plugin

accent plugin new my-plugin --lang rust   # or: --lang js

Creates a my-plugin/ directory containing a complete, buildable content-hook plugin in the chosen language, including the slice of the WIT contract it needs. The command prints the build steps for the toolchain you picked. See Writing a Plugin for the full walkthrough.

Listing Installed Plugins

accent plugin list

Displays a summary table of all installed plugins:

NAME                      VERSION    HOOKS                FILTERS    ROUTES
---------------------------------------------------------------------------
syntax-highlight          0.2.0      on_render            1          0
contact-form              1.0.0      none                 0          1

Inspecting a Plugin

accent plugin info syntax-highlight

Shows detailed metadata: name, version, API version, description, registered hooks, filters, routes, shortcodes, and configuration.

Installing from the Registry

# Install the latest version
accent plugin install syntax-highlight

# Install a specific version
accent plugin install syntax-highlight@0.2.0

Downloads the plugin from the configured registry, verifies the SHA-256 checksum, and places it in the plugins directory. If a plugin with the same name is already installed, you must remove it first.

The configured registry defaults to the Hub – the signed index of plugins, themes, and starter templates. Browse it to see what a name resolves to before you install it; plugins.registry_url in config.yaml points somewhere else if you run your own.

Installing a plugin does not switch the plugin system on. A project that leaves plugins.enabled unset – which the starter template does – loads nothing: the files are on disk and verified, but no hook runs, the plugin’s routes 404 and any island it provides never hydrates. The install says so rather than leaving you to find out:

Note: plugins are not enabled for this project, so this one will not load.
      Set `plugins.enabled: true` in config.yaml.

It is a note and not a refusal – installing into a project you intend to enable later is perfectly reasonable. See Configuration Reference for the block.

To go the other way – turning a plugin, theme, or starter template of your own into something installable – see Publishing Artifacts.

Removing a Plugin

accent plugin remove syntax-highlight

Deletes the plugin directory and all its contents. The plugin must be reinstalled to use it again.

Custom Config Path

All plugin commands accept --config to specify a config file (for resolving the plugins directory):

accent plugin --config prod.yaml list

Hot Reload

When dev.hot_reload is enabled, plugin WASM files are watched for changes. Modifying a .wasm file triggers an automatic reload of that plugin without restarting the server. Template filters provided by plugins are re-registered after reload.

The replacement is compiled before the running plugin is swapped out, which has two consequences worth knowing while you iterate:

  • A save that does not compile changes nothing. The error is logged and the previously loaded version of the plugin keeps handling requests, so a half-written build never leaves a gap where the plugin’s routes, filters, or shortcodes are missing.
  • Requests keep being served during the recompile. Pages that use other plugins (or none) are not blocked while your plugin is rebuilt.

Graceful Error Handling

The plugin system is designed to be resilient:

  • Missing plugins directory: The server starts normally with no plugins loaded
  • Invalid plugin.toml: The plugin is skipped with a warning; other plugins still load
  • Missing plugin.wasm: The plugin is skipped with a warning
  • WASM load failure: The plugin is skipped; the server continues
  • Failed hot reload: The previously loaded version of the plugin stays live
  • Runtime errors: Plugin errors are logged; original content is preserved

This means a broken plugin will never prevent your site from serving content.