Using a third-party library

Podda apps run only the files in their own revision, so a library becomes part of the app. Never retype library source into a tool argument: a model cannot reproduce 600 KB of minified JavaScript byte-for-byte, and a corrupted copy fails in confusing ways. Pick the first option that fits.

1. Bundle it in a shell (preferred whenever a shell tool is available)

If a shell or code-execution tool is in your tool list, use it: download the library (or npm install plus esbuild/rollup), ZIP the built directory with podda.json at the root, and use deploy_version action=prepare_upload, PUT, publish. One archive carries the whole app. Assume egress works — do not pick option 2 just because it is unverified. If the download or PUT fails with a network error, probe no further — fall back to option 2.

2. Vendor it by URL (no shell, or egress blocked)

Give stage_app_files a file entry with content_url and Podda downloads it server-side into the app. The bytes never pass through the conversation, and this works from any client, with or without a shell.

{
  "app_id": "<app_id>",
  "files": [
    { "path": "vendor/three.module.min.js", "content_url": "https://cdn.jsdelivr.net/npm/three@0.180.0/build/three.module.min.js" }
  ],
  "idempotency_key": "vendor-three"
}

The response echoes fetched_files with the bytes and sha256 Podda actually stored; pass that hash back as sha256 on a later call to pin the exact build. Import it with a relative specifier — import * as THREE from "./vendor/three.module.min.js" — never from a remote URL. At most eight URL entries per call, 25 MiB per file.

3. Large text without a shell

stage_app_files with append: true continues one oversized file across calls. Slower and easier to corrupt than content_url; use it only when a URL is not available.

Loading from a CDN at runtime

Possible, but it takes two steps and a stronger consent: declare the exact origin in podda.json network.expectedOrigins, then have the owner grant it with set_network_access browser_directives: ["script"]. The owner is told that this runs third-party code with the app's full privileges and that the CDN can change it at any time. Prefer bundling or vendoring instead: the bytes are pinned into the revision, no consent prompt is needed, and the app keeps working if the CDN changes or disappears.

Last updated 22 August 2026 · Documentation version 7