Skip to main content

How the Plugin Loader Discovers & Validates Plugins

Your plugin isn't wired in by hand — the plugin loader discovers it at API startup, validates it, and mounts it. Knowing what the loader does (and checks) explains both how a plugin "just works" once its files are in place, and why a subtle mistake makes a plugin silently vanish.

The startup sequence​

The order is strict, and it matters:

  1. The API connects to Postgres.
  2. Core migrations have already run (at deploy time, before the process starts).
  3. Plugin migrations have already run (after core migrations, still before the process starts).
  4. The loader runs inside the API process — discovering, validating, seeding, mounting.

Because migrations run before the loader, by the time the loader checks "does this table exist?", it does. (In local development, you run migrations manually before npm run dev.)

What the loader does per plugin​

At startup, for each plugins/*/manifest.ts it finds, the loader:

  1. reads and validates the manifest;
  2. upserts the entity row from the manifest's identity;
  3. checks entity.is_enabled — if false, the plugin is skipped (no routes, no statuses); to disable a plugin you set this directly in the database;
  4. seeds the workspace statuses into workspace_status with the entity's id;
  5. mounts the routes from createRouter() at /api{apiRoutePrefix};
  6. registers the extension points in memory so the core can call them.

What it validates​

The checks are worth knowing, because failing any one skips your plugin:

  1. the manifest shape — all required fields present and correctly typed;
  2. entity-slug uniqueness across plugins;
  3. workspace-status slug uniqueness within your plugin (cross-plugin collisions are fine — two plugins may both have new);
  4. the declared tables exist (entityObjectTable, joinTable);
  5. the join table has the required columns ({entity_slug}_id, workspace_id, is_deleted, is_archived);
  6. the initial status is in the declared list;
  7. the route prefix doesn't collide with a core route or another plugin.

Fail-safe by design​

If validation fails, your plugin isn't loaded — its routes aren't mounted, its statuses aren't seeded — and the core logs a clear error identifying the failed check. Crucially, the rest of the platform still starts: one broken plugin never brings down the system or the other plugins. On success, the entity is enabled, statuses are seeded, routes are mounted, and your extension points are live.

This is why a mistyped slug or a missing join-table column shows up as "my plugin's routes 404" rather than a crash — start with the troubleshooting guide, and check the startup logs for the validation error.