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. 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: 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. The public surface is kept deliberately small.

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. 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
  • History: ctx.services.versions (PluginVersionsService) and its version pins (PluginVersionPins, PluginVersionPinHolder, PluginVersionPin, PluginPinOptions, PluginPinTransaction, VersionPinHolderDefinition, VersionRef), which plugin-page-builder depends on
  • 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 (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 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)
  • 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, and onMigrate, called by nextly migrate once it leaves nothing pending
  • 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: ctx.filters / ctx.actions + seam types
  • Secrets: secret, Secret, isSecret
  • Client UX (@nextlyhq/plugin-sdk/client): useCan, <Can>
  • Admin dashboard widgets (defineWidget under contributes.dashboard — rendered; shape still settling)
  • contributes.events, dependsOn / optionalDependsOn, plugin.rename
  • 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 (a PostgreSQL schema other than public)
  • 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: 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.

Seeing experimental use when you lint

@nextlyhq/eslint-plugin's no-experimental-sdk rule names each experimental surface your plugin uses, where you use it, so adopting one is a choice you make knowingly rather than something an upgrade tells you about. A scaffolded plugin has it already: nextly.configs.recommended turns it on as a warning.

src/plugin.ts
  3:10  warning  `getCachedNextly` from `@nextlyhq/plugin-sdk` is experimental: it may
                 change or be removed in any release, with no deprecation period.
                 Pin your Nextly version, or see https://nextlyhq.com/docs/plugins/stability

What counts as experimental comes from the SDK's own stability ledger, read when the rule is published, so a surface that graduates stops being flagged in the next release with nothing for you to change.

By default the rule checks what you import from the SDK. To also check members of the plugin context, such as ctx.db, turn on context. It follows the context from a lifecycle's first parameter (init(ctx)) and from anything you annotate PluginContext, but not through other names you pass it on as. List the surfaces you have adopted on purpose in allow, by export name or by context path:

// eslint.config.mjs
export default [
  ...nextly.configs.recommended,
  {
    rules: {
      "@nextlyhq/no-experimental-sdk": [
        "warn",
        { context: true, allow: ["db", "getCachedNextly"] },
      ],
    },
  },
];

Deprecation policy

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

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.