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'sfn(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'smethodsare 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. Adbsplugin 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.