Library

flypod is a tiny, dependency-light npm package that turns a folder of static files into a live URL from JS/TS. It's the same deploy primitive the CLI wraps, exposed as functions you can call directly.

npm install flypod   # or: bun add flypod

Everything ships from one entry point. It's ESM-only (load it with import, not require) and runs on Node 18+ and Bun:

import {
  deploySite,
  DeployError,
  collectDist,
  collectFiles,
  resolveDeployDir,
  BUILD_DIR_CANDIDATES,
  DEFAULT_IGNORES,
  IGNORE_FILE,
} from "flypod";
import type { DeployResult, DeployOptions, DeploySource, CollectedFiles, SkippedPath } from "flypod";

The mental modelCopy Anchor Link

A deploy is two steps: read files into a map, then ship the map.

const files = await collectDist("./dist"); // { "index.html": Uint8Array, ... }
const { url, manage_token } = await deploySite({ files });

deploySite creates a new site every time it's called. Save the manage_token it returns — that token is what lets you update or roll back the site later.

Two more things worth knowing up front:

• Deploys are anonymous by default (public, expires in ~14 days). Pass an account token to make a site owned and permanent — see Owned deploys.
• The library only deploys. There's no update() or rollback() function. To ship a new version to an existing site or roll one back, use the HTTP API (POST /sites/:id/deploys) or the CLI with the manage_token.

Want to run something now? The TypeScript demo is a downloadable, working example you can deploy in one command.

deploySiteCopy Anchor Link

deploySite(opts: DeployOptions): Promise<DeployResult>

Zips a files map, uploads it as a new site, and returns the live URL plus the tokens you need to manage it. If the server answers with a non-2xx status it throws a DeployError carrying the status and the server's error code, so you can tell a rate limit (retry later) from a refused upload (don't). A network failure rejects with whatever fetch threw.

Called directly, deploySite never reads a saved flypod login session or a FLYPOD_TOKEN from the environment — a deploy is owned only if you pass apiKey yourself. The one ambient value it reads is the FLYPOD_SOURCE label (see source below), which can't change who owns a deploy or where it goes.

DeployOptionsCopy Anchor Link

DeployResultCopy Anchor Link

flypod.dev always returns healed and warnings (as empty arrays when there's nothing to report); they're typed optional so the result still fits an older self-hosted server. The raw response also carries a render block, which the type leaves out — see POST /sites.

ExampleCopy Anchor Link

import { deploySite, collectDist } from "flypod";

const files = await collectDist("./dist");
const result = await deploySite({ files });

for (const w of result.warnings ?? []) console.warn(`${w.code}: ${w.fix_recipe}`);
console.log(result.url);          // https://a3f1c2d4e5b60789.flypod.page — live now
console.log(result.manage_token); // save this to update / roll back later

DeployErrorCopy Anchor Link

class DeployError extends Error {
  readonly status: number;            // the HTTP status, e.g. 413 or 429
  readonly code: string | undefined;  // the server's stable error code, when it sent one
  readonly body: string;              // the response body, verbatim
}

What deploySite throws when the server refuses the deploy. Its message is deploy failed: <status> <code> (or the body, when that's short and carries no code). Branch on code, not on the message; the codes are the HTTP API's, for example:

import { deploySite, DeployError } from "flypod";

try {
  await deploySite({ files });
} catch (err) {
  if (err instanceof DeployError && err.code === "rate_limited") {
    // back off and try again later
  } else throw err;
}

collectDistCopy Anchor Link

collectDist(path: string): Promise<Record<string, Uint8Array>>

Reads files off disk into the { path → bytes } map that deploySite expects. Pass a directory and it's walked recursively (paths are relative to the directory, with / separators); pass a single file and you get a one-entry map keyed by its file name. A file you name explicitly is never filtered.

const site = await collectDist("./dist");      // whole folder
const one  = await collectDist("./index.html"); // { "index.html": Uint8Array }

A directory walk leaves out the same paths the CLI does:

• DEFAULT_IGNORES, wherever they sit in the tree: .git, .hg, .svn, node_modules, .DS_Store, Thumbs.db, .env, and .env.*. Other dotfiles (.well-known/, .nojekyll) are kept.
• Patterns in a .flypodignore (IGNORE_FILE) at the top of the folder, in gitignore syntax: *, ?, **, a leading / to anchor, a trailing / for directories only, ! to re-include, # for comments. The last matching pattern wins. The .flypodignore itself is never uploaded.
• Symlinks: a link to a file is read through. A link to a directory is followed only when it resolves inside the folder being deployed; one that points outside it, loops back up the tree, or is broken is skipped.

To see what was left out, use collectFiles, which returns the same map plus the list.

You don't have to use collectDist — any Record<string, Uint8Array> works, so you can generate files in memory (see the inline demo).

collectFilesCopy Anchor Link

collectFiles(path: string): Promise<CollectedFiles>

interface CollectedFiles {
  files: Record<string, Uint8Array>; // what collectDist returns
  skipped: SkippedPath[];            // what was left out, sorted by path; empty when nothing was
}

interface SkippedPath {
  path: string; // relative to the folder; directories end in "/"
  reason: "default" | "flypodignore" | "symlink_outside" | "symlink_loop" | "broken_symlink";
}

collectDist with a receipt. Use it to show the user what a deploy will leave out before it ships:

const { files, skipped } = await collectFiles("./dist");
for (const s of skipped) console.log(`skipped ${s.path} (${s.reason})`);
await deploySite({ files });

DEFAULT_IGNORESCopy Anchor Link

The names every directory walk skips, at any depth:

[".git", ".hg", ".svn", "node_modules", ".DS_Store", "Thumbs.db", ".env", ".env.*"]

IGNORE_FILECopy Anchor Link

".flypodignore" — the optional per-folder ignore file that adds to DEFAULT_IGNORES. It's read from the top of the folder you collect, honoured, and never uploaded.

resolveDeployDirCopy Anchor Link

resolveDeployDir(opts?: { cwd?: string; explicit?: string }): Promise<string>

Figures out which folder to deploy so callers don't have to hardcode dist. It's async. Behavior:

• With explicit set, that path is returned as-is.
• Otherwise it scans BUILD_DIR_CANDIDATES in order (relative to cwd, default process.cwd()) and returns the first folder that exists and contains an index.html.
• Next, a candidate with exactly one app folder inside that has an index.html (dist/<app>/ or dist/<app>/browser/, as Angular builds) returns that folder.
• Next, cwd itself, when it has an index.html, no package.json (or other project file such as _config.yml or pyproject.toml), and is not the home directory: a folder of plain pages.
• If nothing matches, it throws — pass the folder explicitly in that case.

import { resolveDeployDir, collectDist, deploySite } from "flypod";

const dir = await resolveDeployDir();   // auto-detect, e.g. "/proj/dist"
const files = await collectDist(dir);
await deploySite({ files });

BUILD_DIR_CANDIDATESCopy Anchor Link

The ordered list resolveDeployDir searches. public ranks low because some tools use it for source assets — requiring an index.html disambiguates a built site from source.

["dist", "build", "out", ".output/public", ".vercel/output/static", "public", "_site"]

Owned deploysCopy Anchor Link

By default a deploy is anonymous: public, noindex, and it expires in ~14 days. To make a site owned and permanent, pass an account session token as apiKey. flypod login saves one to its session file for the CLI; for headless runs the convention is to supply it as the FLYPOD_TOKEN environment variable, which the CLI reads first. deploySite reads neither on its own, so pass it explicitly:

const result = await deploySite({
  files,
  apiKey: process.env.FLYPOD_TOKEN,
});
// result.expires_at === null, result.owner_account_id is set

See Tokens & ownership for how tokens and ownership fit together, and Accounts & claiming to attach sites you already deployed anonymously.