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

Plugins

API stability

What's stable vs experimental in the plugin API, the semver guarantee that backs it, and the deprecation policy.

@nextlyhq/plugin-sdk is the stability boundary for the plugin platform (D40/D43). Every export carries a TSDoc release tag — @public, @experimental, or @deprecated — and the authoritative ledger lives in the SDK's STABILITY.md. This page summarizes it.

How a surface becomes stable

Nextly uses a stability ladder (D55): nothing is declared stable on paper. A surface graduates from @experimental to @public only once a first-party plugin has exercised it in production (against a real database, not just the SQLite test harness). ctx.services is the highest-scrutiny surface and was held experimental the longest (D56). The public surface is kept deliberately small (D40).

The semver guarantee

The @public surface is the semver-protected contract. Once Nextly reaches 1.0, breaking a @public export requires a major version bump (D40). During the current 0.x alpha it is stable-in-intent: changes follow the deprecation policy below rather than landing as silent breaks — but pin your versions while we're pre-1.0. @experimental exports carry no compatibility guarantee.

Stable (@public)

  • definePlugin, PluginDefinition, PluginContributions, PluginContext
  • Lifecycle: setup / init / destroy
  • Schema: contributes.collections / extend (+ singles/components)
  • Permissions: PluginPermission, PermissionSlug, AuthUser
  • Data access: ctx.services (incl. { as: "system" }), PluginCollectionService, QueryOptions, PaginatedResult, BatchOperationResult, ServiceOpts. Each service is now a facade of its plugin methods, and collections.withTransaction hands its work a PluginCollectionTransaction token rather than the adapter's transaction context
  • HTTP routes: PluginRoute, PluginRouteContext, PluginRouteHandler, Middleware, RouteMethod
  • Events: EventBus, EventEnvelope, EventHandler, EventName, DocumentEvents / AuthEvents / MediaEvents
  • Collection/field hook context: HookContext
  • Admin: contributes.admin menu/pages/views, ComponentPath, the @nextlyhq/plugin-sdk/admin registration helpers
  • Testing: @nextlyhq/plugin-sdk/testing (createTestNextly)

Still @experimental

These ship today but carry no guarantee yet — use them, but expect change:

  • ctx.db (D56 — prefer ctx.services): the typed, owner-checked surface, and the ctx.db.raw escape hatch, which is the live Drizzle instance only for a plugin that declares capabilities.db.rawSql and that the app lists in db.rawSqlPlugins
  • ctx.dialect — which database the installation runs on
  • ctx.config and its types PluginConfig, PluginSummary and PluginEmailSettings: a frozen copy of the plain configuration values, with no live handles and no email provider credentials, and plugin summaries in place of definitions; FrozenCopy and FrozenValue, which type it readonly all the way down
  • The service facade types PluginUserService, PluginMediaService, PluginEmailService, PluginVersionsService and PluginCollectionTransaction
  • PluginTransaction (the handle ctx.db.transaction passes its work), PluginInsert (what ctx.db.insert takes for a table) and PluginRawDatabase (ctx.db.raw)
  • Version pins on the plugin's own transaction, ctx.services.versions.pins, and their types PluginVersionPins, PluginVersionPinHolder, PluginVersionPin, PluginPinOptions, PluginPinTransaction, VersionPinHolderDefinition and VersionRef
  • PluginMigration.transaction — false runs a migration module outside a transaction, statement by statement
  • onReady, run once per boot after every plugin has initialised and routes are registered, and onInstall / onUninstall, called by nextly plugins install and nextly plugins uninstall, never at boot
  • contributes.transforms — changing entities another plugin declared
  • ctx.db.contributed(table, columns) — reading and writing the hidden columns a plugin contributed to a table it does not own
  • createTestNextly's pluginConsent option
  • ctx.hooks plugin registration (PluginHookRegistry, HookType, HookHandler)
  • The in-transaction hook phase: ctx.hooks.onInTransaction / offInTransaction, InTransactionHandler, InTransactionContext
  • Filters & actions (D63): ctx.filters / ctx.actions + seam types
  • Secrets (D37): secret, Secret, isSecret
  • Client UX (@nextlyhq/plugin-sdk/client): useCan, <Can>
  • Admin dashboard widgets (defineWidget under contributes.dashboard, D22 — rendered; shape still settling)
  • contributes.events, dependsOn / optionalDependsOn, plugin.rename (D54)
  • Schema extensibility: contributes.schema (tables, extend, migrations), the defineTable / col.* DSL, schema.extendTable, schema.adoptTable and db.schema.afterDrizzle
  • Collection db options: db.idType, db.allowIdOnCreate, db.slugPaths
  • db.postgres.schema (accepts only "public" for now)
  • The manifest's declaration of reach: capabilities (net.outbound, db.rawSql, secrets, auth.login), provides and requires
  • The stateful runtime surfaces, each present only once declared: contributes.settings / ctx.settings, capabilities.net.outbound / ctx.fetch, and contributes.audit / ctx.audit
  • The route options rateLimit, limitKey, rawBody, csrf and noStore
  • Auth extensibility (D71/D57): contributes.auth (auth-flow hooks, challenges, sign-in UI), auth.strategies, and finishing an external sign-in with ctx.auth.completeLogin
  • Typed hook points: contributes.hookPoints, ctx.filters.decide and the HookPointPayloads map
  • Admin places: CORE_ADMIN_PLACES, AdminPlaces, AdminPlaceId, CoreAdminPlaceId, PluginAdminPlaceDeclaration and contributes.admin.places
  • Entry-list filters: contributes.admin.filters, PluginListFilterDeclaration and PluginListFilterOption
  • Admin contributions: contributes.admin.contributions, AdminContribution and its kinds, AdminContributionAction, AdminContributionKind, RowPredicate and RowPredicateValue
  • ctx.security: the password helpers, and the opaque and one-purpose secret stores
  • Account events: UserEvents — core emits user.created and user.deleted with { userId } after the change commits; a plugin subscribes and cannot emit either
  • The /db query operators, and collectDeclarations for reading what other plugins declared
  • Sign-in challenge views: ChallengeViewProps, ChallengeResolveResult

Each graduates once a first-party plugin exercises it.

Deprecation policy (D41)

When a @public export must change incompatibly:

  1. It's marked @deprecated with the replacement and removal version.
  2. A one-time runtime warning is emitted at first use where practical.
  3. It keeps working for at least two minor releases after the one that deprecates it, and is removed only at the next major release after those (the support window). Deprecated in 1.3, it still works in 1.4 and 1.5, and 2.0 is the earliest it can be removed; if 2.0 comes before two minor releases have passed, removal waits for 3.0.
  4. A migration guide ships before removal.

Promotion (@experimental → @public) is not a breaking change.

Out of scope for v1

Per D0/D42/D34, v1 is npm-trust: no marketplace, no UI-install, no runtime sandbox or verification. Discovery is npm + these docs + the nextly-plugin keyword — see Publishing & distribution. These are deferred, not cancelled.