Skip to content

Dependencies

This page shows how to ship each library inside your tool, because a tool on SweatStack Tools can load files only from its own address.

Beta

SweatStack Tools is in beta and is subject to breaking changes. If you plan to use it in production, email [email protected] before you integrate, so we can tell you about changes in advance and help you migrate.

The rule

Everything a tool loads comes from its own files. The browser blocks a library from a CDN, a font from a font service and a script from any other site. This also makes a tool reproducible: what you deployed is what runs, for as long as the tool exists, and no CDN outage or compromised package can change it.

Run sweatstack tool check to list what your tool still loads from other sites. See SweatStack Tools.

Download a library

For a library that is one file:

  1. Make a vendor/ folder in your tool.
  2. Download the file. Put the exact version in the file name:
    mkdir -p vendor
    curl -L -o vendor/uPlot.iife.min-1.6.31.js https://cdn.jsdelivr.net/npm/[email protected]/dist/uPlot.iife.min.js
    curl -L -o vendor/uPlot.min-1.6.31.css https://cdn.jsdelivr.net/npm/[email protected]/dist/uPlot.min.css
    
  3. Load it with a relative path:
    <link rel="stylesheet" href="vendor/uPlot.min-1.6.31.css">
    <script src="vendor/uPlot.iife.min-1.6.31.js"></script>
    
  4. Keep the library's licence file next to it, if its licence asks for that.

Fonts work the same way. Download the font files and reference them with @font-face and a relative url().

A URL with a version range, like [email protected], is fine to download from. The downloaded file is the pinned version. The version in the file name shows which one you have.

Ship an ES module

If the package publishes a self-contained ES module build, download that file and import it with a relative path.

If the module imports other packages by name (import ... from "apache-arrow"), the browser can't resolve it. Bundle it once with esbuild:

npm install some-package
npx esbuild node_modules/some-package/dist/index.mjs --bundle --format=esm --outfile=vendor/some-package.mjs

If your tool already has a build step, keep it. A bundled tool already loads only its own files.

A library that downloads more code while it runs fails the same way as a CDN link. tool serve shows the blocked request in the console, with its URL. Download that file into the tool and tell the library where it is.

Ship DuckDB-WASM

DuckDB-WASM reads the Parquet files that the SweatStack API returns. It needs four files and one setting. These instructions are for version 1.32.0.

  1. Bundle the browser module. It imports apache-arrow by name:
    npm install @duckdb/[email protected]
    npx esbuild node_modules/@duckdb/duckdb-wasm/dist/duckdb-browser.mjs --bundle --format=esm --outfile=vendor/duckdb.mjs
    
  2. Copy the WebAssembly file and its worker:
    cp node_modules/@duckdb/duckdb-wasm/dist/duckdb-eh.wasm vendor/
    cp node_modules/@duckdb/duckdb-wasm/dist/duckdb-browser-eh.worker.js vendor/
    
  3. Download the Parquet extension. DuckDB-WASM reads Parquet through this extension. Without it, DuckDB downloads the extension from extensions.duckdb.org on the first Parquet query, the policy blocks that download, and the query fails with NetworkError.
    mkdir -p vendor/duckdb-extensions/v1.4.3/wasm_eh
    curl -L -o vendor/duckdb-extensions/v1.4.3/wasm_eh/parquet.duckdb_extension.wasm \
      https://extensions.duckdb.org/v1.4.3/wasm_eh/parquet.duckdb_extension.wasm
    
    v1.4.3 is the version of DuckDB inside DuckDB-WASM 1.32.0, not the version of the package. Keep the folder layout: DuckDB looks for {repository}/v1.4.3/wasm_eh/parquet.duckdb_extension.wasm.
  4. Start DuckDB from your own files, and tell it where the extension is:
    import * as duckdb from "./vendor/duckdb.mjs";
    
    const vendor = new URL("/vendor/", location.origin).href;
    const worker = new Worker(vendor + "duckdb-browser-eh.worker.js");
    const db = new duckdb.AsyncDuckDB(new duckdb.VoidLogger(), worker);
    await db.instantiate(vendor + "duckdb-eh.wasm");
    
    const conn = await db.connect();
    await conn.query(`SET custom_extension_repository = '${vendor}duckdb-extensions'`);
    
    Use absolute URLs, built from location.origin. DuckDB's worker resolves relative URLs against its own address, not the page's.

Then register and query Parquet as usual:

const response = await fetch(url, { headers: { Authorization: `Bearer ${accessToken}` } });
await db.registerFileBuffer("activity.parquet", new Uint8Array(await response.arrayBuffer()));
const result = await conn.query("SELECT avg(power) AS power FROM 'activity.parquet'");

The four files add about 38 MB to your tool. The 34 MB WebAssembly file is uploaded once. A later deploy uploads it again only if it changes.

Ship Pyodide

Download the Pyodide release into your tool and point indexURL at it:

npm install [email protected]
mkdir -p vendor/pyodide
cp node_modules/pyodide/{pyodide.mjs,pyodide.asm.mjs,pyodide.asm.wasm,python_stdlib.zip,pyodide-lock.json} vendor/pyodide/
import { loadPyodide } from "./vendor/pyodide/pyodide.mjs";

const pyodide = await loadPyodide({ indexURL: new URL("/vendor/pyodide/", location.origin).href });

A package that Pyodide loads with loadPackage or micropip must also be in the tool: download its wheel into vendor/pyodide/. pyodide.http.pyfetch uses the browser's fetch, so it can reach the SweatStack API and nothing else.

Sizes

  • 50 MB per file, 99 MB and 20,000 files per tool.
  • A deploy uploads only the files that changed. A large library costs upload time once.

What a tool can't use

  • Third-party APIs, such as a weather service.
  • Map tiles from a third party. Use SweatStack Maps.
  • Analytics and error tracking services.
  • Fonts or scripts from a CDN at runtime.

If your tool uses SweatStack data and needs one of these, build a SweatStack app with its own hosting instead.