Developer Guide

Workflow

This is the practical path from a local extension folder to a marketplace draft. It covers the dev-only folder shape, the in-app Dev Extensions screen, listing submission, media uploads, and the current security boundaries.

Local development

Dev-only extensions live in devextensions/<key>/. Each one needs a manifest.json and a JS module file. These folders are discovered in development mode through /api/dev-extensions.

text

devextensions/
  hello-extension/
    manifest.json
    hello-extension.js

json

{
  "apiVersion": 6,
  "version": "1.0.0",
  "key": "hello-extension",
  "name": "Hello Extension",
  "category": "integration",
  "icon": "Sparkles",
  "description": "My local development extension"
}

✦

Keep the manifest focused on runtime behavior. Marketplace-only presentation details can be layered in later during draft submission.

Dev Extensions screen

The in-app Dev Extensions screen is the bridge between files on disk and the live app. It reads devextensions/, lets you install a dev build for the current persona, refresh it from disk, remove it, and prefill a marketplace draft when you are ready.

1Create or update manifest.json and the JS module in devextensions/<key>/.
2Open the Dev Extensions screen and install the extension for the persona you want to test.
3Use refresh when you change files on disk and want the cached dev build to reload.
4Use “Submit draft” when you want the same manifest and source to open in the marketplace submission flow.

Marketplace drafts and submission

Marketplace uploads are JS-only and require both the manifest object and the exact JS source text. New submissions begin as unpublished drafts so the author can install them and share them by direct link before publication review.

manifest JSONrequiredSupplies runtime metadata and the public listing baseline.

JS sourcerequiredThe browser-side module that the app will load.

listing overridesoptionalSubmission fields such as long description, tags, screenshots, and icon style can override matching manifest values at upload time.

draft share linkgeneratedUnpublished drafts may expose a direct share path for testing.

What carries over from dev mode

The Dev Extensions screen can prefill the submission form with the current manifest and JS source. That keeps the dev build and draft package aligned while you write listing copy, screenshots, and changelog text.

My Media

Shared extension media lives in My Extensions -> My Media. Upload there when the extension needs a stable media id that users can paste into settings or variables and resolve later with ctx.runtime.media.get(...) or ctx.runtime.media.getUrl(...).

Allowed uploads

.jpg up to 500 KB

.png up to 100 KB

.mp3 and .wav up to 10 MB

Access rules

Only admin-approved users can upload media.

Uploads are checked by extension, MIME type, and file signature before storage.

Security model

Extension code runs in the same browser context as the app. The main trust boundary is the extension author, not the listing page or install button.

Safe assumptions

The loader validates the manifest shape and checks source integrity for stored JS modules.

Media uploads are restricted to a small validated file set.

Still your responsibility

Review any JS you load locally or install from the marketplace.

Do not treat published status as a sandbox. Browser-side code still has browser-side privileges.