Skip to content

Run your plugin locally

Use the starter’s development workflow to test the same release artifacts Phials will eventually install for users. The everyday loop is:

edit → npm run dev:install → Reload in Phials → try the change

dev:install builds before installing and uses your normal Phials home by default. Run npm run check and npm test when you want type checking and automated tests too.

Do not treat a successful build, an Enabled badge, or a notification by itself as proof that the complete plugin is running.

Start with the first-plugin path

If you have not run a plugin yet, follow Build your first plugin. It establishes a stable ID, builds the starter artifacts, and proves one command.

Return here for the complete loop:

  1. Install a development plugin locally into your normal home, or optionally choose a separate home for isolated tests.
  2. Rebuild and reload plugin changes without restarting the app.
  3. Test activation, restart, and persisted state across lifecycle boundaries.

Know the four runtime states

State Meaning Direct evidence
Installed A valid release directory exists under the active Phials Home. The plugin appears under Settings → Plugins → Community plugins → Installed with the expected ID and version.
Enabled The active Phials Home records that the plugin may run. The Installed card shows Enabled and no permission review is pending.
Loaded Phials imported main.js and accepted its module shape and identity. The card has no load diagnostic; a load failure identifies the import, export, or identity problem before activation.
Activated Phials registered the plugin’s capabilities and onActivate completed. An activation probe and one representative capability both work.

Each later state depends on the earlier ones. A plugin can be installed but disabled, enabled but unable to load, or loaded but unable to activate.

Use one active Phials Home

Phials home contains plugin files, settings, and app data. Normally the installer and Phials both use the platform default, so no setup is needed. If you choose another home with PHIALS_HOME or --phials-home, make sure the installer and Phials use the same directory.

Use an isolated home when testing:

  • permission changes
  • first-run safe mode
  • destructive plugin settings or data migrations
  • repeated uninstall and reinstall
  • incompatible or intentionally broken artifacts

Do not run two Phials processes against the same development home at once.

Keep the loop observable

Give every development change a visible proof:

  • a changed command label
  • a version or build marker in a development-only interface
  • a changed viewer state
  • a lifecycle notification used only while debugging

Verify both presence and absence. After reload, the new result should appear and the old result should be gone.

If a gate fails, stop at that boundary. Use Fix a plugin that will not load or activate rather than changing unrelated code.

This article includes AI-assisted content.

Documentation is licensed under CC BY 4.0. Phoundry names and marks remain reserved.