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

Plugins

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

  1. Build with tsdown to ESM dist/ (first-party plugins are ESM-only — see the note below).
  2. Set package metadata:
    • "type": "module" and an exports map (include ./admin if you ship admin components, like the scaffold does).
    • "files": ["dist"] so the embedded dev/ playground never publishes.
    • Add the nextly-plugin keyword (this is how plugins are discovered).
    • List nextly (and @nextlyhq/admin/react if you have admin UI) as peerDependencies, and declare a nextly core-compatibility range in your definePlugin (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.
  3. 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.

  • export is required: a JavaScript name, or default.
  • call is false unless given. call: true with no options writes acmePlugin().
  • options need call: true. Each has a description, which the prompt shows, and a format: text (the default) or url, a full https:// or http:// 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-plugin keyword.
  • 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-plugin topic.

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.