| name | manifest-and-deploy |
| description | How to register, configure, and ship an app built on this kit — the manifest that declares the app to the platform registry, registration in the platform's developer hub (app id + shared secret, sandbox before prod), environment variables and secrets, and deployment to any capable host. Use when editing the manifest, setting up env/secrets, registering the app, changing the embed/webhook URLs, or deploying. Triggers on "manifest", "developer hub", "deploy", "env vars", "secrets", "publish the app", "register the app", "sandbox vs prod", "401 after deploy", "which manifest". |
Manifest, registration & deployment
Getting an app from this kit into a platform account has three parts: the manifest (declares
what the app is and where it lives), registration in the platform's developer hub, and
deployment to your host. This skill covers all three generically. Peek Pro is the canonical
example — the concrete manifest shape, env-var names, and dev CLI behavior live in
peek-manifest-and-deploy; the host/framework build details live in javascript-nextjs.
Host and database are your choice — this skill recommends a shape, not a product. The
platform, framework, SDK, and test runner are fixed by the CLI; the host and database are the
"moving layer" you pick per project (research current best practice at build time). When the app
needs persistence, a serverless-Postgres-style database reached server-side only (one
connection string), with any live UI driven by polling/SSE from your own API routes, fits this
architecture cleanly — scope every row to the stable per-install data key (see backoffice-data).
The concrete host/DB recommendation lives in peek-manifest-and-deploy and javascript-nextjs.
1. The manifest
The manifest declares the app to the platform registry — what the app is (id, name, version,
listing copy, icon, categories), where it lives (its public base URL and the embed entry URL the
platform loads inside its surface), and what capabilities it requests (the extensions /
extendables that grant API access, surface the app, and register its webhooks). Enumerate the
extensions available for the platform and read each one's required config with the CLI (extensions list / extensions show — see cli); pushing the manifest to the registry is sync-app (also
cli).
- The embed entry URL in the manifest is what the platform POSTs to — it must match the embed
route your app implements (see
embed-and-auth).
- If you add a webhook or an MCP endpoint, declare its URL here too (see
webhooks,
mcp-endpoint).
- When you change the embed path or add an endpoint, update the manifest to match, and re-register /
re-publish in the developer hub.
The exact field names and the registry extendable/key slugs are platform-specific and can be
volatile — pull them from the installed package (types + docs/) / the live registry doc, and see
peek-manifest-and-deploy for the canonical shape.
2. Registration — the platform's developer hub
- Get access to the platform's developer hub.
- Register the app; obtain its app id and its shared secret (used to verify the identity
token — see
embed-and-auth).
- Confirm the sandbox environment and validate there before production. Never test against a
live account.
- The app's runtime auth is per-install via the token flow — there is no login the developer
or user creates. Registration just provisions the app's identity/keys.
3. The #1 post-deploy trap: two apps/environments, one coherent set
You are really juggling two separate apps in two environments:
- a dev/test app in sandbox (often generated by the CLI's dev command, published at an ephemeral
tunnel URL, with its own id+secret written into your local env), and
- a source/production app in prod (which you author, publish, and deploy, with its id+secret in
the host's secret store).
The identity token is signed with the issuing app's secret and verified with the secret in your
runtime env; the SDK calls the platform API at the configured API URL. So the set {app id, app secret, api url, base url} must ALL describe the SAME app in the SAME environment. Cross them — a
prod secret against a sandbox API, or a test-app id verifying prod tokens, or the sandbox tunnel URL
carried into prod — and every request 401s with nothing obviously wrong. This is the single most
common "every request 401s / blank embed after deploy" cause.
Rule of thumb: one coherent set at a time. Local dev = the test app in sandbox (the CLI manages
that set in your local env); production = your real app in prod (you keep that set coherent in the
host's env). Don't cross the streams. See peek-manifest-and-deploy for the canonical two-manifest
split and dev-CLI behavior.
4. Environment & secrets
- Env is validated on boot and fails LOUD. A required var that's missing is a broken deploy,
not a warning — the app 500s on the first request (see the misconfig → 500 rule in
embed-and-auth). Register every runtime var in the env schema so it's validated on boot.
- Any var an app adds is required too. As a build introduces persistence or integrations (a DB
URL, a webhook signing secret, third-party API keys), register each in the env schema and add it to
the production set. The kit's baseline vars are not the whole list for a finished app.
- Secrets live in the host's secret store — never in the repo or the client bundle. Mark each var
secret (the app secret, DB URLs, API keys) or non-secret config (the app id, the base URL).
If you add a DB, keep its connection string server-only — there is no client-direct DB access
in this architecture. No PII or tokens in logs.
- End every build with the app-specific production env-var checklist — the base vars plus every
var this build added, secret-vs-config flagged, set in the host before deploying. This is the
most common post-deploy failure. See the "Before deploy" step in
app-builder.
5. Deployment
Deploy to any Node-capable host; the concrete recommended host and its build details are in
javascript-nextjs / peek-manifest-and-deploy. One worked concrete example — Fly.io, with its
flyctl login/launch flow, the pnpm-workspace Dockerfile gotcha, and managed Postgres — is
javascript-deploy-fly. Regardless of host:
- Set the env vars in the host (the coherent prod set from §3 — do not carry over the sandbox
URL from local dev; add the DB URL if used).
- Keep the CI gate green — lint → typecheck → test w/ coverage → build on every branch (see
testing). It's host-agnostic and gates the deploy.
- Ensure the embed's frame-ancestors/CSP header is set so the platform can embed the app (see
embed-and-auth / javascript-nextjs).
First-time deploy checklist:
Related skills
cli — the CLI that drives all of this: extensions list/show to discover what the manifest
can declare, sync-app to push the manifest, dev to run locally, and the registry/login
preflight checks.peek-manifest-and-deploy — the canonical concrete manifest fields, the PEEK_APP_* env names,
the two-manifest sandbox/prod split, the dev-CLI behavior, and the recommended host/DB.javascript-nextjs — the framework build/deploy details and the CSP/iframe header.javascript-deploy-fly — a concrete Fly.io deploy recipe instantiating this contract.embed-and-auth — the embed route the manifest points at; how the app secret is used and why a
config error is a 500, not a 401.backoffice-data — the extendable that grants API access, and the per-install scoping key for the
DB.webhooks / mcp-endpoint — endpoint URLs declared in the manifest/registry.testing — the CI gate that runs before deploy.
