Build

Manifest

One manifest.json per app. You write this file and nothing else about a release; build derives the rest into release.json, which is what the shell, the store and the loader read. Both types are exported by the SDK as Manifest and Release.

JSON
1{
2 "id": "dev.example.tides",
3 "name": "Tides",
4 "version": "1.2.0",
5 "lane": "community",
6 "entry": "./main.tsx",
7 "icon": "./icon.png",
8 "light": true,
9 "edge": false,
10 "widgets": ["small", "medium"],
11 "network": ["https://api.example.com"],
12 "permissions": ["geolocation"],
13 "author": "Ada",
14 "repo": "https://github.com/ada/tides",
15 "license": "MIT"
16}

Fields

FieldRequiredMeaning
idyesReverse-DNS, lowercase, at most 64 characters, immutable. The key for the app's data, its releases and os.open. Two apps may share a name, never an id.
nameyesHome screen label and store title. At most 12 characters, or it truncates on the cover display.
versionyesStrict semver. Prereleases run only under ?dev=.
laneyescommunity or official. Official is a review status set by the catalog owner, not something an author grants themselves; check refuses official for an id outside the repository's OFFICIAL.txt.
entryyesYour entry module, relative to the manifest. Built into one app.html with script, styles and assets inline.
iconyesA square 1024 px PNG. Copied as icon-1024.png.
lightnoThe status bar draws dark on this app.
edgenoThe app draws under the status stack.
widgetsnoSizes you publish snapshots for through os.widget.set: small, medium. The shell renders the snapshot; no app code runs outside the frame.
networknoExact HTTPS origins the document may connect to: scheme and host, optional port, no path, no wildcard. They become the document's connect-src and media-src. Loopback http:// origins are allowed in development builds only.
permissionsnoNames from the permission table: geolocation, clipboard-read, clipboard-write, photos. Undeclared means refused at runtime.
author, repo, licenseyesShown in the store. repo is an https:// URL. license must be MIT.

Rules

  • id never changes. Renaming an app changes name only. A new id is a new app with no data.
  • version increases with every release, and CHANGELOG.md must mention it; check reads both.
  • Layout is responsive by requirement. There is no flag to opt out of the cover display: every app runs at 387 points wide.

release.json

JSON
1{
2 "manifest": { "...": "the file above" },
3 "build": { "sdk": "0.0.0", "kit": "0.1.0", "at": "2026-09-18T09:12:00Z", "commit": "…", "hash": "9f3ab21c" },
4 "files": [
5 { "path": "app.html", "bytes": 412000, "sha256": "…" },
6 { "path": "icon-1024.png", "bytes": 15100, "sha256": "…" }
7 ]
8}

build.sdk is the SDK version the app compiled against and its host requirement: the shell runs a release when its own SDK satisfies ^build.sdk under npm's caret rules, which while the SDK is 0.x means the exact version. build.kit is recorded for the store page and never gates. The release identity is version+hash, so a rebuild that changes any byte is a new identity and a published path is never overwritten.

Edit this page on GitHub