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:
contributesis read first (without running your plugin) — the host folds your schema, permissions, routes, and admin contributions into the merged config.contributes.transformsrun once everything is merged, so they can change entities other plugins declared (see Change entities you don't own).setup(config)runs for every plugin before anyinit— so a plugin can adjust config that a later plugin'sinitrelies on.init(ctx)runs once services are live. This is where you do runtime work.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 neitherinitnordestroy: 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"). Usectx.nextlyVersionor 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 existPrereleases (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__draftsA 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-runA 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.
Security helpers
Core's helpers for the people a plugin signs in itself — passwords, opaque secrets, and one-purpose links and codes — with their guarantees and bounds.
Data access (ctx.services)
Read and write data from a plugin through the managed, secure-by-default service layer — queries, bulk operations, and system elevation.