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), whichplugin-page-builderdepends 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, andcollections.withTransactionhands its work aPluginCollectionTransactiontoken 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.adminmenu/pages/views,ComponentPath, the@nextlyhq/plugin-sdk/adminregistration helpers - Testing:
@nextlyhq/plugin-sdk/testing(createTestNextly)
Still @experimental
These ship today but carry no guarantee yet — use them, but expect change:
ctx.db(preferctx.services): the typed, owner-checked surface, and thectx.db.rawescape hatch, which is the live Drizzle instance only for a plugin that declarescapabilities.db.rawSqland that the app lists indb.rawSqlPluginsctx.dialect— which database the installation runs onctx.configand its typesPluginConfig,PluginSummaryandPluginEmailSettings: a frozen copy of the plain configuration values, with no live handles and no email provider credentials, and plugin summaries in place of definitions;FrozenCopyandFrozenValue, which type it readonly all the way down- The service facade types
PluginUserService,PluginMediaService,PluginEmailServiceandPluginCollectionTransaction PluginTransaction(the handlectx.db.transactionpasses its work),PluginInsert(whatctx.db.inserttakes for a table) andPluginRawDatabase(ctx.db.raw)PluginMigration.transaction—falseruns a migration module outside a transaction, statement by statementonReady, run once per boot after every plugin has initialised and routes are registered, andonInstall/onUninstall, called bynextly plugins installandnextly plugins uninstall, never at boot, andonMigrate, called bynextly migrateonce it leaves nothing pendingcontributes.transforms— changing entities another plugin declaredctx.db.contributed(table, columns)— reading and writing the hidden columns a plugin contributed to a table it does not owncreateTestNextly'spluginConsentoptionctx.hooksplugin 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 (
defineWidgetundercontributes.dashboard— rendered; shape still settling) contributes.events,dependsOn/optionalDependsOn,plugin.rename- Schema extensibility:
contributes.schema(tables,extend,migrations), thedefineTable/col.*DSL,schema.extendTable,schema.adoptTableanddb.schema.afterDrizzle - Collection
dboptions:db.idType,db.allowIdOnCreate,db.slugPaths db.postgres.schema(a PostgreSQL schema other thanpublic)- The manifest's declaration of reach:
capabilities(net.outbound,db.rawSql,secrets,auth.login),providesandrequires - The stateful runtime surfaces, each present only once declared:
contributes.settings/ctx.settings,capabilities.net.outbound/ctx.fetch, andcontributes.audit/ctx.audit - The route options
rateLimit,limitKey,rawBody,csrfandnoStore - Auth extensibility:
contributes.auth(auth-flow hooks, challenges, sign-in UI),auth.strategies, and finishing an external sign-in withctx.auth.completeLogin - Typed hook points:
contributes.hookPoints,ctx.filters.decideand theHookPointPayloadsmap - Admin places:
CORE_ADMIN_PLACES,AdminPlaces,AdminPlaceId,CoreAdminPlaceId,PluginAdminPlaceDeclarationandcontributes.admin.places - Entry-list filters:
contributes.admin.filters,PluginListFilterDeclarationandPluginListFilterOption - Admin contributions:
contributes.admin.contributions,AdminContributionand its kinds,AdminContributionAction,AdminContributionKind,RowPredicateandRowPredicateValue ctx.security: the password helpers, and the opaque and one-purpose secret stores- Account events:
UserEvents— core emitsuser.createdanduser.deletedwith{ userId }after the change commits; a plugin subscribes and cannot emit either - The
/dbquery operators, andcollectDeclarationsfor 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/stabilityWhat 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:
- It's marked
@deprecatedwith the replacement and removal version. - A one-time runtime warning is emitted at first use where practical.
- 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.
- 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.