paseo/public-docs/plugins/publishing.md

title, description, nav, order, category

title	description	nav	order	category
Publish a plugin	Prepare, publish and submit a Paseo plugin to the reviewed registry.	Publishing	45	Plugins

Publish a plugin

Start with a working plugin project. Prepare its listing, publish it on npm or push it to GitHub, then submit it to the registry. After approval, users install the reviewed version with paseo plugin add owner/slug.

1. Prepare your listing page and, for a visual plugin, an interface image.
2. Publish on npm or share through Git.
3. Submit to the plugin registry.

For a private plugin, use direct Git installation or private npm packages.

Your listing page

You can submit without OVERVIEW.md; the reviewer creates a listing page from your README and verified behavior. To maintain the page yourself, put OVERVIEW.md beside paseo-plugin.json and include it in the published package. The scaffold already includes it in files. Your shipped overview replaces the reviewer-written page.

Explain these points in order, using headings only when they help:

1. What the plugin does.
2. How it works, when that is not obvious.
3. Setup: settings, accounts, tokens, external tools, supported operating systems and Paseo versions.
4. Useful capabilities, settings, data access, permissions and limitations.

Describe where data goes, including prompts and tool results sent to agent providers. Local storage does not mean data stays on the host. If the plugin downloads or installs software while running, explain what it installs and its source, and require explicit user confirmation before the download. This applies to activation and connection tests too; declining must leave the software uninstalled.

Use plain factual language and sentence case. Omit marketing, unsupported claims, badges, changelogs, contributing and license sections, and implementation details that do not help someone choose the plugin. The listing already provides plugin installation instructions.

The publication validator rejects paseo plugin add, npm install and npm i anywhere in an overview, including development or setup examples. Link to your README for those commands.

Also supply a one-sentence description: use package.json's description for npm or the manifest's description for Git. The reviewer can fill in a missing description in the registry.

Icons and screenshots

Themes, panels and other visual plugin interfaces need at least one image showing the current interface. Use sample data and hide private details. An icon alone does not meet this requirement; plugins without their own visual interface do not need screenshots.

Declare local images in paseo-plugin.json before publishing:

{
  "id": "review-tools",
  "name": "Review tools",
  "description": "Reviews changes before merge",
  "icon": "assets/icon.png",
  "media": ["assets/screenshot.png"],
  "requirements": { "paseo": ">=0.11.0" }
}

Create the referenced files and include assets/ in package.json's files list for npm. Paths are relative to the manifest, use forward slashes and stay inside the plugin directory. These metadata fields require Paseo 0.11.0 or later.

Field	Listing behavior
name	Optional display name; defaults to a humanized plugin ID.
icon	Optional package-relative PNG. Provider registration icons have a separate SVG contract.
media	Package-relative paths or public HTTPS URLs. Images: PNG, JPG, JPEG, WebP or GIF. Videos: MP4 or WebM. The first image is the card thumbnail; videos supplement it.

Public media URLs need a supported file extension, matched case-insensitively, and must return HTTP 200 with the corresponding image or video content type. SVG and extensionless attachment URLs are not accepted as registry media.

Instead of declaring media, you can supply suitable public image URLs in the submission or review PR. The reviewer can add them to the listing without a new plugin release.

Publish on npm

1. Set package identity

Use an npm scope you can publish to and authenticate with npm login. From your plugin directory, replace @acme and the repository below with your own values:

npm pkg set name=@acme/paseo-review version=1.0.0
npm pkg delete private
npm pkg set repository.type=git repository.url=git+https://github.com/acme/paseo-review.git

The current registry tooling requires a GitHub repository for npm listing ownership, supplied through package.json or npm provenance. Set repository to your public source repository so pinning can determine the listing owner. Provenance itself is optional; if present, its repository must match the package's repository. A matching source checkout is not required for artifact review.

2. Lock installed dependencies

Keep Paseo's host libraries and type-only dependencies in devDependencies. Add other runtime libraries to dependencies. For registry submission, every installed dependency tree needs a lock with exact versions, resolved sources and integrity, including transitive dependencies.

For an npm package with installed runtime dependencies, update its lock without running lifecycle scripts, then create the publishable lock:

npm install --package-lock-only --ignore-scripts
npm shrinkwrap

npm shrinkwrap converts package-lock.json into npm-shrinkwrap.json. npm publishes the shrinkwrap at the package root; it does not publish package-lock.json. A repository-only lock or exact direct version does not lock the dependency tree installed by your users.

Plugins using only host libraries and development dependencies need no runtime lock unless a preparation command installs those dependencies. You can also bundle a library and remove the runtime dependency declaration. See preparation and additional setup if your plugin installs a separate tree.

3. Check the package and publish

Generate any required files before checking the package; the dry run skips packing scripts.

npm run typecheck
npm pack --dry-run --ignore-scripts

Check the file list contains paseo-plugin.json, at least one runtime entry, every imported local module, any overview and assets you declared, and the shrinkwrap when required. Repository-only import aliases and files outside the package do not reach users. The scaffold includes the entries and client/, server/ and shared/; add other asset directories to files.

Confirm any declared preparation command succeeds with the Node/npm versions you support; an out-of-sync or incompatible lockfile still blocks installation.

Publish the checked version:

npm publish --access public

On a test daemon, install that exact published version and exercise its contributions:

paseo plugin install npm:@acme/paseo-review@1.0.0
paseo plugin ls

Require running with no error, then submit the package.

Share through GitHub or Git

For the public registry, push your plugin to a public GitHub repository. Include its manifest, runtime entries, imported files and listing assets. Git tags and commits are optional at submission; provide one to select a revision, or the reviewer resolves main.

If preparation installs runtime npm dependencies, commit a synchronized package-lock.json and add this command to paseo-plugin.json:

{
  "build": [["npm", "ci", "--omit=dev", "--ignore-scripts"]]
}

npm ci consumes the committed lock and fails if it disagrees with package.json. --omit=dev excludes development tools and --ignore-scripts suppresses dependency lifecycle scripts. The daemon needs npm on its command path. Plugins using only host libraries need no preparation command. See preparation for generated files or explicit scripts.

Users can install directly from Git without a registry listing:

paseo plugin add git:acme/paseo-review
paseo plugin add git:acme/monorepo:plugins/review

Use --ref to select a branch, tag or commit for the initial installation. Direct installation also supports private repositories and other Git hosts when the daemon has access; see plugin sources. Registry submission accepts public GitHub sources and public npm packages.

Plugin registry

Open the submission form. Use the form so the issue receives the submission label that starts intake.

1. Use your plugin's name as the title.
2. In Source, enter the public npm package name or page, or the GitHub repository/folder URL. Include the version or Git reference if you want a specific release reviewed. npm defaults to latest. Registry IDs and local directories are not submission sources.
3. Select the categories that fit. Include any interface-image URLs in the issue description.

The bot opens a review PR. The reviewer inspects the artifact and dependencies without running plugin code, completes the listing and records the exact approved version or commit. Publication requires the review policy, including locked installation inputs and appropriate data access, even when automated validation passes.

If a change is requested, reply on the review PR with the corrected version/revision or requested image URL. The reviewer updates the pin and listing. Intake service errors retry automatically; missing images or an overview do not prevent opening the review PR.

After approval and publication, users install your listing with:

paseo plugin add owner/slug

npm releases receive automatic update PRs. Submit Git updates manually with the desired revision. Existing registry installations use approved pins; direct npm/Git installs follow their own update rules in the source reference.

Plugins with a build step

Paseo compiles TypeScript, so an ordinary plugin needs no separate publication build. Keep generated modules in their runtime directory and host-provided modules external.

Paseo suppresses npm lifecycle scripts during package acquisition. Commands explicitly declared in manifest build still run, including scripts they invoke. Explain the purpose of those commands and keep their inputs locked and inspectable. Remove Git-only dependency-install commands from npm manifests when npm already installs the production dependencies.

Later setup that installs another dependency tree needs its own complete lock, even if your plugin has a development lockfile. For npm setup, ship the runtime manifest and lock together and use npm ci. For Python setup, ship a requirements file containing exact versions and SHA-256 hashes for all transitive packages, then install it with:

python -m pip install --require-hashes -r requirements-documents.txt

This command rejects unpinned or unhashed dependencies. Runtime installation also needs the confirmation and disclosure described above.

Private npm packages

:::example[Publish a private package with GitHub Packages]

You can publish a company plugin to GitHub Packages. Follow the npm steps above, using your organization's scope, and replace the publish command with:

npm publish --registry=https://npm.pkg.github.com

Configure GitHub authentication and package access before publishing.

To install the plugin, configure npm on the daemon host, as the user running Paseo:

1. Add your organization's registry to ~/.npmrc:

   @acme:registry=https://npm.pkg.github.com
   

2. Log in with your GitHub username and a personal access token (classic) as the password. The token needs read:packages and access to the package.

   npm login --scope=@acme --auth-type=legacy --registry=https://npm.pkg.github.com
   

3. Install the plugin:

   paseo plugin install npm:@acme/paseo-review
   

Paseo uses the host's npm registry settings and credentials for installation and updates. In the app, enter only the source identifier.

:::