Publishing to Cosmo

Everything described here happens in the Cosmo web app on Publish (/publish). Sign in, open that page, and follow the labels on the form—you only need this doc when you want the full picture before you click around.

Widgets

You can ship a widget in one of two ways. Pick Widget at the top of the Publish page, then use either path below (the UI asks you to choose a repo or a ZIP, not both).

From GitHub (recommended for repos)

Use this when your widget source lives in GitHub and you want releases to drive publishing.

1. Connect your GitHub account (Connect GitHub Account).
2. Install the Cosmo Widget Publisher app on the repo you care about. If the repo list is empty, use Add Repositories (or the “adjust authorizations” link) to grant access.
3. Pick the repository, then choose a Workflow Trigger:
   • On Release (Recommended) — publish when you create a GitHub Release.
   • On Version Bump — publish when a new version appears in your widget config.
   • Manual Only — the workflow is installed; you run it from the Actions tab when you want.
4. Submit the form. Cosmo adds the publish workflow and repository secret your CI run needs. After that, publishing is driven from GitHub (create a release or run the workflow), not by re-submitting this form.

From a ZIP (manual upload)

Use this when you already have a packaged widget archive (for example from your own build pipeline or the CLI).

1. Under Or upload manually, choose Select Widget File (ZIP).
2. Wait for the in-browser check to finish. You should see name, version, config schema, widget identity, and file checks (index.html or assets/, optional README, preferences template, previews).
3. Fix any reported issues in the ZIP, then fill in Description and click Publish Widget.

Your ZIP must include a valid widget.config.json at the root of the packaged output (same layout you would ship to users). Required fields and optional id behavior are documented in Widget configuration. The archive must contain either index.html or a non-empty assets/ directory under that same root.

Publishing a new version of something you already shipped

Cosmo keeps one marketplace record per widget and attaches each upload as a version.

• GitHub-linked widgets: bump the version in your project and publish again using your chosen trigger (release, version bump, or manual workflow).
• ZIP widgets: scroll to My Published Widgets, click Upload New ZIP Version on the right row, then select your ZIP and publish. If your config uses an explicit widget id, it must match the widget you are updating.

Wallpapers

Choose Wallpaper on Publish, then:

1. Enter Title and Description.
2. Choose an image or video (supported types are noted next to the file field).
3. Click Publish.

Wallpapers do not use widget.config.json or the widget ZIP layout.

While you are still building locally

Developer Mode is for trying a widget on your machine. Publish is for versions you want in the marketplace. Stay in Developer Mode until you have a build you are ready to ship.