Skip to content
Verified

What a plugin is

A plugin is an npm package that installs into one Xuda project and extends it with code that runs in the browser, in Studio, or on the server.

A Xuda plugin is a scoped npm package (@xuda.io/<name> for first-party plugins, any scope for a third party) that a project installs to add capability: a UI component, a code library callable from Studio, a database socket, a UI framework, or an icon set. Every plugin under plugins/@xuda.io/ in this repo is one, and the same shape works for a plugin published from outside the monorepo.

The moving pieces

The package on disk

A plugin is a normal npm package: package.json plus whichever of the six manifest files (see the manifest) it ships. plugins/@xuda.io/<name> in this repo is the working copy for the first-party plugins; a third party writes and publishes the same shape from their own repo.

The catalog document

Uploading a plugin (upload_plugin) writes one document to the xuda_plugins database, keyed by the package name. That document is both the install source (its manifest, version and package_source say what to fetch and what the package actually ships) and the marketplace listing (label, plugin_description, tags, icon, visibility, stat) for the exact same plugin. There is no separate listing record to keep in sync.

The project install

Installing a plugin into a project (install_plugin) does three things: it npm-installs the package into that project's own node_modules (under plugins_drive_path, one tree per project, not a shared global install), it records the plugin under the project's app_plugins_purchased map (installed, version, manifest, plugin_type), and it flags the project as needing a rebuild (set_update_required_to_app).

Where a plugin's code actually runs

A plugin can ship code for up to three different places, and it only runs where the file exists:

  • In the browser, inside every published app that has the plugin installed, via runtime.mjs. This is a UI plugin's fn(plugin_name, element, properties), called once per element the plugin is attached to.
  • On the server, inside the project, via server.mjs. This is where a library plugin's methods are actually implemented, and where a data (dbs) plugin talks to its backing store.
  • Inside Studio itself while the project is being built, via studio.mjs. A dbs plugin uses this to run its own live queries against the Studio table view.

The install consent screen a user sees before installing a plugin is built directly from which of these files the plugin's manifest says it ships, which is why the manifest is the plugin's contract with the person installing it, not just a build artifact.

Next