---
title: "WebAssembly: compile a script into a module"
description: "shotcup:wasm compiles a script into a WebAssembly module that runs in Node, Deno or a bundler's build: compile(), the files it writes, the per-plan limits, how to load the module, where it runs, the language features and built-ins it compiles, what does not compile yet and the cold start."
canonical: "https://shotcup.dev/docs/wasm"
last_updated: "2026-10-18"
---
# WebAssembly: compile a script into a module

`shotcup:wasm` compiles a script in your sandbox into a WebAssembly module
that runs outside Shotcup: in Node, in Deno, or in a bundler's build. The
module carries its own runtime and calls nothing on Shotcup; it is a file the
run writes, like a PNG or a PDF, and you host it. Compiling happens inside a
run and counts like any other run. The module needs no engine switch.

```js
import { compile } from "shotcup:wasm";

const result = compile("/main.ts");
console.log(result.wasmBytes, result.exports);
```

Not every program compiles yet. When a compile meets something it does not
compile, it stops with an `Error` whose message starts with `wasm:` and
names the feature, and writes nothing. [What does not compile
yet](#what-does-not-compile-yet) lists them, and [the
table](#language-features-and-built-ins) shows the language features and
built-ins one by one.

## compile(entry, { out })

`compile(entry, options)` reads the sandbox file `entry` (a path such as
`"/main.ts"`; a relative path starts from `/`), parses it with the run's
language profile and with its type annotations checked at run time (every
compile does), and writes the module.

- `out` (optional) names the `.wasm` file, under `/out/`, its name made
  of letters, digits, `_`, `-` and `.`. The default is `/out/app.wasm`.
- It returns `{ wasm, companion, wasmBytes, companionBytes, functions,
  exports }`: the two paths, their sizes in bytes, the number of functions
  compiled, and `exports`, a list of `{ name, kind }` whose `kind` is
  `"function"` or `"constant"`.
- An option other than `out`, or an `out` that is not such a path, is a
  `TypeError`. A missing entry is an `Error`. A cap below is a
  `RangeError` naming it.

Your script's exports are the module's: functions, async functions (which
return promises), generators, and constants that are numbers, strings,
booleans, `null` or `undefined`.

## Your own files

An import of another script file in your sandbox, by a relative or absolute
path (`import { total } from "./lib.ts"`), is compiled into the same module.
Each file runs once, as the module loads, after the files it imports and in
the order JavaScript runs modules, and an imported binding stays live: when
the file that exports it writes it again, the importer reads the new value.
The entry's exports are the module's, and the entry can re-export another
file's (`export { run } from "./impl.ts"`, `export * from "./lib.ts"`): each
is then an export like the entry's own, a function with its own name and
length. Another file's exports that the entry does not re-export are seen only
by the files that import them.

Not compiled yet: an import cycle between your files, a namespace import of
one (`import * as lib from "./lib.ts"`), and an import of a file that is not
a script, such as JSON, YAML or text.

## The files it writes

| File | What it is |
|---|---|
| `<name>.wasm` | The module. |
| `<name>.companion.js` | A small JavaScript module the `.wasm` imports by its relative name. Keep it beside the module. |

A module that passes objects, arrays or functions to and from its host also
writes `<name>.proof.js` and `<name>.preload.js`, and the result names them
as `proof` and `preload` with their sizes. Keep `proof.js` beside the
companion; `preload.js` is optional ([below](#load-the-module)). The files
come back with the run like any other file it writes under `/out`, as
downloads.

## Limits per plan

Every plan has `shotcup:wasm`. The caps apply to one `compile` call:

| Plan | Each source file | Functions | Output (the files together) |
|---|---|---|---|
| Free | 24 KiB | 2,000 | 1 MiB |
| Pro | 192 KiB | 20,000 | 8 MiB |
| Scale | 192 KiB | 50,000 | 16 MiB |
| Platform | 192 KiB | 50,000 | 16 MiB |

The source cap applies to each file the compile reads: the entry and each of
your files it imports. The functions cap counts the functions of all of them.
A compile also needs memory from the run's heap, in proportion to the size of
those files together. It checks before it compiles each file, and a program
that does not fit is a `RangeError` before the module is built. The files
it writes count against the sandbox's storage like any other file.

## Load the module

```js
// Node 24.15 or later
const app = await import("./app.wasm");
console.log(app.total([1, 2, 3]));
```

A bare import in your script (`fs`, `node:fs`, a package name) stays an
import of the module, and the host resolves it when it loads the module, as
it would for JavaScript. Shotcup's own modules (`shotcup:canvas`, `shotcup:html`
and the others) exist only in a run, so the compile refuses an import of one.

A module has exactly the capabilities of the host modules its script
imports. Import `fs` and it reads and writes the host's files; import a
module that starts processes or runs code from text, and so can it. The
compile does not limit what an import can do: check what you import, as you
would for any JavaScript you run. The same goes for what your own code hands
the module, such as the arguments of an exported function: it uses what it is
given.

Beyond that, a module reaches the host's built-ins through `String`,
`RegExp`, `Math`, `Boolean`, `Number` and the values they give. It
cannot build a function from text through them: the `Function` constructor
it can reach that way throws the same `TypeError` it throws on Shotcup.

When your script names a property of `String`, `RegExp`, `Math`,
`Boolean` or `Number`, it can read only the members they have on Shotcup.
Any other member, an assignment to or `delete` of one, and `__proto__` and
its relatives stop the compile with a `wasm:` error, or throw a
`TypeError` whose message starts with `wasm:`. A host method your script
calls behaves as it does in JavaScript, including any change it makes: an
array's `push` called on `Math`, for example, adds an element to it, as it
does on Shotcup.

If you load the preload, load it first, before any code that replaces a
built-in, and once in each realm:

```js
await import("./app.preload.js");
const app = await import("./app.wasm");
```

It lets the module take faster paths through host objects and arrays. Without
it the module uses the ordinary methods, which is the safe default.

`JSON.parse` and `JSON.stringify` are the module's own, with the same results
and error messages as on Shotcup. When they read an object or array that came
from the host, they use the host's `Object.keys`, `Array.isArray` and a few
other built-ins as they were when the module loaded. If the host replaces one
of them later, the module's `JSON` does not change. What `JSON.parse` returns
works in template literals, `+`, arithmetic and comparisons, as in JavaScript,
except an object or array whose own `toString`, `valueOf` or `join` is a
function: the compile stops at one of your script's functions there, and a
function from the host there is a `TypeError` whose message starts with
`wasm:` when the conversion would call it.

`console` is the host's. `console.log` and the other methods a script has on
Shotcup (`info`, `debug`, `warn`, `error`, `dir`, `table`,
`assert`, `count`, `countReset`, `time`, `timeLog`, `timeEnd`,
`group`, `groupEnd`, `clear` and `trace`) call the host's console, so
the text is the host's: how it shows objects and arrays, whether it reads
format strings such as `%s`, which stream each method writes to, and the
`Warning:`, `Error:`, `Info:` and `Debug:` that Shotcup's console puts
before those methods' lines and the host's does not. Plain strings and numbers
print the same. Objects and arrays reach the console as copies made at the
call: a getter runs to fill the copy, and an instance shows no class name, as
on Shotcup. An error that leaves the module carries only its name and message
as its stack, with no lines naming the module's code.

Reading a property by a key your script makes as it runs (`table[name]`)
works on your script's own objects and arrays, as in JavaScript: properties
it inherits, getters, array elements and `length`, and `undefined` for a
key nothing holds. A key that names a built-in method the module does not
compile, such as `toString` or `__proto__` on a plain object, throws a
`TypeError` whose message starts with `wasm:`. Such a read of a value that
may also be a string, a number or a host value, such as one `JSON.parse`
returned, does not compile yet.

## Where it runs

A module needs WebAssembly 3.0's exception references and the JavaScript
string built-ins, and a host that loads a `.wasm` file through `import()`:

| Host | Loads the module |
|---|---|
| Node | 24.15 or later (it prints an experimental warning) |
| Deno | 2.3.2 or later |
| Vite | 8.2 or later |
| webpack | with `asyncWebAssembly`; its string built-ins are not checked |
| Browsers | not yet: no release browser loads a `.wasm` file through `import()` |
| Bun | not through `import()` yet |

## Language features and built-ins

Each row is a small program compiled and run under Node and Bun, its result
compared with the same script run on Shotcup. "Compiled" means the module
does it itself. "Calls the host" means the module calls the host's own
built-in or module for it, so it behaves as the host's does: the String
methods, `Math`, RegExp and turning numbers into text come from the host.

| Language | Status |
|---|---|
| Numbers, arithmetic and bitwise operators | Compiled |
| Strings and template literals | Compiled |
| Numbers as text (String(n), a number in a template) | Calls the host |
| let, const and block scope | Compiled |
| Destructuring and spread | Compiled |
| Closures | Compiled |
| Default and rest parameters | Compiled |
| Arguments past the declared parameters | Compiled |
| Objects, computed keys and getters and setters | Compiled |
| Optional chaining and nullish coalescing | Compiled |
| typeof, instanceof, in and delete | Compiled |
| Classes, fields, inheritance and super | Compiled |
| Static members and static blocks | Compiled |
| Private fields and methods | Not compiled yet |
| Exceptions: try, catch, finally and throw | Compiled |
| Labelled break and continue, switch | Compiled |
| Iterators, for...of and Symbol.iterator | Compiled |
| Generators | Compiled |
| async functions and await | Compiled |
| Async generators and for await | Compiled |
| A top-level await | Not compiled yet |
| Regular expression literals | Calls the host |
| Tagged templates | Not compiled yet |
| BigInt | Not compiled yet |
| Decorators | Not compiled yet |
| Enums | Not compiled yet |
| using and await using | Not compiled yet |
| JSX | Compiled |
| Imports of the program's own files | Compiled |
| Import cycles between the program's own files | Not compiled yet |
| Namespace imports of the program's own files | Not compiled yet |
| Shotcup's own modules (shotcup:canvas, shotcup:html and the others) | Not compiled yet |
| Bare imports (provided by the host) | Calls the host |
| export default of an expression | Not compiled yet |

| Built-in | Status |
|---|---|
| Math | Calls the host |
| String methods | Calls the host |
| RegExp objects and their methods | Calls the host |
| Number | Calls the host |
| Number.prototype.toFixed | Not compiled yet |
| Boolean | Calls the host |
| Array methods | Compiled |
| Array static methods (Array.from, Array.isArray) | Compiled |
| Object static methods (Object.keys, Object.entries) | Compiled |
| JSON.stringify (a replacer, an indent, toJSON) | Compiled |
| JSON.parse (a reviver) | Compiled |
| JSON.rawJSON and JSON.isRawJSON | Not compiled yet |
| Map | Compiled |
| Set | Compiled |
| WeakMap and WeakSet | Not compiled yet |
| Promise | Compiled |
| Symbol() | Not compiled yet |
| Error and its subclasses | Compiled |
| Date | Not compiled yet |
| Temporal | Not compiled yet |
| Intl | Not compiled yet |
| console | Calls the host |
| globalThis | Not compiled yet |
| Proxy and Reflect | Not compiled yet |
| ArrayBuffer and typed arrays | Not compiled yet |
| TextEncoder and TextDecoder | Not compiled yet |

## What does not compile yet

We compile every one of our run templates, and the language tests of [GocciaScript](https://gocciascript.dev), the
engine Shotcup runs, that run in Shotcup's default language profile. Each
module that compiles runs under Node and Bun, and its results must equal the
same script run on the engine. A template counts as compiled only when its
module, run under Node and Bun with the template's files, prints and writes
exactly what the template's own run on Shotcup does.

- **Templates:** 29. 2 compile and give the same results; 27 stop at a compile error that names the feature.
- **GocciaScript's language tests:** 933 files, of which 838 run in Shotcup's default profile. 282 compile, and their 1,207 tests give the same results as on the engine; 548 stop at a compile error that names the feature; 2 the engine does not parse in that profile either; 6 compile and differ where a value crosses between the module and its host.

Mocking your own files, such as a test runner's `vi.mock` of one of them, is
not supported: they are compiled in as they are, so a mock the compile does
not catch has no effect.

Each row is what the compile says, and how many templates and test files
stop there first. A file stops at its first, so a feature further down the
same file is not counted; a row without a count comes from the table above.

| The compile says | Templates | Language test files |
|---|---|---|
| the import of "shotcup:canvas" is refused: shotcup:canvas has no host outside Shotcup | 7 |  |
| the import of "shotcup:zip" is refused: shotcup:zip has no host outside Shotcup | 3 |  |
| import() of a computed specifier (opcode OP_COMPUTED_IMPORT_SPECIFIER is not compiled yet) | 2 | 7 |
| converting a compiled object to a string is not compiled yet | 2 | 1 |
| the global Date is not compiled yet | 2 | 1 |
| a file larger than the plan's maxWasmSourceBytes | 2 |  |
| a top-level await is not compiled yet | 1 | 21 |
| Number.prototype.toFixed is not compiled yet | 1 | 1 |
| a call of a value of more than one type is not compiled yet | 1 |  |
| a namespace-only or side-effect import of "goccia:yaml" is not compiled yet | 1 |  |
| opcode OP_CREATE_ARGUMENTS is not compiled yet | 1 |  |
| opcode OP_SET_PROP_CONST_LOOSE is not compiled yet | 1 |  |
| the import of "shotcup:html" is refused: shotcup:html has no host outside Shotcup | 1 |  |
| the import of "shotcup:result" is refused: shotcup:result has no host outside Shotcup | 1 |  |
| the import of "shotcup:streams" is refused: shotcup:streams has no host outside Shotcup | 1 |  |
| the global globalThis is not compiled yet |  | 35 |
| an import of a file that is not a script ("./…") is not compiled yet |  | 27 |
| an import cycle is not compiled yet |  | 26 |
| a class whose parent is not a class written in the same code that the transform can follow is not compiled yet |  | 24 |
| the global Goccia is not compiled yet |  | 24 |
| decorators (opcode OP_BEGIN_DECORATORS is not compiled yet) |  | 22 |
| a private name (a private field) is not compiled yet |  | 20 |
| a BigInt is not compiled yet |  | 19 |
| an async function or a generator passed to the host is not compiled yet |  | 17 |
| a global name the program reads without declaring it is not compiled yet |  | 16 |
| export default of an expression is not compiled yet; declare it (const x = ...) and export { x as default } |  | 16 |
| Symbol() is not compiled yet |  | 15 |
| a using or await using declaration is not compiled yet |  | 15 |
| enums (opcode OP_FINALIZE_ENUM is not compiled yet) |  | 12 |
| import() (opcode OP_DYNAMIC_IMPORT is not compiled yet) |  | 12 |
| the property constructor, which Object.prototype or an error may give, is not compiled yet |  | 12 |
| a private name (OP_CLASS_DECLARE_PRIVATE_STATIC_CONST) is not compiled yet |  | 11 |
| an export that a function assigns (an exported `let` that changes after the module loads), which is not compiled yet |  | 11 |
| enums (opcode OP_ENUM_KEYS is not compiled yet) |  | 11 |
| OP_ADD on a value of more than one type is not compiled yet |  | 9 |
| the property name of a function is not compiled yet |  | 9 |
| getters and setters with computed names (opcode OP_DEFINE_ACCESSOR_DYNAMIC is not compiled yet) |  | 8 |
| iterating a value of more than one type is not compiled yet |  | 8 |
| assigning a global (opcode OP_SET_GLOBAL is not compiled yet) |  | 7 |
| delete of a computed property (opcode OP_DEL_INDEX is not compiled yet) |  | 7 |
| import.meta (opcode OP_IMPORT_META is not compiled yet) |  | 7 |
| a tagged template is not compiled yet |  | 5 |
| pattern matching (opcode OP_MATCH_HAS_PROPERTY is not compiled yet) |  | 5 |
| the global ArrayBuffer is not compiled yet |  | 5 |
| import defer (opcode OP_IMPORT_DEFER is not compiled yet) |  | 4 |
| module mocking of the program's own files is not compiled yet |  | 4 |
| the global Proxy is not compiled yet |  | 4 |
| the property call of a function is not compiled yet |  | 4 |
| OP_GET_THIS_BINDING in a function is not compiled yet |  | 3 |
| a host namespace value is not compiled yet |  | 3 |
| a namespace import of "./…", one of the program's own files, is not compiled yet |  | 3 |
| pattern matching (opcode OP_MATCH_VALUE is not compiled yet) |  | 3 |
| Array.prototype.slice is not compiled yet |  | 2 |
| Array.prototype.sort is not compiled yet |  | 2 |
| OP_ADD on an object is not compiled yet |  | 2 |
| OP_LT on an object is not compiled yet |  | 2 |
| OP_MUL on a value of more than one type is not compiled yet |  | 2 |
| a class that extends Map is not compiled yet |  | 2 |
| a computed property key that may be a string is not compiled yet |  | 2 |
| a property key that may be an object is not compiled yet |  | 2 |
| an import of "./…" with attributes is not compiled yet |  | 2 |
| instanceof with the global Object or Array is not compiled yet |  | 2 |
| new of a value of more than one type is not compiled yet |  | 2 |
| new.target (opcode OP_NEW_TARGET is not compiled yet) |  | 2 |
| the property apply of a function is not compiled yet |  | 2 |
| the property hasOwnProperty, which Object.prototype or an error may give, is not compiled yet |  | 2 |
| the property length of a function is not compiled yet |  | 2 |
| typeof the global Object or Array is not compiled yet |  | 2 |
| < on an object is not compiled yet |  | 1 |
| Array.prototype.Symbol(Symbol.iterator) is not compiled yet |  | 1 |
| Number.prototype.toString is not compiled yet |  | 1 |
| OP_BXOR on a function is not compiled yet |  | 1 |
| OP_DIV on a function is not compiled yet |  | 1 |
| OP_DIV on an object is not compiled yet |  | 1 |
| OP_INC_NUMERIC on a value of more than one type is not compiled yet |  | 1 |
| OP_INC_NUMERIC on an object is not compiled yet |  | 1 |
| OP_POW on an object is not compiled yet |  | 1 |
| Object.defineProperty of a function is not compiled yet |  | 1 |
| Object.defineProperty of a value of more than one type is not compiled yet |  | 1 |
| Object.defineProperty of the realm's prototype is not compiled yet |  | 1 |
| Object.getOwnPropertyDescriptor of a value of more than one type is not compiled yet |  | 1 |
| Object.getOwnPropertyNames is not compiled yet |  | 1 |
| Object.getPrototypeOf of a value the analysis cannot follow is not compiled yet |  | 1 |
| Symbol.hasInstance is not compiled yet |  | 1 |
| Symbol.metadata is not compiled yet |  | 1 |
| Symbol.toPrimitive is not compiled yet |  | 1 |
| a comparison with a number on an object is not compiled yet |  | 1 |
| a computed property key that may be a number is not compiled yet |  | 1 |
| a function with properties of its own passed to the host is not compiled yet |  | 1 |
| a namespace-only or side-effect import of "goccia:csv" is not compiled yet |  | 1 |
| a namespace-only or side-effect import of "goccia:test" is not compiled yet |  | 1 |
| a property descriptor on a value of more than one type is not compiled yet |  | 1 |
| a write of the property length of a string is not compiled yet |  | 1 |
| a write of the property missing of a number is not compiled yet |  | 1 |
| an error message that may be an object is not compiled yet (ToPrimitive) |  | 1 |
| an index of a function is not compiled yet |  | 1 |
| an instruction with more than 300 operands (a call's arguments, a closure's captured bindings) is not compiled yet |  | 1 |
| in on a number is not compiled yet |  | 1 |
| new of a function that is not a class is not compiled yet |  | 1 |
| spreading a string into an object is not compiled yet |  | 1 |
| super property reads outside a class method (opcode OP_SUPER_BASE is not compiled yet) |  | 1 |
| super property reads outside a class method (opcode OP_SUPER_GET is not compiled yet) |  | 1 |
| the element "0" of an array by a string key is not compiled yet |  | 1 |
| the export default is not one function, which is not compiled yet |  | 1 |
| the global Float64Array is not compiled yet |  | 1 |
| the global Reflect is not compiled yet |  | 1 |
| the property bind of a function is not compiled yet |  | 1 |
| the property stack, which Object.prototype or an error may give, is not compiled yet |  | 1 |
| the property toString, which Object.prototype or an error may give, is not compiled yet |  | 1 |
| the re-export namespaceExport (from "./…") is not compiled yet |  | 1 |
| JSON.rawJSON is not compiled yet |  |  |
| the global Intl is not compiled yet |  |  |
| the global Temporal is not compiled yet |  |  |
| the global TextEncoder is not compiled yet |  |  |
| the global Uint8Array is not compiled yet |  |  |
| the global WeakMap is not compiled yet |  |  |

## Cold start

The time from nothing loaded to a module ready to call, for the parts of four
templates that compile today, each measured in 21 fresh processes: the
median, with the 10th and 90th percentiles. On Node it is `import()` of the
module, which reads it and its companion, compiles, links and instantiates it.
Bun does not load a `.wasm` file through `import()`, so there it is
`WebAssembly.instantiate` with the companion and the string built-ins
supplied in JavaScript. Measured on 6 November 2026 on a desktop with an AMD Ryzen AI Max+ 395, Linux x86-64, Node 24.21.0, Bun 1.4.2.

| Program | Module and companion | Node | Bun |
|---|---|---|---|
| browser-planner's walk of an accessibility tree | 84 KiB | 2.8 ms (2.7 ms–5.8 ms) | 4.5 ms (4.2 ms–5.2 ms) |
| the code-mode-orchestrator's tool filters and totals | 37 KiB | 2.6 ms (2.5 ms–6.3 ms) | 3.8 ms (3.6 ms–4.5 ms) |
| fetch-diff-monitor's release normaliser | 36 KiB | 3.1 ms (3.0 ms–6.5 ms) | 3.8 ms (3.6 ms–4.5 ms) |
| hook-policy's rules and its decision function | 108 KiB | 3.2 ms (3.1 ms–3.6 ms) | 4.9 ms (4.7 ms–5.9 ms) |
