Browser and Node.js setup

pystd is ESM-only. All module subpaths load the same internal CPython WebAssembly runtime, so import modules normally and let the first import finish initialization through top-level await.

Node.js

Use Node.js 22.12 or newer and install the single package:

pnpm add pystd

import { hashlib, math } from "pystd";

console.log(math.factorial(10n));
console.log(hashlib.sha256(new TextEncoder().encode("hello")).hexdigest(undefined));

The importing file must be ESM: use an .mjs extension or set "type": "module" in package.json. No Python installation is needed at runtime.

Browser

Use a bundler that supports ESM, top-level await, and WebAssembly assets. Vite works with an ESNext build target:

// vite.config.ts
import { defineConfig } from "vite";

export default defineConfig({
  build: { target: "esnext" },
});

Application code uses the same imports:

import { itertools, math } from "pystd";

const result = math.factorial(10n);
const pairs = itertools.combinations(new BigInt64Array([1n, 2n, 3n]), 2);
document.querySelector("#output").textContent = `${result}: ${pairs.length} pairs`;

Serve the built files over HTTP; opening index.html through file:// will not provide the fetch behavior needed by WebAssembly assets. Production servers should send .wasm files as application/wasm.

Repository smoke tests

Build before running smoke tests:

vp run build
vp run smoke:node
vp run smoke:browser
# or both
vp run smoke

The Node.js smoke test imports the typed namespace barrel from pystd. The browser test creates a production Vite bundle, serves it locally, opens it in headless Chromium, and verifies real math, hashlib, and itertools calls. Chromium must be available as chromium on PATH for the browser test.