Publishing & distribution
How to publish a Nextly plugin, how plugins are discovered, and the trust model behind v1.
Nextly plugins are plain npm packages, registered in code. There is no marketplace, no UI-install, and no runtime sandbox in v1 — distribution and trust ride entirely on npm.
Publish
- Build with
tsdownto ESMdist/(first-party plugins are ESM-only — see the note below). - Set package metadata:
"type": "module"and anexportsmap (include./adminif you ship admin components, like the scaffold does)."files": ["dist"]so the embeddeddev/playground never publishes.- Add the
nextly-pluginkeyword (this is how plugins are discovered). - List
nextly(and@nextlyhq/admin/reactif you have admin UI) as peerDependencies, and declare anextlycore-compatibility range in yourdefinePlugin(e.g.">=0.0.2-alpha.67"). It is checked at boot, and a core outside it refuses to start, so while Nextly is in alpha a range like"^1"matches no release.
npm publish.
// package.json (essentials)
{
"type": "module",
"keywords": ["nextly-plugin"],
"files": ["dist"],
"exports": {
".": { "types": "./dist/index.d.ts", "import": "./dist/index.mjs" },
"./admin": { "types": "./dist/admin.d.ts", "import": "./dist/admin.mjs" },
},
"peerDependencies": { "nextly": "^0.0.2-alpha.67" },
}ESM-only: first-party plugins ship ESM only. CommonJS tooling importing them gets
ERR_PACKAGE_PATH_NOT_EXPORTED. Either keep your consuming tooling ESM, or ship a dual (ESM+CJS) build if you must support CJS consumers.
Declaring how a plugin is added
nextly plugins add <package> installs a plugin and registers it in the site's config in
one step. A package whose entry exports one plugin definition, as it is, needs nothing
more: it is registered as plugins: [thatExport]. A plugin made by calling a function,
or one whose install needs values from the site, says so in its package.json under
nextly.plugin:
// package.json
{
"nextly": {
"plugin": {
// The export that is the plugin; "default" for a default export.
"export": "acmePlugin",
// The export is a function that makes the plugin, called with the options as one object.
"call": true,
// Values the install asks for, written into the config as the call's options.
"options": {
"siteUrl": {
"description": "The site's production address",
"format": "url",
},
},
},
},
}With that, nextly plugins add @acme/plugin --option siteUrl=https://example.com writes
plugins: [acmePlugin({ siteUrl: "https://example.com" })]. Without the option, the
command asks for it in a terminal, and refuses in a script or CI, naming the flag.
exportis required: a JavaScript name, ordefault.callisfalseunless given.call: truewith nooptionswritesacmePlugin().optionsneedcall: true. Each has adescription, which the prompt shows, and aformat:text(the default) orurl, a fullhttps://orhttp://address. Every option listed is asked for.
The command makes the plugin from the declaration before it touches the site's files:
it imports the entry, calls the export with the options, and checks it gets a plugin
definition back. A function that throws on the options it was given refuses the run in
its own words, with the config left as it was. The values land in the site's
nextly.config.ts, which is committed, so never declare a secret as an option: read
secrets from the environment, as below.
Configuration & secrets
Plugin options are passed where the plugin is registered
(defineConfig({ plugins: [myPlugin({ ... })] })). For sensitive values, read from the
environment and wrap them with secret() so they auto-redact in logs, JSON, and
inspection — the real value is only available via .reveal():
import { secret } from "@nextlyhq/plugin-sdk";
myPlugin({ apiKey: secret(process.env.ACME_API_KEY) });secret() is currently @experimental. Never hard-code
secrets in config or commit them.
Discovery
In v1, plugins are found through:
- npm. Search the
nextly-pluginkeyword. - The Nextly docs. First-party and notable community plugins are listed on the plugins index. To get a community plugin listed, see Contributing a plugin.
- GitHub. The
nextly-plugintopic.
There is intentionally no in-app gallery or one-click install yet.
Trust model
v1 is full-trust: a plugin runs with the same access as your application code. There is no sandbox and no verification gate — installing a plugin is exactly as much a trust decision as adding any npm dependency. Vet plugins the way you vet dependencies: read the source, check the maintainer, pin versions.
Sandboxing, verification, and a curated marketplace are deferred to a post-v1 milestone — they're designed-for, not shipped. Until then, trust is npm trust, stated honestly.
See also: API stability · Contributing a plugin.