@archival/carriers-toolchain

Builds archival carriers: the small server side functions a site keeps under carriers/. A carrier is built the same way everywhere it runs, and this is that build.

1. Install. The packages the carrier's package-lock.json names are downloaded, checked against their hash and unpacked in memory.
2. Strip. swc removes TypeScript's types.
3. Link. Every import is resolved and rewritten to the relative path of the module it names.

Nothing is bundled and nothing is executed. The result is a map of module path to source, plus the entry's path, ready to be written to disk, uploaded as an unbundled Worker, or served to a page.

The toolchain refuses anything that would not run identically everywhere, and names the file or package when it does.

• ES modules only. A CommonJS file, or a package that only publishes CommonJS, is refused.
• Web APIs only. A Node built-in (node:fs, crypto, buffer) is refused.
• Imports are named. An import names one of the carrier's own files or an installed package, as a string. A specifier with a scheme (cloudflare:workers, https:) is refused, and so is an import() whose argument is computed when it runs, since the build could not see what it loads.
• Dependencies come from the lockfile. Development and optional packages are left out, install scripts never run, and dependencies with no lockfile are refused. The lockfile must be version 2 or later.
• TypeScript that erases. Types are stripped, not transformed, which is the rule Node applies: no enum, no namespace, no parameter properties, and a type-only import must say import type. Positions are preserved, so a stack trace names the line the author wrote with no source map.

Relative imports may name a file with or without its extension, and a .json file is imported as its value. Where a package offers a browser build beside a node one, the browser build is linked.

npm install @archival/carriers-toolchain

The toolchain takes two functions from the platform it runs on: strip, which removes types, and parse, which finds a module's imports. A host module supplies the pair.

import { buildCarrier } from "@archival/carriers-toolchain";
import { parse, strip } from "@archival/carriers-toolchain/node";

const { entry, modules } = await buildCarrier({
  // The carrier's own files, by path relative to its directory.
  files: new Map([["index.ts", "export default async () => ({ ok: true });"]]),
  strip,
  parse,
  fetch,
});
// entry === "index.ts.js"; modules is a Map of path -> JavaScript.

@archival/carriers-toolchain/node strips with the swc version this package pins. @archival/carriers-toolchain/node-builtin strips with Node's own stripTypeScriptTypes instead (Node 22.13 or later), which is the same stripper as that Node release bundles it.

import { buildCarrier } from "@archival/carriers-toolchain";
import { createWebHost } from "@archival/carriers-toolchain/web";

const host = await createWebHost(fetch("/swc.wasm"));
const built = await buildCarrier({ files, fetch, ...host });

The wasm is wasm_bg.wasm from @swc/wasm-typescript-esm; the node host exports its location as swcWasmPath for a build step that copies it. A Worker cannot compile wasm at run time, so it imports the file as a module and calls createWebHostFromModule with it.

@archival/carriers-toolchain/embedded is the toolchain and the node-builtin host bundled into one file that imports nothing but Node's own modules, for a program that ships the toolchain inside itself. npm run bundle writes it to dist/embedded.mjs.

A refusal is a CarrierCompileError, or a LockfileError for a lockfile that cannot be installed from.

npm install
npm test
npm run format

The tests run under Node's own test runner. They build tarballs in memory and stand in for the registry, so nothing is downloaded.

swc is pinned to an exact version in package.json, and every consumer gets that version through this package, so bumping it here is what moves all of them. Tagging v<version> stages the package from CI; npm stage list shows it and npm stage approve <stage-id> (2FA) publishes it. CI can only stage.

AGPL-3.0-or-later