Primeros pasos
Cargar Wasm en JS
WebAssembly (Wasm) es un formato binario que corre a una velocidad casi nativa en los navegadores. instantiateStreaming carga y compila un archivo .wasm. Las exportaciones son funciones invocables desde JavaScript.
// Load and instantiate a .wasm module
WebAssembly.instantiateStreaming(fetch('module.wasm'))
.then(result => {
const { instance } = result;
// call exported functions
console.log(instance.exports.add(2, 3)); // 5
});
// Alternative: from ArrayBuffer
const bytes = new Uint8Array([0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00]);
WebAssembly.instantiate(bytes).then(result => {
console.log(result.instance.exports);
});Módulo e instancia de WebAssembly
WebAssembly.Module es la representación compilada y sin estado — segura de reutilizar entre varias instancias. WebAssembly.Instance guarda el estado en tiempo de ejecución (memoria, globales). Compilar una vez e instanciar muchas veces es eficiente para lanzar workers paralelos.
// Two-step: compile then instantiate
const module = await WebAssembly.compile(bytes);
const instance = await WebAssembly.instantiate(module, importObject);
console.log(instance.exports.add(1, 2));
// Module is stateless & shareable across instances
const instance2 = await WebAssembly.instantiate(module, importObject);
// Each instance has its own memory and globalsSoporte de navegadores y detección de características
WebAssembly 1.0 está soportado en cualquier navegador moderno. Las propuestas más nuevas (SIMD, excepciones, threads, GC) necesitan detección de características. WebAssembly.validate comprueba si unos bytes forman un módulo válido sin compilar.
// Check basic WebAssembly support
if (typeof WebAssembly !== 'undefined') {
console.log('WebAssembly is supported');
}
// Verify the engine can actually compile
WebAssembly.validate(new Uint8Array([
0x00, 0x61, 0x73, 0x6d, 0x01, 0x00, 0x00, 0x00
])); // true if valid module
// Feature-detect newer proposals
const hasSIMD = typeof WebAssembly.Module !== 'undefined';
const hasExceptions = 'exceptions' in WebAssembly;Streaming vs no streaming
instantiateStreaming compila el módulo a medida que llega por la red — arranque más rápido. El servidor DEBE enviar 'Content-Type: application/wasm'. Si usas un CDN o un host estático sin esa cabecera, recurre a la vía del ArrayBuffer.
// Streaming (preferred): compiles while downloading
WebAssembly.instantiateStreaming(fetch('m.wasm'), imports);
// Non-streaming: must download fully first
const res = await fetch('m.wasm');
const buf = await res.arrayBuffer();
WebAssembly.instantiate(buf, imports);
// Streaming requires correct MIME type:
// Content-Type: application/wasmNúmero mágico y cabecera de Wasm
El número mágico del binario Wasm es el string ASCII '\0asm' seguido de una versión de 4 bytes little-endian. Esta cabecera permite validar que un archivo es Wasm antes de compilar. El formato se organiza en secciones (Type, Import, Function, Memory, etc.).
// Every .wasm file starts with this 8-byte header:
// 0x00 0x61 0x73 0x6d -> "\0asm"
// 0x01 0x00 0x00 0x00 -> version 1
const magic = [0x00, 0x61, 0x73, 0x6d];
const version = [0x01, 0x00, 0x00, 0x00];
// Quick validity check
function isWasm(bytes) {
return bytes[0] === 0x00 && bytes[1] === 0x61
&& bytes[2] === 0x73 && bytes[3] === 0x6d;
}Hola Wasm (ejemplo mínimo)
Una app Wasm mínima: el módulo importa una función 'log' desde JS y exporta 'greet' que la llama. El formato WAT (WebAssembly Text) es la representación legible por humanos, compilada a binario con wat2wasm. Los navegadores solo ejecutan la forma binaria.
<!-- index.html -->
<script>
WebAssembly.instantiateStreaming(fetch('hello.wasm'))
.then(({ instance }) => {
instance.exports.greet(); // logs "Hello, Wasm!"
});
</script>
;; hello.wat (compiled to hello.wasm via wat2wasm)
(module
(import "console" "log" (func $log (param i32)))
(func (export "greet")
i32.const 72 ;; 'H'
call $log
)
)Formato de texto WAT
Módulo y S-expresiones
WAT (formato de texto de WebAssembly) es la representación textual de Wasm. La totalidad va envuelta en una s-expresión (module ...). Las instrucciones se escriben en orden basado en pila: primero se apilan los operandos y luego la operación los consume.
;; WAT uses s-expressions: (keyword args...)
(module
;; function definitions, exports, etc. go here
)
;; Nested expressions form the instruction sequence
(module
(func $add (param $a i32) (param $b i32) (result i32)
local.get $a
local.get $b
i32.add
)
(export "add" (func $add))
)Comentarios en WAT
WAT soporta dos estilos de comentario: ';;' para una línea y '(; ... ;)' para bloques. Los comentarios de bloque pueden anidar y ocupar varias líneas — útil para desactivar trozos de código durante el desarrollo.
;; Single-line comment (starts with ;;)
(func (export "f")
i32.const 1 ;; push 1
drop ;; discard
)
(; Block comment
can span
multiple lines ;)
(func (export "g")
nop
)Sintaxis de definición de funciones
Las funciones se declaran con (func ...). Los parámetros usan (param $name type) y los resultados (result type). El '$name' es opcional — sin él, funciones/locales se referencian por índice numérico. Los retornos multi-valor requieren la propuesta multi-value (ampliamente soportada).
;; Named function with params and result
(func $name (param $p1 i32) (param $p2 f64) (result i32)
;; body
)
;; Anonymous function (referenced by index)
(func (param i32) (result i32)
local.get 0
)
;; Multiple results (multi-value proposal)
(func $swap (param i32 i32) (result i32 i32)
local.get 1
local.get 0
)Export e import en línea
WAT soporta las anotaciones en línea (export "name") y (import "module" "field") sobre funciones, memorias, tablas y globales — un atajo de las formas expandidas (export ...) / (import ...). Ambas compilan a una salida binaria idéntica.
;; Inline export on a function
(func (export "add") (param i32 i32) (result i32)
local.get 0
local.get 1
i32.add
)
;; Inline import
(func $log (import "env" "log") (param i32))
;; Inline export on memory
(memory (export "mem") 1)
;; Expanded form (equivalent)
(func $add (param i32 i32) (result i32) ...)
(export "add" (func $add))Segmentos de datos
Los segmentos de datos inicializan la memoria lineal en la instanciación (activos) o de forma perezosa vía memory.init (pasivos). Los strings incluyen secuencias de escape como \00 para el terminador nulo y \n para el salto de línea. data.drop libera el almacenamiento del segmento tras copiarlo.
;; Initialize memory with bytes at offset 0
(memory 1)
(data (i32.const 0) "Hello, Wasm!\00")
;; Named data segment (active)
(data $msg (i32.const 0) "Hello\00")
;; Passive data segment (used with memory.init)
(data $passive "lazy-loaded bytes")
;; Drop a data segment to free its memory
(data.drop $msg)Conversión wat2wasm y wasm2wat
WABT (WebAssembly Binary Toolkit) ofrece wat2wasm (texto→binario), wasm2wat (binario→texto), wasm-validate y wasm-objdump. Son esenciales para inspeccionar, depurar y escribir módulos Wasm a mano. La forma .wat es para humanos; la forma .wasm es la que ejecutan los navegadores.
# Install the WebAssembly Binary Toolkit (WABT)
# macOS: brew install wabt
# Ubuntu: apt install wabt
# Convert text -> binary
wat2wasm hello.wat -o hello.wasm
# Convert binary -> text (disassemble)
wasm2wat hello.wasm -o hello.wat
# Validate a .wasm file
wasm-validate hello.wasm
# Print module structure
wasm-objdump -x hello.wasmTipos de valor
Tipos de valor básicos (i32/i64/f32/f64)
Wasm solo tiene cuatro tipos de valor básicos: i32, i64, f32, f64. El signo de los enteros lo determina la operación (p. ej., i32.div_s vs i32.div_u), no el tipo. Esto mantiene el sistema de tipos mínimo y predecible.
;; Wasm has exactly four basic value types:
;; i32 - 32-bit integer
;; i64 - 64-bit integer
;; f32 - 32-bit float
;; f64 - 64-bit float
(func (param i32) (param i64) (param f32) (param f64)
(result f64)
local.get 2 ;; f32
f64.promote_f32
)
;; Integers are signed or unsigned PER OPERATION,
;; not per type. Use i32.add_s / i32.div_u etc.Literales numéricos en WAT
Los literales numéricos en WAT soportan las formas decimal, hex (0x) y binaria (0b). Los floats soportan notación científica, infinito (inf) y NaN. Los literales de WAT son sin signo por defecto — los enteros negativos se codifican con un '-' inicial.
;; Integer literals
i32.const 42
i32.const -7
i32.const 0xff ;; hex
i32.const 0b1010 ;; binary
;; Float literals
f64.const 3.14
f64.const 1e10
f64.const -0.0
f64.const inf
f64.const nan
;; 64-bit
i64.const 9007199254740992 ;; 2^53Conversiones de tipos
Las conversiones usan un esquema de nombres consistente: extend (de menor→mayor), wrap (de mayor→menor), convert (int↔float), reinterpret (cast a nivel de bits), demote/promote (precisión float). Las variantes signadas usan _s y las no signadas _u.
;; Extend i32 to i64
i64.extend_i32_s ;; sign-extend
i64.extend_i32_u ;; zero-extend
;; Wrap i64 to i32
i32.wrap_i64
;; Integer <-> Float
f32.convert_i32_s
f64.convert_i64_u
i32.trunc_f32_s ;; truncate (toward zero)
i32.reinterpret_f32 ;; bit-level reinterpret
;; Demote / promote floats
f32.demote_f64
f64.promote_f32Tipo SIMD v128
El tipo v128 empaqueta 16 bytes en un único registro SIMD. Los lanes se direccionan como i32x4 (4×int32), f32x4 (4×float32), i16x8, i8x16, f64x2. SIMD acelera las cargas de imagen/audio/criptografía al operar sobre varios valores por instrucción.
;; SIMD: 128-bit vector type (fixed-width SIMD proposal)
(module
(func (param v128) (result v128)
local.get 0
v128.not ;; bitwise NOT
)
(func (result v128)
v128.const i32x4 1 2 3 4
)
)
;; Vector operations: i32x4, i16x8, i8x16, f32x4, f64x2
v128.const f32x4 1.0 2.0 3.0 4.0
i32x4.addTipos de referencia (funcref/externref)
La propuesta de reference types añade funcref (puntero a función) y externref (referencia opaca al host). externref es potente: permite que Wasm guarde objetos de JS sin copiarlos ni serializarlos. Combinado con tablas, habilita patrones de callbacks flexibles.
;; Reference types proposal adds:
;; funcref - reference to a function (in a table)
;; externref - opaque reference to a host (JS) object
(module
(table 1 funcref)
(func (param externref) (result externref)
local.get 0 ;; pass through a JS object
)
)
;; In JS, externref lets you pass arbitrary objects
;; through Wasm without serialization:
instance.exports.store({ hello: 'world' });Funciones
Definir y llamar funciones
Las funciones son la unidad fundamental de código. call invoca una función por nombre/índice. Los argumentos se apilan antes de la llamada; los resultados quedan en la pila cuando la función retorna. La pila debe coincidir con la declaración (result ...).
(module
(func $add (param $a i32) (param $b i32) (result i32)
local.get $a
local.get $b
i32.add
)
(func $double (param $x i32) (result i32)
local.get $x
local.get $x
i32.add ;; or: i32.const 2 i32.mul
)
(func (export "use")
i32.const 5
i32.const 7
call $add ;; -> 12 on stack
drop
)
)Parámetros y variables locales
Los parámetros son locales inmutables indexados desde 0. Los locales declarados (local $name type) se inicializan a cero y son mutables. Usa local.get, local.set y local.tee (asignar + dejar en la pila). Los locales son el único almacenamiento mutable de Wasm fuera de memoria/globales.
(func $f (param $a i32) (param $b i32) (result i32)
(local $sum i32) ;; mutable local
(local $i i32)
local.get $a
local.get $b
i32.add
local.set $sum ;; store into local
i32.const 0
local.set $i
local.get $sum
)
;; tee: set and keep on stack
local.tee $sum ;; $sum = top; stays on stackMúltiples valores de retorno
La propuesta multi-value permite que las funciones devuelvan varios valores (y acepten cero). Los motores importantes la soportan desde 2020. Elimina la necesidad de parámetros de salida vía memoria y hace naturales modismos como swap/minmax.
;; Multi-value: return two i32 values
(func $minmax (param $a i32) (param $b i32) (result i32 i32)
local.get $a
local.get $b
i32.lt_s
if (result i32 i32)
local.get $a
local.get $b
else
local.get $b
local.get $a
end
)
;; Caller receives both on the stack
(func (export "use")
i32.const 3
i32.const 8
call $minmax
;; stack: [min=3, max=8]
drop drop
)Recursión
Wasm soporta la recursión directa — una función puede llamarse a sí misma. No hay optimización de llamada final (tail-call) en el Wasm MVP (la propuesta tail-call añade return_call). La recursión profunda arriesga desbordamiento de pila, así que prefiere bucles iterativos en código de producción.
(module
(func $fact (param $n i32) (result i32)
local.get $n
i32.const 1
i32.le_s
if (result i32)
i32.const 1
else
local.get $n
local.get $n
i32.const 1
i32.sub
call $fact ;; recursive call
i32.mul
end
)
(export "factorial" (func $fact))
)Export en línea y llamadas con nombre
El (export "name") en línea sobre una definición de función es un atajo de una declaración (export ...) aparte. call_ref (propuesta de reference types) invoca una función vía una funcref directamente, habilitando funciones como valores de primera clase sin consulta de tabla.
(module
;; Inline export on definition
(func $add (export "add") (param i32 i32) (result i32)
local.get 0
local.get 1
i32.add
)
;; call_ref: call via funcref (reference types)
(func $caller (param $f funcref) (param i32) (result i32)
local.get 1
local.get 0
call_ref (param i32) (result i32)
)
)Función start
Un módulo puede declarar una función (start $func) que corre automáticamente al instanciar — útil para inicialización. No toma argumentos ni devuelve nada. Solo se permite una función start por módulo.
(module
(func $init
;; runs once at instantiation
i32.const 0
i32.const 42
i32.store
)
(start $init) ;; declare as start function
(memory (export "mem") 1)
)
;; The start function runs automatically after
;; instantiation, before instantiate() resolves.
;; It takes no params and returns nothing.Memoria
Declarar memoria lineal
La memoria lineal es una región contigua tipo ArrayBuffer, que crece en páginas de 64KiB. (memory 1 10) declara initial=1, max=10. La memoria es la única forma de pasar datos en bloque (strings, arrays) entre Wasm y JS. Expórtala para acceder desde JS.
(module
;; 1 page = 64KiB. Declare 1 page, max 10.
(memory $mem 1 10)
(export "memory" (memory $mem))
;; JS-side: read/write the exported memory
;; const buf = new Uint8Array(instance.exports.memory.buffer);
)Crecimiento de memoria
memory.grow añade páginas y devuelve el tamaño anterior (en páginas), o -1 si falla. Crucialmente, crecer desacopla el ArrayBuffer subyacente — todas las vistas TypedArray existentes quedan inservibles. Recrea siempre las vistas tras cualquier llamada a grow.
(func $grow (result i32)
i32.const 1 ;; request 1 more page
memory.grow ;; returns previous size (or -1)
)
;; In JS, growing detaches the old buffer!
const prev = instance.exports.grow();
const buf = new Uint8Array(instance.exports.memory.buffer);
// OLD buf references are now detached — re-create views!Operaciones load y store
Los loads/stores tienen variantes por tamaño (8/16/32/64 bits) y extensión de signo (_s/_u). offset=N añade una constante al operando de dirección; align= es una pista (debe ser ≤ al tamaño). Todas las direcciones son offsets en bytes dentro de la memoria lineal.
;; Load: read from memory at address (top of stack)
i32.load offset=0 align=2 ;; 4-byte aligned load
i32.load8_u ;; 1 byte, zero-extended
i32.load16_s ;; 2 bytes, sign-extended
f64.load ;; 8-byte float load
;; Store: write value at address
i32.const 100 ;; address
i32.const 42 ;; value
i32.store ;; mem[100] = 42
i32.const 100
i32.const 0xFF
i32.store8 ;; write 1 byteTamaños de memoria y alineación
La alineación en Wasm es una pista de rendimiento, no una restricción de corrección — el acceso no alineado siempre funciona. El valor 'align' no debe superar el tamaño natural de la operación. memory.size devuelve el número actual de páginas (cada una de 64KiB).
;; Each load/store has a natural alignment:
;; i32.load -> 4 bytes
;; i64.load -> 8 bytes
;; f32.load -> 4 bytes
;; i32.load8 -> 1 byte
;; Explicit alignment hint (does not affect correctness)
i32.load align=2 ;; may be slower but still works
;; memory.size returns current pages
(func $pages (result i32)
memory.size
)Memoria compartida y atómicos
La memoria compartida (la propuesta threads) permite que varias instancias/Workers de Wasm compartan una misma memoria para paralelismo. Las operaciones atómicas (i32.atomic.load/store/rmw.add/cmpxchg) aportan sincronización. Requiere aislamiento cross-origin (cabeceras COOP/COEP) en los navegadores.
(module
;; Shared memory (threads proposal)
(memory 1 1 shared)
(export "memory" (memory 0))
;; Atomic operations
(func (param i32 i32)
local.get 0 ;; address
local.get 1 ;; value
i32.atomic.store
)
(func (param i32) (result i32)
local.get 0
i32.atomic.load
)
(func (param i32) (result i32)
local.get 0
i32.const 1
i32.atomic.rmw.add ;; atomic read-modify-write
)
)Leer strings de memoria
Wasm no tiene tipo string nativo — los strings son secuencias de bytes en la memoria lineal, típicamente pasados como pares (puntero, longitud). TextEncoder/TextDecoder manejan la conversión UTF-8. Asegúrate siempre de que la región de memoria sea lo bastante grande antes de escribir.
// Wasm has no string type — strings live in linear memory.
// Decode UTF-8 from a (ptr, len) pair returned by Wasm:
function readString(memory, ptr, len) {
const bytes = new Uint8Array(memory.buffer, ptr, len);
return new TextDecoder('utf-8').decode(bytes);
}
// Writing a string into Wasm memory:
function writeString(memory, str, ptr) {
const bytes = new TextEncoder().encode(str);
const view = new Uint8Array(memory.buffer, ptr, bytes.length);
view.set(bytes);
return bytes.length; // return length
}Tablas
Declarar tablas
Las tablas son arrays de referencias (normalmente funcref) usadas para llamadas indirectas y despacho dinámico. A diferencia de la memoria (que guarda bytes), las tablas guardan referencias opacas que Wasm no puede falsificar. Los segmentos (elem ...) inicializan los slots de la tabla al instanciar.
(module
;; A table of function references, initial size 1
(table 1 funcref)
(export "table" (table 0))
;; With max size
(table $t 4 16 funcref)
;; elem segment: initialize table slots
(elem (i32.const 0) $fn1 $fn2 $fn3)
(func $fn1)
(func $fn2)
(func $fn3)
)Tablas funcref y call_indirect
call_indirect despacha una llamada a través de una entrada de la tabla por índice. La declaración (type ...) es obligatoria — Wasm comprueba en tiempo de ejecución que la firma de la función coincide (un desajuste de firma provoca un trap). Es la base de las vtables y del despacho orientado a objetos en Wasm.
(module
(type $bin (func (param i32 i32) (result i32)))
(table 3 funcref)
(func $add (param i32 i32) (result i32)
local.get 0 local.get 1 i32.add)
(func $sub (param i32 i32) (result i32)
local.get 0 local.get 1 i32.sub)
(func $mul (param i32 i32) (result i32)
local.get 0 local.get 1 i32.mul)
(elem (i32.const 0) $add $sub $mul)
(func (export "dispatch") (param i32 i32 i32) (result i32)
local.get 0 ;; arg a
local.get 1 ;; arg b
local.get 2 ;; table index
call_indirect (type $bin)
)
)Crecer, obtener y fijar tablas
table.grow añade slots y devuelve el tamaño anterior (o -1). table.get/table.set leen/escriben entradas por índice. Hacer crecer una tabla permite registrar callbacks en tiempo de ejecución. Tamaño inicial + límites máximos de crecimiento para evitar asignaciones desbocadas.
(func $addSlot (param funcref) (result i32)
local.get 0
i32.const 1 ;; grow by 1
table.grow ;; returns old size, or -1
)
(func $read (param i32) (result funcref)
local.get 0
table.get
)
(func $write (param i32 funcref)
local.get 0 ;; index
local.get 1 ;; funcref
table.set
)Tablas externref para objetos del host
Las tablas externref almacenan referencias opacas a objetos del host (JS) — Wasm puede guardarlas y pasarlas, pero no puede inspeccionar su contenido. Ideal para registro de callbacks, tablas de handles de JS y para tender puentes entre APIs de JS orientadas a objetos y Wasm.
(module
;; Table holding opaque JS objects
(table 8 externref)
(export "table" (table 0))
(func $store (param i32 externref)
local.get 0
local.get 1
table.set
)
(func $load (param i32) (result externref)
local.get 0
table.get
)
)
// JS: pass arbitrary objects
instance.exports.store(2, { callback: () => 42 });Patrón de despacho dinámico
El patrón de despacho dinámico: guarda las operaciones en una tabla y luego call_indirect por índice. Combinado con la comprobación de tipos obligatoria, da un polimorfismo seguro estilo vtable. Así implementan el despacho los enums de Rust, las funciones virtuales de C++ y los intérpretes.
(module
(type $op (func (param i32 i32) (result i32)))
(table 4 funcref)
(elem (i32.const 0) $add $sub $mul $div)
(func $add (param i32 i32) (result i32)
local.get 0 local.get 1 i32.add)
(func $sub (param i32 i32) (result i32)
local.get 0 local.get 1 i32.sub)
(func $mul (param i32 i32) (result i32)
local.get 0 local.get 1 i32.mul)
(func $div (param i32 i32) (result i32)
local.get 0 local.get 1 i32.div_s)
(func (export "apply") (param $op i32) (param $a i32) (param $b i32)
(result i32)
local.get $a
local.get $b
local.get $op
call_indirect (type $op)
)
)Globales
Declarar globales
Los globales son valores únicos a nivel de módulo, inmutables (por defecto) o mutables (mut). Persisten entre llamadas a funciones y son útiles para contadores, flags de configuración y constantes. Los globales mutables son el único estado mutable compartido fuera de memoria/tablas.
(module
;; Immutable global (const)
(global $counter (mut i32) (i32.const 0))
;; Read-only global
(global $pi f64 (f64.const 3.14159265))
(func $increment
global.get $counter
i32.const 1
i32.add
global.set $counter
)
)Globales mutables vs inmutables
Sin 'mut', un global es inmutable y global.set es un error de compilación. El inicializador debe ser una expresión constante (p. ej., i32.const, ref.null, global.get de un global importado inmutable). Elige inmutable por defecto por seguridad.
(module
;; (global $name type init) -> immutable
;; (global $name (mut type) init) -> mutable
(global $version i32 (i32.const 3))
;; global.set $version ;; ERROR: immutable
(global $state (mut i32) (i32.const 0))
(func (export "toggle")
global.get $state
i32.eqz
if
i32.const 1 global.set $state
else
i32.const 0 global.set $state
end
)
)Importar globales
Los globales importados permiten al host inyectar valores de configuración (u objetos WebAssembly.Global) en un módulo al instanciar. Los globales importados inmutables pueden inicializar otros globales. WebAssembly.Global es el envoltorio visible desde JS para globales compartidos mutables.
(module
;; Import a global from JS
(global $env (import "env" "version") i32)
;; Mutable imported global
(global $flag (import "env" "flag") (mut i32))
(func (export "ver") (result i32)
global.get $env
)
)
// JS side
const imports = {
env: {
version: 3,
flag: new WebAssembly.Global({ value: 'i32', mutable: true }, 0)
}
};Exportar y compartir globales
Los globales exportados son accesibles desde JS como objetos WebAssembly.Global con una propiedad .value (legible y, si es mutable, escribible). Compartir un objeto Global entre varias instancias de módulo es una forma limpia de coordinar estado sin tocar la memoria.
(module
(global $g (export "counter") (mut i32) (i32.const 0))
(func (export "inc")
global.get $g
i32.const 1
i32.add
global.set $g
)
)
// JS reads/writes the global directly
const g = instance.exports.counter;
g.value; // 0
instance.exports.inc();
g.value; // 1
g.value = 100; // write directlyCasos de uso de los globales
Los globales encajan en tres patrones: (1) constantes de configuración importadas, (2) contadores/estado persistentes compartidos entre instancias, (3) resultados de cálculo cacheados. Son más simples que la memoria para valores únicos y visibles para varias instancias si se comparten vía JS.
(module
;; Configuration constants
(global $maxSize (import "config" "maxSize") i32)
(global $debug (import "config" "debug") i32)
;; Persistent counters
(global $calls (mut i32) (i32.const 0))
(func (export "handle") (result i32)
global.get $calls
i32.const 1
i32.add
global.set $calls
global.get $calls
)
)Imports y exports
Importar funciones
Los imports permiten que Wasm llame a funciones del host (JS). Cada import se identifica con un nombre de dos niveles (module, field). El objeto de imports pasado a instantiate debe coincidir con esos nombres. Los imports son la forma en que Wasm alcanza el exterior — I/O, logging, planificación.
(module
;; Import a function under module.field naming
(func $log (import "console" "log") (param i32))
(func $now (import "env" "now") (result f64))
(func (export "run")
i32.const 42
call $log ;; -> console.log(42)
call $now
drop
)
)
// JS
WebAssembly.instantiateStreaming(fetch('m.wasm'), {
console: { log: x => console.log('wasm:', x) },
env: { now: () => performance.now() }
});Importar memoria
Importar memoria permite que varios módulos Wasm (y JS) compartan una región de memoria — la base de las 'librerías' Wasm. Un módulo asigna y escribe; otro lee. Esto compone módulos sin copiar datos y es el precursor del component model.
(module
(memory (import "env" "memory") 1)
(func (export "writeHi")
i32.const 0
i32.const 72 ;; 'H'
i32.store8
)
)
// Shared memory across multiple modules:
const memory = new WebAssembly.Memory({ initial: 1 });
WebAssembly.instantiateStreaming(fetch('a.wasm'), { env: { memory } });
WebAssembly.instantiateStreaming(fetch('b.wasm'), { env: { memory } });
// Both modules read/write the SAME memoryImportar globales y tablas
Los globales y las tablas también pueden importarse, habilitando estado compartido y tablas de punteros a funciones entre módulos. WebAssembly.Table es el constructor de JS. Los globales importados mutables permiten al host influir dinámicamente en el comportamiento de Wasm sin recompilar el módulo.
(module
(global $seed (import "env" "seed") i32)
(table (import "env" "table") 4 funcref)
(func (export "rand") (result i32)
global.get $seed
i32.const 1103515245
i32.mul
i32.const 12345
i32.add
;; (truncated LCG step)
)
)
// JS provides the imports
const imports = {
env: {
seed: 42,
table: new WebAssembly.Table({
element: 'funcref', initial: 4, maximum: 16
})
}
};Exportar funciones, memoria y tablas
Cualquier cosa declarada en un módulo puede exportarse: funciones, memoria, tablas, globales. Las exportaciones se convierten en propiedades de instance.exports. Las exportaciones de memoria dan a JS una vista del heap lineal; las de globales exponen objetos WebAssembly.Global; las de tablas exponen referencias a funciones.
(module
(memory 1)
(table 2 funcref)
(global $c (mut i32) (i32.const 0))
(func (export "add") (param i32 i32) (result i32)
local.get 0 local.get 1 i32.add)
(export "memory" (memory 0))
(export "table" (table 0))
(export "counter" (global $c))
)
// JS usage
const { add, memory, table, counter } = instance.exports;
add(2, 3); // 5
new Uint8Array(memory.buffer); // raw bytes
table.get(0); // funcref
counter.value; // 0Imports y exports en línea
Las anotaciones en línea (import "m" "f") y (export "name") son azúcar sintáctico — compilan al mismo binario que las formas independientes (import ...)/(export ...). Una única definición puede llevar un export en línea, pero los imports y exports de los elementos importados se declaran por separado.
(module
;; Inline import (compact form)
(func $log (import "env" "log") (param i32))
;; Inline export on function
(func (export "add") (param i32 i32) (result i32)
local.get 0 local.get 1 i32.add
)
;; Inline export on memory
(memory (export "mem") 1)
;; Inline import + export combined is NOT allowed;
;; a definition imports OR exports, not both.
)Buenas prácticas del objeto de imports
Estructura el objeto de imports para que coincida con los nombres (module, field) del módulo. Valida los imports obligatorios antes de instanciar para dar errores claros. Envuelve las funciones del host con try/catch donde convenga — una excepción no capturada dentro de un import provoca un trap en el llamador Wasm.
// Build a typed import object
const imports = {
env: {
log: (i) => console.log('[wasm]', i),
now: () => performance.now(),
abort: () => { throw new Error('wasm abort'); },
memory: new WebAssembly.Memory({ initial: 1 }),
seed: 42,
}
};
// Validate imports before instantiation:
function checkImports(imports, required) {
for (const [mod, fields] of Object.entries(required)) {
for (const f of fields) {
if (!imports[mod]?.[f] === undefined) {
throw new Error(`Missing import: ${mod}.${f}`);
}
}
}
}Flujo de control
block
block crea un ámbito etiquetado del que salen las ramas (vía br). Las ramas en Wasm son estructuradas — solo pueden saltar al final de un block/loop/if que las contenga. Un block con (result ...) deja su valor en la pila al saltar hacia él o al caer en su fin.
;; block: a labeled group with a single exit
(block $b
i32.const 1
i32.const 2
i32.add
;; br $b exits the block (with optional value)
br $b
;; unreachable code
)
;; stack now has the result of the block
;; Blocks can produce a value (multi-value):
(block $b (result i32)
i32.const 42
br $b
)loop
loop es como block, pero br $loop salta al PRINCIPIO del bucle (continuando la iteración) en lugar del final. Es lo contrario de block. Wasm no tiene palabras clave for/while — la iteración se construye con loop + un br_if condicional.
;; loop: a block whose br jumps back to the TOP
(func $count (param $n i32) (result i32)
(local $i i32) (local $sum i32)
i32.const 0 local.set $i
i32.const 0 local.set $sum
(loop $loop
local.get $i
local.get $n
i32.lt_s
if
local.get $sum
local.get $i
i32.add
local.set $sum
local.get $i
i32.const 1
i32.add
local.set $i
br $loop ;; jump back to loop start
end
)
local.get $sum
)if / else
if consume un i32 de la pila (distinto de cero = true). La cláusula (result ...) hace que el if produzca un valor cuando ambas ramas coinciden en tipo. Se permite un if sin else; la rama puede estar vacía. if es azúcar de block + br_if.
;; if consumes a condition from the stack
(func $abs (param $x i32) (result i32)
local.get $x
if (result i32)
local.get $x
else
i32.const 0
local.get $x
i32.sub ;; negate
end
)
;; if without else (no result)
(func (param i32)
local.get 0
if
;; do something only if non-zero
end
)br y br_if
br $etiqueta salta al FINAL del block/if nombrado (o al PRINCIPIO de un loop). br_if hace lo mismo condicionalmente. Las etiquetas también pueden ser numéricas (br 0 = la más interna). Ramificar con un valor lo deja en la pila — la forma idiomática de Wasm para retornar antes.
;; br: unconditional branch to a label
(block $outer
(block $inner
br $inner ;; exits inner
br $outer ;; exits outer (unreachable here)
)
)
;; br_if: branch only if top of stack is non-zero
(func $clamp (param $x i32) (result i32)
(block $done (result i32)
local.get $x
i32.const 100
i32.gt_s
br_if $done ;; if x > 100, branch with...
i32.const 100 ;; ...100 on the stack
local.get $x
i32.const 0
i32.lt_s
br_if $done ;; if x < 0, branch with...
i32.const 0 ;; ...0
local.get $x ;; else x
)
)br_table (switch)
br_table implementa un switch: consume un índice i32 y salta a una de las etiquetas listadas, o a la última (por defecto) si está fuera de rango. Anida los bloques de fuera hacia dentro para que cada caso pueda devolver su valor. Es la forma más eficiente de despachar según una etiqueta.
;; br_table: jump table (like a C switch)
(func $dayName (param $d i32) (result i32)
(block $default
(block $sat
(block $sun
local.get $d
br_table $sun $sat $default
)
i32.const 0 ;; Sunday
return
)
i32.const 6 ;; Saturday
return
)
i32.const -1 ;; default
)
;; br_table $l0 $l1 $l2 ... $default
;; index 0 -> $l0, 1 -> $l1, ... out-of-range -> $defaultreturn y unreachable
return sale inmediatamente de la función con el valor en la pila. unreachable siempre provoca un trap (lanza una excepción en tiempo de ejecución) — sirve para marcar rutas de código que nunca deberían ejecutarse, similar a assert(false). Ambos son válvulas de escape del flujo de control más allá del modelo estructurado de bloques.
(func $find (param $arr i32) (param $len i32) (param $key i32)
(result i32)
(local $i i32)
i32.const 0 local.set $i
(block $notFound
(loop $loop
local.get $i
local.get $len
i32.ge_s
br_if $notFound
;; load arr[i] and compare...
local.get $i
i32.const 1
i32.add
local.set $i
br $loop
)
)
unreachable ;; traps if reached
)
;; return: early exit from the function
;; unreachable: always traps (used to mark bugs)Interoperabilidad con JS
Pasar números
i32/f32/f64 se mapean directamente a números de JS. i64 se mapea a BigInt de JS (los enteros grandes exceden el rango seguro de Number). Usa siempre BigInt para parámetros/retornos i64. La conversión es sin copias en la frontera, pero cruzarla con frecuencia tiene sobrecarga — agrupa operaciones dentro de Wasm.
// Numbers pass directly across the Wasm/JS boundary.
const exports = instance.exports;
exports.add(2, 3); // 5 (i32 -> JS number)
exports.square(4); // 16
exports.compute(1.5, 2.5); // f64 -> JS number
// i64 caveat: before BigInt integration, i64 returns
// caused problems. Now Wasm i64 maps to JS BigInt:
const big = exports.bigResult(); // 9007199254740993n
// Passing a BigInt to an i64 param:
exports.takeBigInt(123n);Pasar strings
Los strings cruzan la frontera como secuencias de bytes UTF-8: JS los codifica en la memoria de Wasm y luego pasa (puntero, longitud). A menudo Wasm exporta helpers alloc/free, o empaquetas ambos en un único i64 (32 bajos = ptr, 32 altos = len). Libera o reutiliza siempre el buffer para evitar fugas.
// Wasm has no string type. Encode UTF-8 into memory,
// pass (ptr, len) to Wasm:
function passString(memory, str) {
const bytes = new TextEncoder().encode(str);
const ptr = instance.exports.alloc(bytes.length);
new Uint8Array(memory.buffer, ptr, bytes.length).set(bytes);
instance.exports.processString(ptr, bytes.length);
instance.exports.dealloc(ptr, bytes.length);
}
// Receiving a string back:
function recvString(memory, ptrLen) {
const ptr = ptrLen >>> 0;
const len = ptrLen >>> 32;
const bytes = new Uint8Array(memory.buffer, ptr, len);
return new TextDecoder().decode(bytes);
}Pasar arrays y datos en bloque
Para datos numéricos en bloque, mira la memoria de Wasm como un TypedArray del tipo adecuado (Float32Array, Int32Array, etc.) y usa .set() para copiar. Es la vía más rápida — tipo memcpy. Recuerda la alineación de punteros (4 bytes para i32/f32, 8 para i64/f64) y libera siempre la memoria.
// Write a JS array into Wasm memory:
function passArray(memory, arr) {
const view = new Float32Array(memory.buffer);
const ptr = instance.exports.alloc(arr.length * 4);
const offset = ptr / 4;
for (let i = 0; i < arr.length; i++) view[offset + i] = arr[i];
return ptr;
}
// Faster: use TypedArray.set with a subarray
function passArrayFast(memory, arr) {
const ptr = instance.exports.alloc(arr.length * 4);
new Float32Array(memory.buffer, ptr, arr.length).set(arr);
return ptr;
}Gestión de memoria a través de la frontera
La memoria de Wasm se gestiona manualmente — no hay recolector de basura. Si Wasm exporta alloc/free (o usas un helper tipo malloc), envuelve el acceso de JS en try/finally para garantizar la liberación. Vigila que memory.grow desacopla las vistas del ArrayBuffer — recrea las vistas tras crecer.
// Wasm has no GC — JS must manage allocations.
// Pattern: Wasm exports alloc/free, JS uses them:
const { memory, alloc, free, process } = instance.exports;
function withBuffer(size, fn) {
const ptr = alloc(size);
try {
return fn(new Uint8Array(memory.buffer, ptr, size));
} finally {
free(ptr, size);
}
}
// CAUTION: TypedArray views become detached after
// memory.grow — re-create them after any grow call.WebAssembly.Global
WebAssembly.Global es un envoltorio de JS alrededor de un valor global de Wasm. Crear uno y pasarlo a varias instancias de módulo comparte estado mutable de forma limpia sin tocar la memoria. La propiedad .value lee/escribe el i32/i64/f32/f64 subyacente (o v128/externref).
// Create a global on the JS side
const counter = new WebAssembly.Global(
{ value: 'i32', mutable: true },
0
);
// Pass to Wasm at instantiation
WebAssembly.instantiateStreaming(fetch('m.wasm'), {
env: { counter }
});
// Read/write from JS
counter.value; // 0
counter.value = 10; // set
counter.value++; // 11
// Share across multiple instances
WebAssembly.instantiateStreaming(fetch('m2.wasm'), {
env: { counter } // same Global object
});WebAssembly.Table y errores
WebAssembly.Table guarda referencias a funciones accesibles tanto desde JS como desde Wasm — útil para registros de callbacks y tablas de despacho. Los traps de Wasm (división por cero, memoria fuera de rango, desbordamiento de pila) se manifiestan como WebAssembly.RuntimeError en JS — envuelve las llamadas riesgosas en try/catch.
// Table of function references, callable from JS indirectly
const table = new WebAssembly.Table({
element: 'funcref',
initial: 4,
maximum: 16
});
// Set a slot to a Wasm-exported function
table.set(0, instance.exports.add);
table.get(0)(2, 3); // 5
// Errors propagate as 'RuntimeError' across the boundary:
try {
instance.exports.divide(1, 0);
} catch (e) {
// e instanceof WebAssembly.RuntimeError
console.error('Wasm trapped:', e.message);
}Compilar C/C++ a Wasm
Configuración de Emscripten
Emscripten es el toolchain canónico para compilar C/C++ (y lenguajes LLVM) a Wasm. Agrupa Clang, Binaryen y una libc/libstdc++ portada al navegador. Activa el entorno en cada sesión de shell con emsdk_env. Se actualiza con frecuencia — reinstala periódicamente.
# Install the Emscripten SDK
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh # Linux/macOS
# Windows: emsdk_env.bat
# Verify
emcc --version
# emcc (Emscripten gcc/clang-like replacement)Hola mundo en C
El C estándar funciona tal cual — printf escribe en un terminal virtual que Emscripten proporciona. main() se invoca automáticamente cuando el módulo carga. Las funciones llamadas desde JS deben exportarse con EMSCRIPTEN_KEEPALIVE o con el flag -s EXPORTED_FUNCTIONS.
// hello.c
#include <stdio.h>
int add(int a, int b) {
return a + b;
}
int main() {
printf("Hello from C!\n");
printf("2 + 3 = %d\n", add(2, 3));
return 0;
}Compilar con emcc
emcc dirige la compilación. -O3 activa optimizaciones agresivas (inlining, eliminación de código muerto). EXPORTED_FUNCTIONS lista los símbolos C (con _ inicial) a exponer. MODULARIZE envuelve el cargador como una fábrica para usarlo en bundlers. Formatos de salida: solo .wasm, glue .js + .wasm, o demo .html.
# Standalone .wasm (no main, exported functions only)
emcc add.c -O3 -o add.wasm \
-s EXPORTED_FUNCTIONS='["_add"]' \
-s ALLOW_MEMORY_GROWTH=1
# HTML + JS + Wasm bundle (auto-runs main)
emcc hello.c -o hello.html
# With optimizations and a specific output
emcc hello.c -O3 -s WASM=1 -o hello.js
# Common flags:
# -O0/-O1/-O2/-O3/-Os optimization level
# -s MODULARIZE=1 export as JS module
# -s EXPORT_ES6=1 ES module output
# -s ENVIRONMENT=web target only the webSalida HTML y módulo de Emscripten
El objeto 'Module' de Emscripten es el runtime del lado JS: expone las funciones C con prefijo _, gestiona la memoria (_malloc/_free) y ofrece hooks (print, onRuntimeInitialized). MODULARIZE lo convierte en una fábrica que devuelve una Promise, apta para bundlers y carga asíncrona.
// Generate a runnable HTML demo
// emcc hello.c -o hello.html
// Then open hello.html in a browser.
// Modularized loader (use from JS):
// emcc hello.c -o hello.js -s MODULARIZE=1 -s EXPORT_NAME='createModule'
import createModule from './hello.js';
const Module = await createModule({
print: (text) => console.log('C said:', text),
onRuntimeInitialized: () => {
Module._main(); // call main
const sum = Module._add(2, 3);
console.log('sum:', sum); // 5
}
});Llamar a JS desde C (EM_JS / EM_ASM)
EM_JS define una función JS en línea que C puede llamar directamente — eficiente y síncrono. EM_ASM incrusta un fragmento JS en línea. Usa $0, $1, ... para los argumentos. Estas macros pegan C a las APIs del navegador (DOM, fetch, Web Audio) sin escribir bindings JS aparte.
#include <emscripten.h>
// EM_JS: define a JS function callable from C
EM_JS(void, callAlert, (int x), {
alert("Value from C: " + x);
});
// EM_ASM: inline JS (use $n for arguments)
void logValue(int n) {
EM_ASM({
console.log("C passed:", $0);
}, n);
}
int main() {
callAlert(42);
logValue(99);
return 0;
}Soporte de sistema de archivos (MEMFS)
Emscripten ofrece MEMFS, un sistema de archivos virtual en memoria. fopen/fread/fwrite funcionan como en C. Usa --preload-file para incrustar recursos en el sidecar .data en tiempo de compilación. Para almacenamiento persistente, IDBFS sincroniza con IndexedDB; NODERAWFS expone el sistema de archivos real en Node.
#include <stdio.h>
#include <emscripten.h>
int main() {
// MEMFS: a virtual in-memory filesystem
FILE *f = fopen("/tmp/data.txt", "w");
fprintf(f, "Hello, MEMFS!\n");
fclose(f);
f = fopen("/tmp/data.txt", "r");
char buf[64];
fgets(buf, sizeof(buf), f);
fclose(f);
printf("%s", buf);
return 0;
}
// Preload files at compile time:
// emcc app.c -o app.html \
// --preload-file assets/data.txtCompilar Rust a Wasm
Configuración de wasm-pack
Rust compila a Wasm mediante el target wasm32-unknown-unknown. wasm-pack es la herramienta recomendada — envuelve a cargo, ejecuta wasm-bindgen y produce un paquete listo para npm. Para targets WASI, usa wasm32-wasi en su lugar.
# Install Rust (rustup)
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
# Add the wasm32 target
rustup target add wasm32-unknown-unknown
# Install wasm-pack (the canonical Wasm tool for Rust)
cargo install wasm-pack
# or: curl https://rustwasm.github.io/wasm-pack/installer/init.sh -sSf | sh
# Verify
wasm-pack --versionEstructura de librería Rust
wasm-bindgen es el puente entre Rust y JS. #[wasm_bindgen] marca los elementos a exportar. Los strings, Vec<u8> y objetos JS se convierten automáticamente. El atributo de constructor expone new() como constructor de JS. Genera el glue de JS que hace que Rust se sienta nativo.
// src/lib.rs
use wasm_bindgen::prelude::*;
// Export a function callable from JS
#[wasm_bindgen]
pub fn add(a: i32, b: i32) -> i32 {
a + b
}
// Export a struct with methods
#[wasm_bindgen]
pub struct Counter {
count: i32,
}
#[wasm_bindgen]
impl Counter {
#[wasm_bindgen(constructor)]
pub fn new() -> Counter {
Counter { count: 0 }
}
pub fn increment(&mut self) -> i32 {
self.count += 1;
self.count
}
}Compilar con wasm-pack
wasm-pack build produce un paquete npm publicable: el binario .wasm, el glue de JS y los archivos .d.ts de TypeScript. --target web da un módulo ES autocontenido para uso directo en el navegador; --target bundler se integra con webpack/vite. Los tipos generados dan autocompletado completo de TS.
# Build for the browser (npm package output)
wasm-pack build --target web
# Targets:
# --target web ES module, modern browsers
# --target bundler for webpack/rollup/vite
# --target nodejs CommonJS for Node.js
# --target no-modules global-based
# Output goes to ./pkg/
# my_crate.js JS glue
# my_crate_bg.wasm the binary
# my_crate.d.ts TypeScript types
# Use in JS:
import init, { add } from './pkg/my_crate.js';
await init(); // load the .wasm
console.log(add(2, 3)); // 5wasm-bindgen: interoperabilidad con JS
Los bloques extern importan funciones y clases de JS a Rust. js_namespace = console llama a console.log. method expone las funciones miembro de JS sobre tipos importados. wasm-bindgen se encarga de las conversiones de strings (&str de Rust <-> string de JS) y de la propiedad — sin malabares manuales de memoria.
use wasm_bindgen::prelude::*;
// Call a JS function from Rust
#[wasm_bindgen]
extern "C" {
#[wasm_bindgen(js_namespace = console)]
fn log(s: &str);
}
#[wasm_bindgen]
pub fn run() {
log("Hello from Rust!");
}
// Import a JS class
#[wasm_bindgen(module = "/js/util.js")]
extern "C" {
pub type JsCounter;
#[wasm_bindgen(constructor)]
pub fn new() -> JsCounter;
#[wasm_bindgen(method)]
pub fn tick(this: &JsCounter) -> i32;
}Llamar a JS desde Rust y panics
Las funciones JS importadas aparecen como funciones Rust ordinarias. Usa console_error_panic_hook para obtener backtraces legibles de panics de Rust en la consola del navegador (por defecto los panics hacen trap sin mensaje). El atributo #[wasm_bindgen(start)] ejecuta main() al instanciar — como el main de C.
use wasm_bindgen::prelude::*;
#[wasm_bindgen]
extern "C" {
fn alert(s: &str);
}
#[wasm_bindgen]
pub fn greet(name: &str) {
alert(&format!("Hello, {}!", name));
}
// Install a panic hook for readable errors:
#[wasm_bindgen(start)]
pub fn main() {
console_error_panic_hook::set_once();
}AssemblyScript
Configuración y hola mundo
AssemblyScript es un lenguaje parecido a TypeScript que compila a Wasm. Apunta a desarrolladores que quieren el rendimiento de Wasm sin aprender C/Rust. La sintaxis imita a TS pero con tipos estrictos (i32 en lugar de number). Usa el loader o importa el .wasm directamente.
# Install AssemblyScript compiler
npm install -g assemblyscript
# or use the boilerplate:
npm init assemblyscript my-app
cd my-app
npm install
npm run asbuild
// assembly/index.ts
export function add(a: i32, b: i32): i32 {
return a + b;
}
// Load from JS:
import { instantiate } from "@assemblyscript/loader";
const module = await instantiate(fetch("build/release.wasm"));
console.log(module.exports.add(2, 3)); // 5Tipos en AssemblyScript
A diferencia de TypeScript, AssemblyScript exige tipos numéricos concretos: i32, i64, f32, f64, u8, u16, u32, etc. 'number' se rechaza en compilación. StaticArray evita el GC; ArrayBuffer/TypedArray imitan las APIs de JS. El tipado estricto es lo que permite compilar a un Wasm eficiente.
// Distinct numeric types (NOT just 'number')
let a: i32 = 42;
let b: i64 = 9007199254740993n;
let f: f64 = 3.14;
let u: u32 = 100;
// Bool, string, arrays
let flag: bool = true;
let s: string = "hi";
let arr: i32[] = [1, 2, 3];
// Static arrays (no GC overhead)
let sa: StaticArray<i32> = [1, 2, 3];
// TypedArray-like
let buf: ArrayBuffer = new ArrayBuffer(8);Memoria y strings
AssemblyScript tiene un pequeño GC para objetos gestionados (Array, Map, String). Usa __retain/__release para controlar los ciclos de vida al cruzar a JS. @assemblyscript/loader ofrece __getString, __newString, __getArray, etc., para tender el puente a través de la frontera.
// Strings are UTF-16 in AssemblyScript memory
export function greet(name: string): string {
return "Hello, " + name + "!";
}
// Manual memory management for buffers
export function process(len: i32): i32 {
let buf = new ArrayBuffer(len);
// ...fill buf...
let result = __retain(buf); // prevent GC
return result;
}
// In JS, use the loader's __getString/__newString:
const ptr = module.exports.greet("World");
console.log(module.exports.__getString(ptr));Exports y puntos de entrada
Las funciones y clases marcadas como export se convierten en exportaciones Wasm. Las clases se mapean a objetos compatibles con JS vía el loader. _start es el punto de entrada convencional (como el main de C). La stdlib de AssemblyScript imita Math, Array, Map de JS — haciendo suave la curva de migración.
// assembly/index.ts
export function fib(n: i32): i32 {
if (n < 2) return n;
return fib(n - 1) + fib(n - 2);
}
export class Vector {
constructor(public x: f32, public y: f32) {}
magnitude(): f32 {
return Math.sqrt(this.x * this.x + this.y * this.y);
}
}
// Module start function (runs at instantiation)
export function _start(): void {
// initialization code
}Compilación y optimizaciones
asc es el compilador de AssemblyScript. --optimize (-O) ejecuta wasm-opt de Binaryen. --runtime controla el GC: 'full' (por defecto), 'half' (menor), 'none' (manual). --importMemory permite compartir memoria entre módulos. Los source maps permiten depurar en el código .ts original.
# Build debug vs release
npm run asbuild # both debug and release
# or:
asc assembly/index.ts --outFile release.wasm --optimize
# Common flags
asc index.ts -o release.wasm \
--optimize \
--noAssert \
--runtime half # smaller GC runtime
--importMemory # use imported memory
--sourceMap # emit source map
# Optimize for size:
asc index.ts -o tiny.wasm --optimize --runtime none \
--conformance --noDebugWASI (WebAssembly System Interface)
Qué es WASI
WASI es una interfaz de sistema portable y basada en capacidades para Wasm fuera del navegador. A diferencia de la web, donde Wasm llama a JS, WASI da a Wasm acceso directo (y aislado) a archivos, red y entorno. La seguridad basada en capacidades significa que un programa solo puede tocar los recursos que se le preabren explícitamente.
// WASI = WebAssembly System Interface
// A standardized API for Wasm to access OS capabilities:
// - filesystem (files, directories)
// - network sockets (preview2)
// - environment variables, args
// - clocks, random numbers
// - process exit
// Capability-based security: a Wasm program can
// ONLY access resources it was explicitly granted.
// Targets:
// wasm32-wasi (preview1)
// wasm32-wasip1 (preview1, new name)
// wasm32-wasip2 (preview2, component model)
// Runtimes: wasmtime, wasmer, WasmEdge, browser_wasi_shimRuntime wasmtime
wasmtime es el runtime de referencia para WASI del Bytecode Alliance. --dir preabre un directorio del host (concediendo acceso a archivos). --env pasa variables de entorno. --net activa la red en preview2. Sin concesiones explícitas, el programa Wasm no ve nada — ahí está la seguridad por capacidades en acción.
# Install wasmtime (the reference WASI runtime)
# macOS: brew install wasmtime
# Linux: curl https://wasmtime.dev/install.sh -sSf | bash
# Windows: scoop install wasmtime
# Run a WASI module
wasmtime hello.wasm
# Pass arguments
wasmtime hello.wasm arg1 arg2
# Preopen a directory (grant filesystem access)
wasmtime --dir=. app.wasm
# Set environment variables
wasmtime --env FOO=bar app.wasm
# Allow network (preview2)
wasmtime --net allow app.wasmEjecutar Wasm con WASI (ejemplo en C)
Los programas escritos para WASI parecen programas C ordinarios que usan libc. Compila con clang --target=wasm32-wasi y un sysroot WASI (descarga la release de wasi-sdk). El mismo .wasm corre en wasmtime, wasmer, WasmEdge y otros hosts WASI sin recompilar — portabilidad real.
// wasi_hello.c
#include <stdio.h>
#include <unistd.h>
int main(int argc, char *argv[]) {
printf("Hello from WASI!\n");
printf("argc = %d\n", argc);
for (int i = 0; i < argc; i++) printf(" argv[%d] = %s\n", i, argv[i]);
return 0;
}
# Compile with the WASI SDK
clang --target=wasm32-wasi \
--sysroot=/path/to/wasi-sysroot \
-o hello.wasm wasi_hello.c
# Run
wasmtime hello.wasm foo bar
# Hello from WASI!
# argc = 3
# argv[0] = hello.wasm
# argv[1] = foo
# argv[2] = barAcceso al sistema de archivos con WASI
WASI expone una API de sistema de archivos tipo POSIX (open, read, write, close). Los archivos fuera de los directorios preabiertos son invisibles. Usa --dir=ruta:alias para conceder acceso y renombrar. WASI preview2 introduce interfaces del component model (wasi filesystem, wasi sockets) para APIs más ricas.
// wasi_fs.c — read a file passed via --dir
#include <stdio.h>
#include <fcntl.h>
#include <unistd.h>
int main() {
int fd = open("input.txt", O_RDONLY);
if (fd < 0) { perror("open"); return 1; }
char buf[256];
ssize_t n = read(fd, buf, sizeof(buf) - 1);
if (n > 0) { buf[n] = '\0'; printf("%s", buf); }
close(fd);
return 0;
}
# Grant access, then run:
# wasmtime --dir=. wasi_fs.wasmEntorno y argumentos de WASI
WASI proporciona args y variables de entorno vía las interfaces estándar de C (argv, environ, getenv). El host controla qué se ve — --env concede variables concretas. Esto hace que los programas Wasm sean configurables sin cambios de código y limita la fuga de secretos del host.
// wasi_env.c
#include <stdio.h>
#include <stdlib.h>
extern char **environ;
int main(int argc, char *argv[]) {
printf("Args:\n");
for (int i = 0; i < argc; i++) printf(" %s\n", argv[i]);
printf("Env:\n");
for (char **e = environ; *e; e++) printf(" %s\n", *e);
const char *home = getenv("HOME");
printf("HOME=%s\n", home ? home : "(unset)");
return 0;
}
# Run with env vars:
# wasmtime --env HOME=/tmp --env FOO=bar wasi_env.wasm a b cSockets WASI (preview)
Los sockets WASI forman parte de preview2 (component model). wasi:sockets/tcp y wasi:sockets/udp ofrecen red; wasi:http aporta un cliente HTTP de más alto nivel. Las APIs se están estabilizando — prefiere wasi:http hoy por portabilidad. Runtimes como wasmtime y WasmEdge los implementan.
// WASI preview2 adds TCP/UDP sockets.
// In Rust (using wasi crate):
use wasi::sockets::network::{IpAddress, IpSocketAddress};
// Component-model based sockets:
// - wasi:sockets/tcp
// - wasi:sockets/udp
// - wasi:sockets/ip-name-lookup
# Compile a Rust program for preview2:
cargo build --target wasm32-wasip2 --release
# Run with network access:
wasmtime --net allow target/wasm32-wasip2/release/myapp.wasm
// Note: socket APIs are still stabilizing.
// Use HTTP via wasi:http/types for stability.Depuración
wasm-objdump
wasm-objdump (de WABT) imprime la estructura de un módulo: tipos, imports, exports, firmas de funciones, desensamblado del código y tamaños de secciones. -x da un resumen de alto nivel; -d desensambla los cuerpos de las funciones en instrucciones tipo WAT. Esencial para entender qué contiene realmente un módulo.
# Inspect a .wasm file's structure
wasm-objdump -x module.wasm # everything
wasm-objdump -d module.wasm # disassemble functions
wasm-objdump -s module.wasm # raw section contents
wasm-objdump -j Import -x m.wasm # only the Import section
# Sample -x output:
# Section Type (1) at 0x0008:
# type[0] (i32, i32) -> i32
# Section Function (3) at 0x0015:
# func[0] type=0wasm2wat para inspección
wasm2wat convierte un .wasm binario de vuelta a WAT legible por humanos. Es inestimable para entender módulos de terceros, depurar comportamientos inesperados e ingeniería inversa. El viaje de ida y vuelta (wasm2wat → editar → wat2wasm) preserva el comportamiento, haciendo de WAT un verdadero formato fuente.
# Disassemble binary to readable text
wasm2wat module.wasm -o module.wat
# View in your editor
cat module.wat
# Round-trip: edit .wat, recompile
wat2wasm module.wat -o module.wasm
# Common inspection: find exports
grep "(export" module.wat
# Find imports
grep "(import" module.watDevTools del navegador
La totalidad de los navegadores importantes pueden depurar Wasm en DevTools: ver el WAT desensamblado, fijar breakpoints, inspeccionar locales y la pila de llamadas. Con source maps (Rust, AssemblyScript, Emscripten -g), DevTools mapea de vuelta al código fuente original. La información de depuración DWARF habilita una depuración más rica para C/C++/Rust.
// Chrome/Edge/Firefox DevTools support Wasm debugging:
// 1. Sources tab -> file tree shows .wasm entries
// 2. Click a .wasm to view disassembled WAT
// 3. Set breakpoints on function entries
// 4. Inspect the call stack and locals
// With source maps (Rust/AS), DevTools shows the
// ORIGINAL source (.rs / .ts) instead of WAT.
// Enable in chrome://flags:
// "WebAssembly debugging: Support DWARF"
// Console logging from Wasm:
// Import a JS log function and call it from WAT.
// Rust: wasm_logger / console_log crate.
// AS: console.log via env import.Source maps
Los source maps vinculan las instrucciones Wasm de vuelta al lenguaje fuente original. Rust los emite vía wasm-pack; AssemblyScript vía --sourceMap; Emscripten vía -g4. El comentario sourceMappingURL en el .wasm (sección personalizada) le dice a DevTools dónde encontrar el .map. Sin él, depuras WAT crudo.
# Rust: source maps come automatically with wasm-pack
wasm-pack build --target web --dev
# AssemblyScript: emit source maps
asc index.ts -o release.wasm --sourceMap \
--sourceMap include 'src/**/*.ts'
# Emscripten: include debug info and source map
emcc app.c -g4 -O0 -o app.js \
--source-map-base http://localhost:8000/
# The .map file points DevTools back to the
# original .rs / .ts / .c source files.
# Validate a source map exists:
wasm-objdump -x app.wasm | grep sourceMappingURLErrores y traps comunes
Errores de Wasm recurrentes: imports faltantes (nombres/tipos que no coinciden), traps (unreachable, memoria fuera de rango, desbordamiento de entero al dividir por cero), ArrayBuffers desacoplados (tras grow) y problemas de frontera con i64. Envuelve las llamadas riesgosas en try/catch y valida imports/punteros de entrada para destapar problemas pronto.
// 1. LinkError: "import not found"
// Cause: import object missing a name.
const imports = { env: { log: console.log } };
// Must match (import "env" "log" ...) exactly.
// 2. RuntimeError: "unreachable"
// Cause: Wasm executed unreachable / panic / assert.
// 3. RuntimeError: "out of bounds memory access"
// Cause: load/store at an invalid address.
// Fix: check ptr/len before access; grow memory.
// 4. CompileError: "section size mismatch"
// Cause: corrupted or truncated .wasm file.
// 5. TypeError: "i64 not supported"
// Cause: i64 returns without BigInt integration.
// Fix: use BigInt, or return two i32 values.
// 6. "detached ArrayBuffer"
// Cause: used a TypedArray view after memory.grow.
// Fix: re-create views after grow.Optimización de rendimiento
Inlining y flags -O
-O3 activa el inlining agresivo y las optimizaciones de bucles. wasm-opt (Binaryen) ejecuta pasadas adicionales a nivel Wasm (inlining, código muerto, plegado de constantes) — ejecútalo siempre en producción. -Os/-Oz cambian algo de velocidad por descargas menores. -flto habilita la optimización de programa completo.
# Compilation optimization levels
emcc app.c -O0 -o app.wasm # no optimization (debug)
emcc app.c -O1 -o app.wasm # basic
emcc app.c -O2 -o app.wasm # standard
emcc app.c -O3 -o app.wasm # aggressive (inlining)
emcc app.c -Os -o app.wasm # optimize for size
emcc app.c -Oz -o app.wasm # max size reduction
# Post-optimize with Binaryen
wasm-opt -O3 app.wasm -o app.opt.wasm
wasm-opt -Os app.wasm -o app.small.wasm
# LTO across translation units (C/C++)
emcc app.c -flto -O3 -o app.wasmLayout de memoria y patrones de acceso
La memoria lineal de Wasm es simplemente un ArrayBuffer — se aplica el comportamiento de la caché de CPU. Los patrones de acceso contiguos (row-major para datos row-major) son dramáticamente más rápidos que el acceso con saltos. Mantén la alineación natural (4 bytes para i32) para que los loads/stores encajen en instrucciones únicas.
// Cache-friendly access: linear, contiguous iteration
// GOOD: row-major traversal of a 2D array
for (i32 row = 0; row < rows; row++) {
for (i32 col = 0; col < cols; col++) {
sum += data[row * cols + col];
}
}
// BAD: column-major traversal (cache misses)
for (i32 col = 0; col < cols; col++) {
for (i32 row = 0; row < rows; row++) {
sum += data[row * cols + col];
}
}
// Prefer aligned access (4-byte for i32, 8 for i64).
// Allocators should respect natural alignment.Minimizar cruces de la frontera con JS
Cada llamada JS→Wasm tiene sobrecarga (empaquetado de argumentos, preparación de pila). Para bucles ajustados, mueve el bucle DENTRO de Wasm y llámalo una vez con un buffer. Este es el mayor consejo de rendimiento de Wasm — las operaciones en bloque superan por órdenes de magnitud a las llamadas por elemento.
// BAD: call Wasm per element (boundary overhead)
for (let i = 0; i < arr.length; i++) {
result[i] = exports.process(arr[i]);
}
// GOOD: batch — one call for the whole array
const ptr = exports.alloc(arr.length * 4);
new Float32Array(memory.buffer, ptr, arr.length).set(arr);
exports.processBatch(ptr, arr.length); // single call
const out = Array.from(new Float32Array(memory.buffer, ptr, arr.length));
exports.free(ptr, arr.length * 4);
// Each crossing costs ~tens of nanoseconds.
// Batch loops to amortize the overhead.SIMD (una instrucción, múltiples datos)
SIMD (v128) procesa 4 floats o 4 int32 por instrucción — aceleraciones de 4x para matemáticas de imagen/audio/matrices. Emscripten lo activa con -msimd128; Rust usa intrínsecos de std::arch::wasm32. La auto-vectorización puede ayudar, pero los intrínsecos explícitos dan victorias predecibles. Ampliamente soportado en navegadores.
// C/C++ with Emscripten auto-vectorization
#include <emscripten/simd.h>
void addArrays(float *a, float *b, float *out, int n) {
for (int i = 0; i < n; i += 4) {
v128_t va = wasm_v128_load(a + i);
v128_t vb = wasm_v128_load(b + i);
wasm_v128_store(out + i, wasm_f32x4_add(va, vb));
}
}
# Compile with SIMD enabled
emcc simd.c -O3 -msimd128 -o simd.wasm
// Rust: use std::arch::wasm32 intrinsics
use std::arch::wasm32::*;
unsafe { let v = f32x4_splat(1.0); }Threads y SharedArrayBuffer
Los threads de Wasm comparten una Memory entre Web Workers, usando atómicos para sincronizar. Requiere cabeceras COOP/COEP (aislamiento cross-origin). El -pthread de Emscripten emula pthreads; el std::thread de Rust funciona en wasm32-wasi-threads. Genial para trabajo paralelo intensivo de CPU — procesamiento de imagen, códecs, inferencia de ML.
// Enable threads in Emscripten
# emcc app.c -O3 -pthread -s PTHREAD_POOL_SIZE=4 -o app.js
// Browser requires cross-origin isolation:
// /_headers (Cloudflare/Netlify)
// Cross-Origin-Opener-Policy: same-origin
// Cross-Origin-Embedder-Policy: require-corp
// Spawn workers sharing Wasm memory:
const memory = new WebAssembly.Memory({
initial: 10, maximum: 100, shared: true
});
// Each Worker instantiates the module with this memory
// and uses Atomics for synchronization.Profiling y benchmarks
Perfila con performance.now() y la pestaña Performance de DevTools — Wasm aparece en los flame charts como JS. Calienta antes de medir (la sobrecarga de compilación es de una sola vez). Compara con JS optimizado — el V8 moderno es rápido; Wasm gana en rendimiento predecible, kernels numéricos y cargas grandes, no en microtareas.
// Use performance.now() for high-res timing
const t0 = performance.now();
exports.heavyWork(ptr, len);
const t1 = performance.now();
console.log(`Wasm: ${(t1 - t0).toFixed(2)}ms`);
// Compare against JS equivalent
const t2 = performance.now();
jsEquivalent(data);
console.log(`JS: ${(performance.now() - t2).toFixed(2)}ms`);
// Chrome DevTools Performance tab: profile Wasm
// like JS — flame charts show function time.
// Avoid microbenchmarks pitfalls:
// - warm up first (JIT compilation)
// - run many iterations
// - compare against OPTIMIZED JS, not naive JSWasm vs JavaScript
Comparación de rendimiento
Wasm brilla en el trabajo numérico intensivo de cómputo (procesamiento de imagen, códecs, criptografía, ML) — típicamente 2-10x más rápido que JS. Para DOM, JSON o trabajo con muchos strings, JS suele ser más rápido porque el trabajo ya está en código nativo (el JSON.parse de V8, el DOM del navegador). Perfila para decidir — nunca asumas que Wasm siempre es más rápido.
// Wasm vs JS — typical scenarios:
//
// Image processing (8MB):
// JS: 120 ms
// Wasm (-O3): 35 ms ~3.4x faster
//
// SHA-256 (1MB):
// JS: 45 ms
// Wasm: 8 ms ~5.6x faster
//
// DOM manipulation:
// JS: 5 ms
// Wasm: 20 ms SLOWER (DOM is JS-native)
//
// JSON parse:
// JS: 3 ms
// Wasm: 15 ms SLOWER (JSON.parse is C++ in V8)
//
// Rule of thumb: Wasm wins on compute-heavy numeric
// workloads; JS wins on DOM/JSON/string-heavy tasks.Casos de uso de Wasm
Wasm destaca en: portar bases de código C/C++/Rust existentes (Figma, Photoshop web), kernels numéricos intensivos de cómputo (imagen/ML/criptografía) y plugins aislados. Victorias reales: Figma (renderizador), Photoshop (port de la app completa) y Google Meet (desenfoque de fondo). Para apps de DOM puro, JS suele ser la elección correcta.
// Strong Wasm use cases:
// - Image/video/audio processing (FFmpeg, OpenCV)
// - Games & 3D engines (Unity, Unreal)
// - Cryptography (hashing, encryption, ZK proofs)
// - Machine learning inference (ONNX, TFLite)
// - Codecs (AV1, VP9, MP3)
// - Emulators (DOSBox, retro consoles)
// - Heavy math (physics simulations, linear algebra)
// - Reusing C/C++/Rust libraries (FFI alternative)
// - Sandboxed plugins in editors (Figma, Photoshop)
// Figma: rendering engine in Wasm
// Photoshop: web port of full desktop app
// Google Meet: video background blurCuándo usar JS
JS sigue siendo la elección correcta para UI, DOM, APIs del navegador y la mayoría de lógica de apps web — V8 está fuertemente optimizado. Recurre a Wasm cuando el profiling revele un hotspot que JS no pueda eliminar, o al portar una base de código nativa existente. Un enfoque híbrido (UI en JS + hotspots en Wasm) suele ser lo ideal.
// JS is better when:
// - DOM manipulation dominates
// - Working with browser APIs (fetch, IndexedDB, WebRTC)
// - Heavy string/JSON processing
// - Small utilities and glue code
// - Rapid prototyping (no compile step)
// - Team lacks C/Rust expertise
// - Module size matters more than runtime speed
// JS engines (V8, SpiderMonkey, JSC) are highly
// optimized. For most web apps, JS is fast enough
// AND simpler to ship and maintain.
// Hybrid: keep UI in JS, offload hotspots to Wasm.Carga y coste de arranque
Wasm tiene un coste de arranque fijo (descarga + compilación + instanciación) que JS evita. Mitígalo con compilación en streaming, cacheando módulos compilados vía la Cache API y con carga perezosa del Wasm no crítico. Tras el calentamiento, las llamadas a funciones Wasm son tan rápidas como las de JS — el coste es inicial y lo reembolsa una ejecución más rápida.
// Wasm has upfront costs JS doesn't:
// 1. Download the .wasm binary
// 2. Compile to machine code (~10-50 ms for small modules)
// 3. Instantiate (initialize memory, run start function)
// Mitigations:
// - Cache compiled modules (WebAssembly.compileStreaming + Cache API)
// - Stream compilation (instantiateStreaming)
// - Lazy-load non-critical Wasm on demand
// - Use Web Workers to compile off the main thread
// Streaming compile of a 1MB module:
// ~30 ms download + ~10 ms compile (parallel)
// Cached: ~5 ms (re-instantiate from cached module)Coste de interoperabilidad y sobrecarga de la frontera
Las llamadas JS↔Wasm son baratas pero no gratuitas (~10-100ns cada una, más con strings). Para eventos de alta frecuencia, agrupa en JS y llama a Wasm una vez con un buffer. Evita pasar objetos de JS por llamada — usa externref o copia bytes a memoria. La frontera es rápida para números, lenta para datos serializados.
// Each JS<->Wasm call costs ~10-100 ns:
// - Marshal arguments (i32/f64 fast; strings/objects slow)
// - Stack frame setup
// - Inlined trampoline in the engine
// Implications:
// - Don't call Wasm 1M times for tiny work — batch!
// - Don't pass large objects per-call — copy once, share memory
// - For DOM events, keep handlers in JS, call Wasm with batched data
// Pseudocode: batched event handling
let pendingEvents = [];
button.addEventListener('click', e => {
pendingEvents.push(...);
if (pendingEvents.length >= 100) {
exports.processBatch(ptr, pendingEvents.length);
pendingEvents = [];
}
});Modelo de seguridad
Modelo de sandbox
La base de seguridad de Wasm es el sandbox: un módulo no puede acceder a la memoria, archivos, red ni dispositivos del host salvo que este le provea explícitamente funciones para ello vía imports. Esto hace seguro ejecutar código no confiable — solo puede hacer lo que sus imports permiten. Combinado con la seguridad de tipos, previene desbordamientos de buffer y RCE.
// Wasm executes in a sandboxed virtual machine:
// - No direct access to host memory (only its linear memory)
// - No syscalls (must go through imported functions)
// - No I/O unless the host provides it
// - Control flow is structured (no arbitrary jumps)
// - Type-checked at compile and run time
// All host access is EXPLICIT through imports.
// A module that didn't import "fs" cannot read files.
// Code:
// (module
// (import "env" "log" (func (param i32)))
// ;; the ONLY host capability this module has is log()
// )Política de mismo origen y fetch
Wasm no escapa del modelo de seguridad del navegador — la política de mismo origen y CORS se aplican a los fetch de .wasm igual que a cualquier recurso. El Wasm cross-origin exige cabeceras CORS adecuadas y el tipo MIME application/wasm. Wasm tampoco puede saltarse CSP, cookies ni ningún otro mecanismo de seguridad del navegador.
// Wasm modules obey the same-origin policy:
// - fetch('https://other-origin/x.wasm') needs CORS headers
// - The remote server must send:
// Access-Control-Allow-Origin: *
// - And the correct MIME: application/wasm
// Load cross-origin Wasm with streaming:
const { instance } = await WebAssembly.instantiateStreaming(
fetch('https://cdn.example.com/lib.wasm', {
mode: 'cors'
}),
imports
);
// Wasm cannot bypass CORS — it's subject to the
// browser's normal security model.Aislamiento de memoria
La memoria de Wasm se comprueba con límites en tiempo de ejecución — cualquier acceso fuera de rango provoca un trap inmediato en lugar de corromper memoria. Los módulos no pueden leer la memoria de otros, el heap de JS ni direcciones arbitrarias del host. Los punteros a función (call_indirect) se comprueban por tipo, previniendo la falsificación de destinos de llamada. Esto elimina clases enteras de vulnerabilidades de C/C++.
// Each Wasm instance has its OWN linear memory.
// - Out-of-bounds access traps (RuntimeError)
// - One module's memory cannot read another's
// - JS writes via TypedArray views are bounds-checked
// Even shared memory (threads) requires explicit
// opt-in and is still bounded:
const mem = new WebAssembly.Memory({ initial: 1, maximum: 10 });
// Wasm code CANNOT:
// - Read JS heap
// - Read other instances' memory
// - Forge function pointers (call_indirect type-checks)
// - Read arbitrary host memory addresses
// All memory access is bounds-checked at runtime.Seguridad basada en capacidades
Wasm sigue la seguridad basada en capacidades: el objeto de imports ES la capacidad del módulo. Eligiendo con cuidado qué importar, das al módulo el mínimo privilegio. Un plugin que solo importa log() no puede hacer nada más. Es la base de los sistemas de plugins seguros (Figma, Shopify functions, etc.).
// Capability security: a module can ONLY do what
// the host explicitly grants via imports.
// Strict imports = minimal privilege
const imports = {
env: {
log: msg => console.log('[wasm]', msg)
// NO file IO, NO network, NO timers
}
};
WebAssembly.instantiateStreaming(fetch('plugin.wasm'), imports);
// The plugin can ONLY call log(). It cannot:
// - Access the DOM
// - Make network requests
// - Read files
// - Spawn workers
// unless you import those capabilities.CSP y Trusted Types
Content Security Policy trata a Wasm como eval — por defecto, CSP lo bloquea. Añade 'wasm-unsafe-eval' a script-src para permitir Wasm manteniendo eval() bloqueado. Es más permisivo que unsafe-eval y recomendado para producción. La compatibilidad con Trusted Types exige envolver cualquier glue dinámico de JS en una policy.
// Content Security Policy applies to Wasm:
// - 'wasm-unsafe-eval' is required for instantiation
// - Without it, CSP blocks WebAssembly.compile
// HTTP header:
// Content-Security-Policy:
// default-src 'self';
// script-src 'self' 'wasm-unsafe-eval';
// Wasm output (e.g., Emscripten) often uses eval-like
// patterns for instantiation — CSP 'wasm-unsafe-eval'
// specifically allows Wasm while still blocking eval().
// Trusted Types: Wasm glue code must produce
// trusted scripts; use policy.createScript() for
// any dynamically generated JS that loads Wasm.Cadena de herramientas
WABT (wat2wasm, wasm2wat)
WABT es el toolkit canónico para trabajar con los formatos de texto y binario de Wasm. wat2wasm/wasm2wat van de ida y vuelta; wasm-objdump inspecciona la estructura; wasm-interp ejecuta módulos en un intérprete de referencia. wasm-decompile produce una forma legible tipo C. Esencial para escribir a mano, depurar y enseñar.
# WABT = WebAssembly Binary Toolkit
# Install:
# macOS: brew install wabt
# Ubuntu: apt install wabt
# Windows: scoop install wabt
# Tools included:
wat2wasm hello.wat -o hello.wasm # text -> binary
wasm2wat hello.wasm -o hello.wat # binary -> text
wasm-validate hello.wasm # validate
wasm-objdump -x hello.wasm # inspect structure
wasm-interp hello.wasm # interpret (run)
wasm-decompile hello.wasm -o hello.dly # decompile to C-like
# Online: https://webassembly.github.io/wabt/demo/Emscripten SDK
Emscripten es el toolchain de Wasm más maduro — compila C/C++, Fortran y otros lenguajes LLVM. emcc/em++ envuelven a Clang; emcmake/emconfigure permiten construir proyectos CMake/Autotools existentes sin modificar. También aporta puertos de libc, SDL, OpenGL (vía WebGL) y pthreads por compatibilidad.
# Emscripten: compile C/C++/LLVM languages to Wasm
git clone https://github.com/emscripten-core/emsdk.git
cd emsdk && ./emsdk install latest && ./emsdk activate latest
source ./emsdk_env.sh
# Key tools:
emcc # C/C++ compiler (gcc/clang-like)
em++ # C++ compiler
emcmake # wrapper for cmake
emconfigure # wrapper for ./configure
emranlib # archive tool
emar # archiver
# Common output:
emcc app.c -O3 -o app.js # JS glue + .wasm
emcc app.c -o app.html # runnable HTML demowasm-pack (Rust)
wasm-pack es la herramienta oficial de Rust→Wasm: compila, ejecuta wasm-bindgen, genera tipos de TypeScript y empaqueta para npm. --target elige el formato de módulo JS. wasm-pack test corre pruebas de Rust en navegadores reales vía webdriver. Usa wasm-pack-template para un andamiaje de proyecto listo.
# wasm-pack: build, test, publish Rust Wasm packages
cargo install wasm-pack
# Build for various targets
wasm-pack build --target web # modern browsers
wasm-pack build --target bundler # webpack/vite
wasm-pack build --target nodejs # Node.js
# Test in a headless browser
wasm-pack test --headless --chrome
# Publish to npm
wasm-pack publish
# Generate a template project
cargo generate --git https://github.com/rustwasm/wasm-pack-templateBinaryen (wasm-opt)
Binaryen es el toolkit de optimización que Emscripten y wasm-pack usan internamente. wasm-opt ejecuta pasadas a nivel Wasm (inlining, eliminación de código muerto, plegado de constantes) — ejecútalo siempre en los builds de producción. -O3 para velocidad, -Oz para tamaño mínimo. wasm-metadce elimina exportaciones sin usar entre módulos.
# Binaryen: Wasm optimization toolkit
# Often installed via Emscripten or standalone:
npm install -g binaryen
# wasm-opt: optimize .wasm files
wasm-opt -O3 input.wasm -o output.wasm # speed
wasm-opt -Os input.wasm -o output.wasm # size
wasm-opt -Oz input.wasm -o output.wasm # min size
# Other tools:
wasm-as input.wat -o output.wasm # assemble
wasm-dis input.wasm -o output.wat # disassemble
wasm-merge a.wasm b.wasm -o merged.wasm # link
wasm-shell input.wat # interpreter
wasm-metadce input.wasm -o output.wasm # aggressive dead-codewasm-tools (Bytecode Alliance)
wasm-tools es un toolkit moderno basado en Rust del Bytecode Alliance. Parsea/imprime/valida, pero su función estrella es el soporte del component model (component new/embed/describe). Es más estricto y rápido que WABT para muchas operaciones y es la herramienta recomendada para trabajo con el component model.
# wasm-tools: modern Rust-based Wasm toolkit
cargo install wasm-tools
# Subcommands:
wasm-tools parse input.wat -o output.wasm # text -> binary
wasm-tools print input.wasm -o output.wat # binary -> text
wasm-tools validate input.wasm # validate
wasm-tools component new input.wasm -o c.wasm # wrap as component
wasm-tools strip input.wasm -o stripped.wasm # remove debug info
wasm-tools objdump input.wasm # inspect
wasm-tools smith # generate random modules (fuzzing)
# Component model support is a key feature.
# Stronger WAT parsing than WABT in edge cases.Runtimes (wasmtime, wasmer, WasmEdge)
Tres runtimes independientes principales: wasmtime (referencia del Bytecode Alliance, mejor soporte del component model), wasmer (varios backends incluido LLVM para máximo rendimiento, bindings de JS), WasmEdge (CNCF, optimizado para cloud-native e inferencia de IA). Cada uno implementa WASI, así que el mismo .wasm corre entre ellos. Elige según el ecosistema que te convenga.
# wasmtime — Bytecode Alliance reference runtime
curl https://wasmtime.dev/install.sh -sSf | bash
wasmtime app.wasm
# wasmer — cross-platform, multiple backends
curl https://get.wasmer.io -sSf | sh
wasmer run app.wasm
# WasmEdge — CNCF, optimized for cloud/edge
curl -sSf https://raw.githubusercontent.com/WasmEdge/WasmEdge/master/utils/install.sh | bash
wasmedge app.wasm
# Comparison:
# wasmtime: reference, WASI preview1+2, components
# wasmer: multiple backends (Cranelift, LLVM), JS API
# WasmEdge: AI/ML extensions, Kubernetes-friendly
// All three run WASI modules portably.Componentes y buenas prácticas
Panorama de componentes Wasm
El Component Model es la evolución de Wasm: un formato de módulo que permite a los componentes comunicarse con tipos ricos (strings, records, listas) sin empaquetado manual a través de la memoria lineal. Los componentes se componen como librerías entre lenguajes (componente Rust + componente JS). Soportado por wasmtime, WasmEdge y el ecosistema del Bytecode Alliance.
// Component Model: a higher-level module format
// that lets Wasm modules talk to each other and hosts
// using rich types (strings, records, variants),
// not just (i32, f64).
// Core Wasm module: exports raw functions over memory.
// Component: wraps a core module, exposes typed
// interfaces described in WIT (Wasm Interface Type).
// Build flow:
// 1. Write WIT interface
// 2. Generate bindings for your language (Rust, C, JS)
// 3. Implement, compile to core .wasm
// 4. Wrap into a component with wasm-tools
// Tooling:
wasm-tools component new app.wasm -o app.wasm
// Run with wasmtime:
wasmtime app.wasm # uses component interfacesWIT (Wasm Interface Type)
WIT (Wasm Interface Type) es el IDL de los componentes — declara records, variants, enums, resources y funciones. wit-bindgen genera bindings específicos por lenguaje (Rust, C, JS, Python). La palabra clave 'world' agrupa los imports y exports que un componente provee/consume. Es la base de las librerías Wasm portables y agnósticas al lenguaje.
// example.wit — describe a component's interface
package example:greeter;
interface api {
// A record type
record person {
name: string,
age: u32,
}
// A function taking/returning rich types
greet: func(p: person) -> string;
}
world greeter-world {
export api;
}
# Generate bindings:
# Rust: cargo component bindings
# JS: jco transpile
# C/C++: wit-bindgen c component.wit
# wit-bindgen is the binding generator
cargo install wit-bindgen-cliBuena práctica: módulos pequeños y enfocados
Prefiere varios módulos Wasm pequeños y enfocados a un monolito. Los módulos menores se descargan más rápido, cachean mejor y pueden cargarse con pereza (carga el módulo de audio solo cuando haga falta). Comparte memoria entre módulos vía imports, o usa el component model para llamadas entre módulos con seguridad de tipos. Ejecuta wasm-opt -Oz en cada uno.
// GOOD: One focused .wasm per concern
// - renderer.wasm (drawing)
// - audio.wasm (mixing)
// - physics.wasm (simulation)
// Loaded lazily as needed.
// BAD: One giant monolithic .wasm
// - app.wasm (1MB+, includes everything)
// Benefits of small modules:
// - Faster initial load (only what's needed)
// - Better caching (changed modules re-download)
// - Easier parallel development
// - Smaller attack surface per module
// Use wasm-opt -Oz to minimize each module.
// Share memory across modules via imports.Buena práctica: manejo de errores
Los traps de Wasm (división por cero, memoria fuera de rango, unreachable) no pueden capturarse desde dentro de Wasm — abortan la función. Diseña las funciones exportadas para devolver códigos de error o tipos Result en lugar de trapear. Captura WebAssembly.RuntimeError del lado JS como último recurso. El component model soporta variantes de error tipadas de forma nativa.
// Wasm traps are unrecoverable — handle errors gracefully.
// BAD: let divide crash
(func (export "div") (param i32 i32) (result i32)
local.get 0 local.get 1 i32.div_s ;; traps on 0
)
// GOOD: return a sentinel or error code
(func (export "div") (param i32 i32) (result i32)
local.get 1
i32.eqz
if (result i32)
i32.const -1 ;; error sentinel
else
local.get 0
local.get 1
i32.div_s
end
)
// In Rust/AS: use Result<T, E> and export
// error variants via the component model.Buena práctica: gestión de memoria
Trata la memoria de Wasm como en C: cada alloc necesita su free correspondiente. Exporta helpers alloc/free y envuelve el uso de buffers del lado JS en try/finally. Recrea las vistas TypedArray tras cualquier memory.grow (el ArrayBuffer se desacopla). Documenta la propiedad: ¿quién es responsable de liberar — el llamador o el llamado? Las fugas degradan el rendimiento con el tiempo.
// Export alloc/free and use them consistently.
// C/C++ (Emscripten): _malloc / _free
// Rust: wasm_bindgen's __alloc / __free
// AssemblyScript: __new / __retain / __release
// JS wrapper for safe buffer passing:
function withBuffer(size, fn) {
const ptr = exports.alloc(size);
try {
return fn(new Uint8Array(memory.buffer, ptr, size));
} finally {
exports.free(ptr, size);
}
}
// NEVER leak:
// - Re-create TypedArray views after memory.grow
// - Free buffers passed in from JS
// - For long-lived allocations, document ownershipBuena práctica: pruebas y CI
Prueba Wasm en entornos reales: wasm-pack test corre pruebas de Rust en navegadores headless; AssemblyScript y Emscripten tienen sus propios runners. Añade wasm-validate y comprobaciones de tamaño al CI. Usa -s ASSERTIONS=1 (Emscripten) y builds de depuración para atrapar problemas pronto. Lintea con wat2wasm y ejecuta siempre wasm-opt sobre los artefactos de release.
# Test Wasm just like any other code.
# Rust: wasm-pack test runs in a real browser
wasm-pack test --headless --chrome --firefox
# AssemblyScript: use the built-in test framework
npm run test
# C/C++ (Emscripten): use emcc with -s ASSERTIONS=1
# and write tests in C, run with node:
node tests.js
# Validate .wasm in CI:
wasm-validate module.wasm
# Check size budgets:
ls -la module.wasm # e.g., must be < 200KB
# Lint WAT with wat2wasm (catches syntax errors)
# Run wasm-opt -O3 to ensure optimization is applied
# GitHub Actions example:
# - uses: actions-rs/toolchain@v1
# - run: cargo install wasm-pack
# - run: wasm-pack test --headlessFragmentos de WebAssembly relacionados
Copy-paste ready code for common tasks.
Module Instantiation
Compile and instantiate a .wasm module.
Linear Memory
Shared, growable byte buffer.
Tables
Function references for indirect calls.
Imports and Exports
Exchange functions, memory, and globals.
JS Interop
Pass strings through shared memory.
Text Format (WAT)
Human-readable WebAssembly.
Performance
Benchmark and parallelize WASM workloads.
Debugging
Inspect modules and handle traps.
Was this helpful?