You're reading docs for Nextly Alpha. APIs may change between releases.

Plugins

Lifecycle, dependencies & order

How and when a plugin runs — the setup/init/destroy lifecycle, load order, declaring dependencies on other plugins, version compatibility, and enabling/disabling.

This page covers when a plugin's code runs, in what order, and how to express ordering and version constraints. For the errors these rules produce, see the error reference.

The lifecycle: contributes → setup → init → destroy

definePlugin({
  name: "@acme/nextly-plugin-thing",
  version: "1.0.0", // your plugin's semver (used by others' dependsOn ranges)
  nextly: ">=0.0.2-alpha.63", // core-compat range (see Version compatibility)
  contributes: {
    /* declarative nouns: collections, extend, permissions, routes, admin, events */
  },
  setup(config) {
    // Escape-hatch config transform. ALL plugins' setup() run before ANY init().
    // Don't mutate — spread and return a new object.
    return { ...config };
  },
  async init(ctx) {
    // Runtime wiring: subscribe to events, register hooks, read/write via ctx.services.
  },
  async destroy(ctx) {
    // Teardown on shutdown, re-registration and test teardown. Undo anything init() set up.
  },
});

Phase order:

  1. contributes is read first (without running your plugin) — the host folds your schema, permissions, routes, and admin contributions into the merged config. contributes.transforms run once everything is merged, so they can change entities other plugins declared (see Change entities you don't own).
  2. setup(config) runs for every plugin before any init — so a plugin can adjust config that a later plugin's init relies on.
  3. init(ctx) runs once services are live. This is where you do runtime work.
  4. destroy(ctx) runs, in reverse init order, on shutdown (nextly.shutdown()), when a failed start is rolled back, before services register again, and on test teardown. A config hot reload runs neither init nor destroy: a running plugin keeps running, and a change to either takes effect on the next start. Always clean up here — a subscription or timer left behind outlives the plugin and breaks tests.

Load order

Plugins are run in a topological sort over their declared dependencies, so a plugin always initializes after the plugins it depends on. When two plugins have no dependency relationship, their array order in defineConfig({ plugins: [...] }) breaks the tie.

import { defineConfig } from "nextly";

export default defineConfig({
  // a runs before b (array order), unless dependsOn says otherwise
  plugins: [a(), b()],
});

A dependency cycle is a fail-fast boot error (PLUGIN_RESOLUTION_ERROR, reason: "dependency-cycle").

Dependencies

Declare dependencies on other plugins by package name → version range:

definePlugin({
  name: "@acme/nextly-plugin-reports",
  version: "1.0.0",
  nextly: ">=0.0.2-alpha.63",
  // Hard requirement: must be installed and in-range, and inits first.
  dependsOn: { "@acme/nextly-plugin-core": "^2" },
  // Enhance-if-present: fine if absent; if present it must be in-range and inits first.
  optionalDependsOn: { "@acme/nextly-plugin-search": "^1" },
});
  • dependsOn. A missing dependency, or one whose installed version is outside the range, is a fail-fast boot error (reason: "missing-dependency" / "version-incompatible").
  • optionalDependsOn. An absent optional dependency is fine; a present but out-of-range one fails fast (reason: "optional-version-incompatible"). Use ctx.nextlyVersion or feature checks to branch on whether an optional dep is active. An admin contribution to one of its places is drawn while it runs, and left out, without stopping the app, while it is absent or disabled.

If your plugin extends or relates to another plugin's entity, you must declare a dependsOn on it — otherwise you get NEXTLY_SCHEMA_CROSS_PLUGIN_RELATION.

Version compatibility

Every plugin declares the core range it supports via nextly. It's checked at boot; an out-of-range core is a fail-fast error (reason: "core-incompatible" / "invalid-nextly-range").

nextly: ">=0.0.2-alpha.63", // a range may span multiple majors once they exist

Prereleases (alpha/beta) count as in-range. For runtime feature-detection, read ctx.nextlyVersion rather than branching on the declared range.

Enabling & disabling

enabled defaults to true. Setting it to false skips the plugin's behavior (init, hooks, events, routes, admin UI) but still applies its declarative schema — so disabling a plugin doesn't drop its tables or strand its data. This lets an integrator turn a plugin's behavior off without a destructive schema change.

definePlugin({
  name: "@acme/nextly-plugin-thing",
  version: "1.0.0",
  nextly: ">=0.0.2-alpha.63",
  enabled: false,
});

To actually remove a plugin's tables and data, run nextly plugins uninstall <name> while it is still in the config, then remove it — see Schema & data lifecycle.

Install and uninstall hooks

onInstall and onUninstall (@experimental) are for work that belongs to installing or removing the plugin rather than to every start: seeding a row, registering with an external service, deregistering from it. They never run at boot.

import { definePlugin } from "@nextlyhq/plugin-sdk";

export default definePlugin({
  name: "@acme/nextly-plugin-thing",
  version: "1.0.0",
  nextly: ">=0.0.2-alpha.67",
  async onInstall(ctx) {
    // After the plugin's migrations, so its tables exist.
    ctx.logger.info("installed");
  },
  async onUninstall(ctx, { keepData }) {
    // Before its DOWN migrations, so its tables are still readable.
    ctx.logger.info(keepData ? "uninstalled, data kept" : "uninstalled");
  },
});

nextly plugins install <name> applies the plugin's pending migration modules and then calls onInstall; nextly plugins uninstall <name> calls onUninstall and then runs the DOWN of each applied module, newest first. Each boots the app from your config to build the hook's context, and only when the plugin declares the hook. Write both so they can run again: an install that failed part-way is repaired by running it again, which calls onInstall again, and an uninstall that stopped part-way is finished by running it again, which calls onUninstall again. Once an install has finished, running it again calls no onInstall and records no second install: it applies only the migration modules, permissions and roles an upgraded package added (see Installing). A plugin counts as installed only once nextly plugins install has finished on that database: a production boot refuses it before then while it is enabled, and so does the install of a plugin that depends on it. nextly plugins install --all installs every enabled plugin in your config, its dependencies first, and stops at the first that fails. nextly plugins add <package> runs this install as its last step, after it has added the plugin to your config and to your build (see Adding a Plugin).

The permissions and roles an install and an uninstall write

nextly plugins install <name> adds the permissions and roles the plugin declares, and sets every preset role's grants (Admin, Editor, Author, Viewer) by this release's presets with the record of the release that set them, as nextly migrate from the same release does (see The preset grants and the release that set them). It writes them in the same transaction that records the plugin installed, under the schema lock, so a plugin a production boot serves always has them, whether or not a nextly migrate follows. An install that stops part-way records none of them. Only the installed plugin's own permissions are added: the permissions of a collection or Single it contributes come with that entity's registry row, through nextly migrate, and until then the entity is not served. If the preset grants cannot be set, the install fails and nothing is recorded; run it again once the cause is fixed.

nextly plugins uninstall <name>, with or without --keep-data, marks the plugin's permissions as no longer declared in the same transaction that records it uninstalled, and logs each with the roles that hold it. It changes no grant: the permissions leave the role editor and the preset roles' choices and enforce nothing, but a role that held one still holds it. Installing the plugin again clears the marks, and the grants are as they were. A nextly migrate with the plugin still in your config leaves them as they are: it adds the permissions and roles only of plugins recorded installed, and of plugins no install or uninstall has recorded yet.

In production (any mode but development), both commands refuse, before changing anything, when the database records that a newer Nextly release set the preset grants: the message names that release, and the command succeeds when run from it or a newer one. In development the install goes on and leaves the preset grants as the newer release set them.

A pending module that deletes data needs the data-loss consent before the install applies anything, exactly as nextly migrate asks for it. The install lists each module above what it deletes. At a terminal it asks once. Without a terminal it is refused, with nothing changed, unless --accept-data-loss (alone, or naming each table or table.column) or NEXTLY_ACCEPT_DATA_LOSS covers every deletion:

nextly plugins install @acme/notes --accept-data-loss=acme__drafts

A no at the terminal stops the install with exit code 1, and nothing is changed. With --all, each plugin is judged before its own install changes anything, and the run stops at the first refusal: the plugins installed before it stay installed.

--dry-run on either command shows what it would do and changes nothing: it opens the database read-only, takes no lock, asks no consent and exits 0, naming the refusal a real run would meet. An install names each pending module with what it deletes, and the record it would make; with --all, a plugin is planned as if the installs before it had run. An uninstall names each module's DOWN, the tables and columns it drops (none with --keep-data), and the records it would make. Neither runs onInstall or onUninstall: a hook is plugin code the dry run does not simulate, and it says so.

nextly plugins uninstall @acme/notes --dry-run

A disabled plugin (enabled: false) is not installed, by --all or by name, and a production boot does not require it to be: you can keep a plugin disabled, never installed, and boot. Its tables exist, because its schema still applies, but its onInstall runs only when you enable it and run nextly plugins install <name>. Once you enable it, a production boot refuses it until that install has run. A disabled plugin that was uninstalled, or whose uninstall stopped part way, is still refused, as an enabled one is.

After a migrate

onMigrate (@experimental) is for work a deploy owes once the schema is in step and that no request should wait for, such as filling an index for content that existed before it. nextly migrate calls it after every run that leaves nothing pending, last, after the schema, permissions and roles, translation tables and workflows; so does nextly migrate:fresh. It never runs at boot, in a dry run, or when --step leaves migrations pending, and migrate:create, migrate:status and migrate:check never call it.

import { definePlugin } from "@nextlyhq/plugin-sdk";

export default definePlugin({
  name: "@acme/nextly-plugin-thing",
  version: "1.0.0",
  nextly: ">=0.0.2-alpha.77",
  async onMigrate(ctx, { applied }) {
    // `applied` is how many migrations this run applied; 0 is a run that
    // found nothing to apply, and the hook runs then too.
    ctx.logger.info(`migrated (${applied} applied)`);
  },
});

It runs only for an enabled plugin installed on the database: a first deploy's migrate, before nextly plugins install, skips it and says so. Each plugin's hook runs in a boot of its own, as onInstall does, in which only that plugin initialises. It runs after migrate's lock is released, so two migrates, or a migrate beside a running app, can call it at the same time: write it to be idempotent and safe when run twice at once. If it throws, the next plugin's hook still runs, and the command exits non-zero naming the plugin; the schema the run applied stays applied, and running nextly migrate again runs the hook again.

Inspecting

nextly plugins list           # installed plugins + their contributions
nextly plugins info <name>    # one plugin's details (resolution runs here too)

See also: Author guide · Schema & data lifecycle · Error reference.