App project and configuration

Octonode CLI app projects use one source descriptor, octonode.app.json. Shopify uses a TOML app file and separate extension files; Octonode currently uses JSON and declares entries together. octonode.toml and octonode.app.toml are not read by the app CLI.

workspace-notice/
  octonode.app.json
  src/extensions/notice.tsx
  tests/app.test.cjs
  package.json
  tsconfig.json

The default scaffold is a full Vite app with web.entry and an empty extensions list. The explicit --template extension scaffold starts as this static workspace block:

{
  "apiVersion": "octonode.app/v1",
  "id": "workspace-notice",
  "name": "workspace-notice",
  "version": "0.1.0",
  "settings": [{ "id": "message", "label": "Message", "defaultValue": "Welcome" }],
  "extensions": [{ "id": "notice", "target": "workspace.block", "entry": "src/extensions/notice.tsx" }]
}

id is the source identity; the Partner publication also receives an immutable app ID. Increment the semantic version for each release. Extension IDs must be unique lowercase slugs, and entries must be JavaScript or TypeScript files under src/. Settings are shared strings configured by the installing workspace. They are not secret storage. The CLI builds browser IIFEs and includes integrity hashes; it does not accept hand-written bundle hashes in the source descriptor.

Add a page or block

octonodes app extension add overview --target app.page
octonodes app extension add summary --target workspace.block
npm test

The command adds an entry and starter file. A page opens from Apps → Installed; a block appears on workspace home. Apps with only blocks remain available under Apps → Installed without requiring a dashboard. A page and block may coexist. The CLI's extension-only template can ship a page without a backend.

Add a backend

octonodes app create inventory-labels --template full

The full template adds src/server.ts and web.entry. Its backend is a default exported Fetch API handler. Set a permanent HTTPS origin before a release:

{
  "apiVersion": "octonode.app/v1",
  "id": "inventory-labels",
  "name": "Inventory labels",
  "version": "0.1.0",
  "web": {
    "entry": "src/server.ts",
    "applicationUrl": "https://labels.example.com",
    "requestedActions": ["projects:read", "data:read"]
  },
  "extensions": [{ "id": "notice", "target": "workspace.block", "entry": "src/extensions/notice.tsx" }]
}

The only supported actions are projects:read, data:read, data:write, and workflows:run. Request only what the app uses; installers approve the actions and specific projects. The CLI's extension-only releases currently request no project actions. Full apps configure their own private settings in their backend; shared manifest settings cannot be combined with web in the CLI source file. web.applicationUrl is an HTTPS origin, with no path, query, fragment, or embedded credentials. You may pass --app-url https://labels.example.com to a single build instead of writing the URL in the descriptor; publishing rebuilds, so save the URL in the descriptor before app publish.

See the app SDK for code and hosting for the production output. The source descriptor is validated before each build; compiled registration artifacts use a different versioned manifest contract.