PermuteDocs
Go to Permute

Build apps

Deploy an app

Build a static frontend locally, upload source and compiled files, and publish the app at its Permute URL.

Before you start

Workflow

  1. 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.
  2. 2Build the frontend into dist with relative asset URLs. Keep secrets outside source and compiled files.
  3. 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.
  4. 4Run the deployment example to upload source and compiled files, save a draft, and publish it. Preserve its printed app ID for updates.
  5. 5Open the URL as an intended viewer. Verify permitted reads or actions and denial without access before treating the app as ready.

Project setup

bash
# 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

typescript
// 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.

bash
# 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.