publish — from personal use to publishing to the store

Audience: the person building a tool, and the AI working on their behalf. Both read this same page.

Goal

Take a package you use yourself and turn it into one other people can install from the store, understand at a glance, and not be puzzled by after installing — then ship it.

Publishing itself does not happen in the CLI: the CLI only gets the package into a shippable state (check --profile publish with zero errors). Signing and upload happen in the publish panel of the Workbench in the desktop app (Mac / Windows), which is where your login identity and signing capability live.

Before you start

1. The package is already error-free on the personal profile (you have been through numable docs first-card).
2. You are logged in to the desktop app — otherwise the publish panel just says you need to log in first.
3. The package is the one you authored in your workspace folder, not someone else's package installed from the store.

Step 1 · Know what the two profiles differ on

numable check has two profiles. The personal profile skips nine sections, all of them things that do not affect whether the package runs, only whether other people can use it — left to good intentions, none of them ever get done, so only a check can enforce them.

Beyond that, every check that runs on both profiles (structure, allowlist must match exactly, DSL silent failures, route and credential declarations) still applies. The complete code table is in numable docs lint-codes.

Step 2 · Run the full checks and fix them one by one

Command

numable check hn --profile publish

What "right" looks like: the goal is 0 error. Coming straight from the personal profile, it usually looks like this:

Static checks · profile publish (full store-standard set)

── HN Top Story (hn) ──
✗ [01M200QWNNX1RFPNTX5S7M8PGW] only 1 widget, the standard requires ≥3
✗ [01M200QWNNX1RFPNTX5S7M8PGW] no 42/44 widget (the standard requires at least one wide widget)
! [01M200QWNNX1RFPNTX5S7M8PGW] no logo.png — will fall back to an initial-letter icon
· [01M200QWNNX1RFPNTX5S7M8PGW] 1 widget · layout[22] · 5KB · net[hn.algolia.com]

✗ check finished: 2 error / 1 warn

A suggested order for fixing them:

1. Add widgets (G6). Do not just resize the same widget — a wide widget should answer more (the top few entries, a trend bar), not be a small widget stretched out. After each new widget, go through run → render → the three-state renders again.
2. Export a logo (G11). 512×512, content filling the whole canvas, no margin and no rounded corners of your own at the four corners.
3. Fill in the store front (G19 / G21). subtitle says in one sentence what the package gives me, ≤22 characters; title short enough to read in one line. The English is not a machine translation of the Chinese, it is a fresh sentence an English user understands.
4. Fill in the English (G20 / G8). One title / sub pair per .xwidget; matching keys in both locales in each .rcn's rc.i18n. How to do it: numable docs localize.
5. First-paint cache (G23), credential entry (G25), add-widget button (G24 / G27) — only packages with a detail page / with credentials / with an add-widget entry will run into these.

Warnings (!) do not block publishing, but read every one of them. Several of them mean "it works today, but English users / small-screen users are not seeing what you think they are".

After fixing, re-verify on two layers:

numable run hn
numable render hn --locales zh-CN,en-US

If the English column still renders Chinese, the text table is not wired up; if a literal ${@i18n.xxx} appears on a widget, that key is missing in that locale.

Before you publish · Read your on-screen text once more

check tells you whether things run, not whether the words are any good. Before handing the package to other people, go through every line users can see — in widgets, pages and reminders — against these points:

• Write for users, not for yourself. Users only want to know what happened, what it means for them, and what they can do. Implementation reasons (why it is 30 minutes, which endpoint broke) stay off the screen.
• Use words users recognise. The visual unit is a "widget" (组件 in Chinese), not a "card"; to users your package is a "tool" (工具), not a "package" or "bundle"; words like fetch / host / token / render become "get data" / "site" / "update". In Chinese, count widgets and tools with 个 and reminders with 条.
• In Chinese, use full-width punctuation (，。：？（）), put a space between Chinese and Latin text or digits ("每 5 分钟", "在 Mac 上"), and use the single … for an ellipsis.
• Error messages come in parts: what happened → what you can do. Write "Couldn't get data. Check your connection and try again.", not "Request failed 500"; never ask users to do developer work (read logs, change an API URL).
• Don't promise what you can't deliver. Not a word of "real time" or "on the dot every day" (see numable docs alerts for why).
• In English use sentence case (only the first word capitalised) and start buttons with a verb; write each language as natural sentences of its own rather than word-for-word translations.

Step 3 · Publish from the Workbench in the app

The CLI does not publish. Go to the desktop app (Mac / Windows) → Workbench → find the package → Publish.

The panel has three things to look at:

After a successful upload the panel shows one of two outcomes:

• Published and live — auto-approved, already in the store, visible to all users. This is the normal case.
• Uploaded, pending review (draft) — not visible to ordinary users; it reaches the store after platform review and signing.

Publishing is an outbound action: every byte in the package is signed and distributed to every user. Before you ship, confirm the package contains no keys, no local fixtures, and no private data — the .numable/ folder never enters the package by design, and credentials are declared through manifest.credentials rather than written into files (see numable docs credentials).

Step 4 · After publishing

How the package reaches users

At upload time the package is sealed into a signed .xbundle. The user taps install in the store → the client downloads it → verifies the signature and file hashes → unpacks it to disk → renders locally. Data is always fetched by the user's own device; it never passes through the server.

Updates ride on version +1

The app compares the version in the store with the version installed and only offers an update when the former is higher. Re-publishing without bumping manifest.version is the same as not publishing: the update is never noticed and installed users stay on the old build forever. Before shipping a new version, re-verify your changes on both the run and render layers — users install all of the package, not just the few files you touched.

Your source folder and the published version are two copies

The copy in your workspace folder is the source; it is never overwritten by the published version and never appears in the update badge (updates only apply to packages installed from the store). So:

• Keep editing locally and running check / run / render without affecting the version already shipped;
• To get your changes to users you must publish again (version +1);
• To see what users actually installed, install it from the store on another device (or under another account).

A widget's file name is its identity

Each widget on a user's dashboard records "which package + which .xwidget file name". If a new version deletes or renames a .xwidget, the widgets that point at it show "Widget removed" and are cleared when the package updates. So once a widget file is named, keep the name; to replace a widget, add a new file, and delete the old one only if users can do without it.

A version that widens access is not installed automatically

"Auto-update tools" is on by default, but if a new version reaches more than the installed one — more websites (manifest.network), more credentials (a new credentials[].id, or an existing credential sent to a new website), or new background jobs — it is not updated silently: the user taps update and confirms each one, with the install panel saying "New in this version: …". A version that only narrows access installs automatically. So ship a change that widens access as its own version, not bundled with a fix users are waiting for.

Version history and going back

In the Workbench, the package row's ··· → Version history lists every version you published and its state. A version that was replaced by a newer one, or that you withdrew yourself, offers Go back to this one: it republishes that version's content under a new version number and replaces the version currently live (the app only accepts a higher version number, so going back is also a step forward, not a renumbering). A version the platform took down cannot be restored this way; appeal instead.

What you can still do after shipping

The Workbench lets you take down your own published packages; if a package is taken down or reported, you can appeal. Both live on the package list in the Workbench.

Common mistakes

Next

• Fill in the English and the content text tables: numable docs localize
• Connect a data source that needs a key (and the four hard rules for credentials): numable docs credentials
• Error codes one by one: numable docs lint-codes