Before you start
Workflow
- 1Prepare your frontend project and an authoring client. Creating an app requires app creation access; updating an existing app requires its authoring permissions. Keep the key outside browser code.
- 2Build the frontend into dist with relative asset URLs. Keep secrets outside source and compiled files.
- 3Create an app or select its existing ID. Before releasing the working frontend, arrange viewer access and the app grants required by its queries or approved actions.
- 4Run the deployment example to upload source and compiled files, save a draft, and publish it. Preserve its printed app ID for updates.
- 5Open the URL as an intended viewer. Verify permitted reads or actions and denial without access before treating the app as ready.
Project setup
# For a new React project; skip creation if you already have a frontend. bun create vite operations-portal --template react-ts cd operations-portal bun install bun add @permute/sdk@^0.13.0 # Edit src, then build the complete site with relative asset URLs. bun run build --base=./
Example
// Save as deploy.ts in your frontend project. Running it publishes the build.
import { PermuteClient } from '@permute/sdk';
import { deployApp } from '@permute/sdk/deploy';
function required(name: string): string {
const value = process.env[name]?.trim();
if (!value) throw new Error('Set ' + name + ' before running this script');
return value;
}
const client = new PermuteClient({
apiKey: required('PERMUTE_API_KEY'),
baseUrl: process.env.PERMUTE_API_BASE_URL, // Defaults to https://api.permute.ai.
}).withWorkspace(required('PERMUTE_WORKSPACE_ID'));
const appId = process.env.PERMUTE_APP_ID;
let app = appId
? await client.apps.get(appId)
: await client.apps.create({ name: 'Operations portal', key: 'operations-portal', description: '' });
console.log('App ID:', app.id);
const deadline = Date.now() + 10 * 60_000;
while (app.deployment?.status !== 'live') {
if (!app.deployment) throw new Error('This app has no hosting deployment');
if (['failed', 'deleting', 'deleted'].includes(app.deployment.status)) {
throw new Error(app.deployment.error ?? 'App cannot be published: ' + app.deployment.status);
}
if (Date.now() >= deadline) throw new Error('Provisioning timed out; inspect this app before retrying');
await new Promise((resolve) => setTimeout(resolve, 2000));
app = await client.apps.get(app.id);
}
const current = await client.revisions.list(app.id);
if (current.draft?.revisionId !== current.published?.revisionId) {
throw new Error('Review the existing unpublished draft before replacing it');
}
const deployed = await deployApp(client, {
appId: app.id, directory: './dist', expectedDraft: app.draft,
source: { directory: '.', build: {
command: 'bun run build --base=./', outputDirectory: 'dist', runtime: 'bun@1.3.12',
} },
});
console.log('Changed:', deployed.changed);
console.log('Published revision:', deployed.revisionId);
console.log('Live app:', deployed.url);Run the deployment
Save the complete example as deploy.ts and run it from the project root so it can find dist. Supply PERMUTE_API_KEY through your shell or deployment secret store. Set PERMUTE_API_BASE_URL if you are using a different API environment.
For a new app, choose its name and a stable creation key in the script. Reuse that key when retrying creation, and keep the printed app ID for later updates. A different new app needs a different creation key.
# PERMUTE_API_KEY must already be set in your shell. export PERMUTE_WORKSPACE_ID=wksp_... # First deployment: creates an app, uploads dist, saves a draft, and publishes. bun run deploy.ts # Later deployments: rebuild and update the same app. export PERMUTE_APP_ID=appl_... bun run build --base=./ bun run deploy.ts
Deploy source and compiled output
Use SDK 0.7.0 for source-backed app saves and the deployment helper from @permute/sdk/deploy for Node and Bun. The helper validates the complete build before uploading, saves a draft, and publishes with compare-and-set checks; it does not build or provision the app.
Pass expectedDraft from checkout or a reviewed app read. Deployment rejects stale tokens before uploading and never adopts a newer remote draft as the base of your local files. Omitted actions preserve the current bindings (an empty array clears them); supplied actions must name exact published revisions. Unchanged source, build instructions, compiled files, SPA mode, and supplied bindings return changed: false without uploads or writes; the helper rechecks refs first. A reviewed unpublished draft still publishes its settings changes. The helper stops on concurrent changes and never retries mutations.
After a failed or lost response, inspect app history before retrying: publication may have completed, or the saved draft may need review. Use individual upload/save calls when you want to review a draft before publication.
Build and hosting requirements
Upload the complete dist directory, including index.html. The limits are 200 files, 4 MiB per file, and 50 MiB per build. The SDK hashes each file and uploads it through a signed URL; saving verifies the checksum and size before accepting the manifest.
Use relative URLs for bundled and public assets. Permute inserts a revision-specific base element into HTML so relative files stay on the same version. Root-relative asset paths bypass that pin. For a runtime data file, fetch(new URL("data/example.json", document.baseURI)) stays on the page’s revision.
The example sets spa: true, which serves index.html for extensionless HTML navigation. Missing asset files still return 404. Use spa: false when the build contains separate HTML pages and does not need client-side routing fallback.
Hosting supports static HTML, CSS, JavaScript, and assets. Inline scripts, external scripts and API requests, workers, and server-side rendering are unavailable. There is no hosted build service or app source editor; keep source and lockfiles in your own project. With Permute sign-in, the browser SDK supports governed queries and published business actions through the app session. Shared-password demos serve frontend files only; password-free public access is unavailable.