Bundling und Veröffentlichung

Publish a working sandboxed plugin so other sites can install it. Publishing is sandboxed-only — native plugins distribute through npm.

Publish directly from the CLI, or use the automated release service to build and publish from GitHub Actions. Both paths write the release to your Atmosphere account. You only need a separate artifact host when you explicitly choose the direct CLI’s --url path.

Prerequisites

• A valid emdash-plugin.jsonc with slug, publisher, license, an author (author or authors), and a security contact (security or securityContacts). Run emdash-plugin validate to confirm.
• A version (in package.json, or the manifest for registry-only plugins).
• An Atmosphere account to publish under.

Choose a publishing method

Both methods create the same signed package and release records. Choose where the release build should run.

Your Atmosphere account

You publish under an Atmosphere account: a portable, user-owned identity used across Bluesky and other apps in the AT Protocol network. One account is your single login across the network, with the same @handle everywhere, and your identity and data are not tied to any one app. EmDash uses this account as your publisher identity: every release you publish is a record in your own account, signed in as you.

EmDash uses the same Atmosphere accounts as its Atmosphere login for sites.

Use an existing account

If you already have a Bluesky account or any other Atmosphere account, sign in with its handle:

emdash-plugin login alice.bsky.social

This opens your account provider’s sign-in page in the browser. EmDash never sees your password. emdash-plugin whoami lists your stored sessions; emdash-plugin switch <did> changes the active one.

Sign up for an account

If you do not have an Atmosphere account yet, create one through any provider, then run emdash-plugin login <your-handle>. Your options:

• An app, such as Bluesky. Signing up for Bluesky creates an Atmosphere account hosted by Bluesky. This is the quickest route.
• An independent provider. Community-run or privacy-focused account hosts. Browse options at atmosphereaccount.com.
• Self-hosted. Run your own provider for full control over your identity and data.

Whichever you choose, the @handle from that account is what you pass to emdash-plugin login, and the account’s DID is what you pin as the publisher in your manifest.

Publish from your plugin directory

Log in once, then publish from the directory containing emdash-plugin.jsonc:

emdash-plugin login alice.example.com
emdash-plugin publish

publish runs the same build and validation checks as bundle, creates the gzip archive, uploads it to your Personal Data Server (PDS), uploads any declared listing images, and writes the release record.

Sites need a version of EmDash that supports PDS-hosted registry artifacts before they can install a blob-only release. Use the external package URL path when the release must remain installable on older sites.

Bundle

bundle runs build, validates, collects assets, and creates a tarball. Inside the tarball, plugin.mjs is packed as backend.js (the filename the registry expects).

The command accepts the following flags:

emdash-plugin bundle [--dir <path>] [--out-dir|-o <path>] [--validate-only]

Tarball contents

Validation

bundle (and --validate-only) check:

• Size caps (RFC 0001, decompressed): total ≤ 256 KB, per-file ≤ 128 KB, ≤ 20 files. The gzipped tarball is a fraction of that.
• No Node built-ins in backend.js — sandbox code can’t import fs, path, child_process, etc. Use Web APIs, or move that logic to a native plugin.
• Capability sanity — names must be in the recognised set.
• Trust-contract coherence — the network:request / allowedHosts cross-rules from the manifest.
• Asset limits — icon 256×256, ≤ 5 screenshots at ≤ 1920×1080.

To inspect the tarball before publishing, list its contents:

emdash-plugin bundle
tar tzf dist/my-plugin-1.1.0.tar.gz

Publish

Publish the current source and host its artifacts on your PDS:

emdash-plugin publish

The following manifest block adds listing images. Paths are relative to emdash-plugin.jsonc; PNG, JPEG, and WebP are supported.

{
  "release": {
    "artifacts": {
      "icon": { "file": "./icon.png" },
      "banner": { "file": "./banner.webp" },
      "screenshots": [
        { "file": "./screenshots/editor.png" },
        { "file": "./screenshots/settings.jpg", "lang": "en" }
      ]
    }
  }
}

What publish does:

If an existing login predates blob publishing, publish reports MISSING_BLOB_SCOPE. Run emdash-plugin logout, then log in again to approve the new scopes.

Use an external package URL

Pass --url when the package bundle is already available over HTTPS or the account provider does not accept gzip blobs:

emdash-plugin publish --url https://downloads.example.com/gallery-1.0.0.tar.gz

The CLI downloads the URL, validates the served bundle, and computes its checksum. It does not upload the package blob on this path. Listing images still use PDS blobs.

To compare the hosted bytes with a local tarball, add --local:

emdash-plugin publish \\
  --url https://downloads.example.com/gallery-1.0.0.tar.gz \\
  --local dist/gallery-1.0.0.tar.gz

Versions are immutable

A published version cannot be overwritten or republished. Bump version before publishing again. The build reads version from package.json (see the manifest reference). Bump major for a broadened trust contract, minor for new hooks or routes, and patch for fixes.

Publisher mismatch

If publish fails with MANIFEST_PUBLISHER_MISMATCH, the active session is a different Atmosphere account than the manifest’s pinned publisher. Switch to the pinned account with emdash-plugin switch <did>, or update publisher in the manifest if you are genuinely transferring the plugin to a new account. See Use an existing account for managing sessions.

What to read next

• The emdash-plugin CLI — every command
• Automated plugin releases — publish from an approved GitHub Actions workflow
• The manifest — fields, trust contract, publisher pinning
• Capabilities and security