Skip to main content

​
app.json

The app.json in the project root is the only config file the platform reads:
The platform only reads the fields above; anything else is not uploaded.

​
placement: placement options

Each installation has its own independent shared region. A mini app with a site-wide leaderboard must be single — placing it in two locations splits the leaderboard in half.
It governs nodes too. A single app can exist in one place — one post or one node — and a second anywhere is refused. A bot meant for node owners to install is almost always many: each node keeps its own greeting log, its own rules, its own pending reminders. Use single only when the whole point of the app is one shared thing, and reach for kv.app first — it shares across installs and makes many safe.

​
settings: what to ask at install time

An app that needs to be told something — an endpoint, a key, a category — declares the fields, and the install form renders them:
Types: string text markdown secret url integer boolean enum, at most 20 fields. url accepts https only; enum needs options. markdown is filled in with the same editor a post is written in, with @-mentions, emoji and preview, and is allowed a post’s length — for greetings, notices and anything else the app will publish as is. Whatever is filled in arrives as ctx.config. Declare nothing and ctx.config is whatever an admin put there by hand.
label and description may be written per locale. Node owners are the audience for this form, and a form of English fields on a forum that does not speak English is a form nobody can fill in. Fallback runs exact, then the same language written for anywhere else, then English.
A secret is never sent back to a browser — not even the browser of the person who typed it. The form shows it as already set, and leaving it blank keeps it: a form that cannot show a value must not read blank as “clear it”.

​
readme.md

The readme.md in the project root is uploaded together with the code, rendered as Markdown, and shown on the mini app’s detail page (/apps/<slug>). It’s the only thing people read before deciding whether to open your mini app — the name in app.json is a single line and can’t tell the story. It’s plain Markdown: headings, lists, bold, links, and code blocks are all supported, rendered by the same renderer as posts:
Things to know:
  • The readme follows the version, not the mini app. Whichever version you upload is the version whose readme the page shows; reviewers see that same copy. Changing the readme requires submitting a new version — a mini app approved as a “dice tool” can’t quietly rewrite its description a few days later.
  • You can publish without a readme.md; this section simply won’t appear on the page.
  • Limit: 64 KB.
  • The CLI isn’t required: the submission form in the author center (/apps/authoring/<slug>) has the same field, pre-filled with whatever you wrote in the previous version.