oxy-custom-apps

Custom-app development

Custom-app bundles are arbitrary JS apps served by Oxy at https://<env>/customer-apps/<org>/<slug>/. Oxy is a data gateway: serves static assets, gates cookie auth, and proxies queries. The bundle is opaque above the data plane — no per-app server config.

This file is the contract. The detail lives in references/ — see Read next for which file answers what.

The Oxy App Kit (use it)

Two small packages remove the footguns — default to them rather than wiring a bundle by hand:

• @oxy-hq/sdk — the data layer (useQuery, useSemanticQuery, useAgentRun, <OxyChat>); see rule 2 and the @oxy-hq/sdk README.
• @oxy-hq/vite-plugin (oxyApp() in vite.config.ts) — bakes the asset base path from the manifest, copies oxy-app.json into out/, proxies /api in dev, and injects the window.__OXY_APP__ shim. Dropping it re-introduces the #1 bug — asset 404s → blank dashboard (rule 3).

Scaffold both with pnpm create @oxy-hq/oxy-app my-app (templates vite — the default — functions, dashboard, single-store; -t functions adds Oxy Functions). The platform is kit-agnostic (any bundle with a correct base path works), but hand-rolling means owning the base-path + dev-proxy wiring yourself.

Three rules

1. oxy-app.json (project root, not public/) is identity only. Schema:

   {
     "schemaVersion": 2,
     "slug": "url-slug",
     "orgSlug": "your-org",
     "name": "Display Name"
   }
   

   Required: schemaVersion (must be 2), slug (non-empty). Strongly recommended: orgSlug (lets @oxy-hq/vite-plugin derive the asset base path automatically, so plain pnpm build produces a bundle ready to drop into the linked org with no env var). Optional: name (display), projectId (dev-time hint).

   At serve time, oxy injects the authoritative org + project from the admin row via window.__OXY_APP__ — the manifest's orgSlug and projectId are advisory hints only, never enforcement.