Intégrer WebAssembly avec Claude Code, Rust, wasm-pack et Vite

Le bon rôle de Claude Code avec WebAssembly

WebAssembly, souvent abrégé en Wasm, est un format binaire portable qui permet d’exécuter du code Rust, C, C++ ou d’autres langages dans le navigateur et dans certains environnements serveur. Il ne faut pas le traiter comme un remplacement global de JavaScript. En pratique, Wasm sert surtout à accélérer une petite zone bien choisie : traitement d’image, compression, manipulation de bytes, calcul numérique, agrégation CSV ou réutilisation d’une bibliothèque Rust/C++ déjà éprouvée.

Claude Code devient utile parce qu’une intégration Wasm correcte traverse plusieurs fichiers. Il faut une fonction Rust, un build wasm-pack, le code de liaison généré par wasm-bindgen, un chargement asynchrone côté Vite, un wrapper TypeScript, un benchmark et une revue qui vérifie le coût de la frontière JS-Wasm. Cette frontière est le point où les données passent entre JavaScript et WebAssembly. Si elle est franchie trop souvent, le gain de calcul peut disparaître.

Dans cet article, nous construisons une base minimale mais réaliste : inverser un buffer RGBA, additionner une colonne numérique dans un CSV et calculer un checksum léger sur un tableau de bytes. Ces trois exemples couvrent l’image, le texte et le binaire. Le même modèle peut ensuite servir au traitement rapide dans le navigateur, à la migration d’un moteur Rust/C++, à la compression, aux codecs maison ou aux calculs locaux sur données sensibles. Pour la vision globale des performances, consultez aussi Claude Code performance optimization.

Gardez les références officielles à portée de main : MDN WebAssembly pour la plateforme, wasm-bindgen Guide pour le pont Rust-JavaScript et wasm-pack repository pour l’outil de build Rust vers Wasm. Demandez à Claude Code de respecter ces limites avant de générer une solution trop originale.

Choisir le cas d’usage avant le code

Wasm n’est pas automatiquement plus rapide. Il devient intéressant quand on lui transmet un bloc de travail assez grand, puis qu’on laisse le code compilé faire une passe complète. Il devient moins intéressant quand JavaScript appelle une petite fonction Wasm des milliers de fois. Le premier travail consiste donc à identifier le bon bloc de calcul et la façon de le mesurer.

Cas d’usage	Pourquoi Wasm convient	Ce que Claude Code doit vérifier
Traitement d’image	Les buffers RGBA se parcourent en boucles serrées	Copies mémoire, lecture Canvas et benchmark équitable
Crypto, compression, codecs	Les données binaires se prêtent bien à Rust	Besoin d’une bibliothèque auditée et limites du code maison
CSV et calcul numérique	Parsing et agrégation répètent beaucoup d’opérations	Lignes vides, NaN, gros fichiers et stratégie d’erreur
Portage Rust ou C++	La logique existante peut être réutilisée côté navigateur	APIs système, I/O fichier, threads et dépendances incompatibles
Traitement local navigateur	Les données sensibles restent sur l’appareil	Taille initiale, fallback et navigateurs cibles

Dans les essais de Masa, la bonne approche a été de convertir une seule fonction, puis de mesurer. En image, la fonction Rust pouvait être rapide, mais la lecture et l’écriture de ImageData dominaient parfois le résultat. En CSV, passer tout le texte une fois était plus fiable que d’appeler Wasm ligne par ligne. Ces contraintes doivent figurer dans le prompt donné à Claude Code.

Module Rust minimal avec wasm-pack

wasm-pack compile le crate Rust, lance wasm-bindgen et produit un dossier pkg contenant le binaire Wasm, le chargeur JavaScript, les métadonnées et les déclarations TypeScript. wasm-bindgen est la bibliothèque qui expose les fonctions Rust sélectionnées à JavaScript.

# Cargo.toml
[package]
name = "wasm-lab"
version = "0.1.0"
edition = "2021"

[lib]
crate-type = ["cdylib"]

[dependencies]
wasm-bindgen = "0.2"

// src/lib.rs
use wasm_bindgen::prelude::*;

#[wasm_bindgen]
pub fn invert_rgba(pixels: &mut [u8]) {
    for chunk in pixels.chunks_exact_mut(4) {
        chunk[0] = 255 - chunk[0];
        chunk[1] = 255 - chunk[1];
        chunk[2] = 255 - chunk[2];
    }
}

#[wasm_bindgen]
pub fn sum_csv_column(csv: &str, column: usize) -> f64 {
    csv.lines()
        .filter(|line| !line.trim().is_empty())
        .filter_map(|line| line.split(',').nth(column))
        .filter_map(|cell| cell.trim().parse::<f64>().ok())
        .sum()
}

#[wasm_bindgen]
pub fn fnv1a32(bytes: &[u8]) -> u32 {
    let mut hash = 0x811c9dc5u32;

    for byte in bytes {
        hash ^= u32::from(*byte);
        hash = hash.wrapping_mul(0x01000193);
    }

    hash
}

rustup target add wasm32-unknown-unknown
cargo install wasm-pack
wasm-pack build --target web --out-dir pkg

La fonction fnv1a32 n’est pas un hash cryptographique sûr. Pour les mots de passe, signatures, paiements ou jetons, utilisez Web Crypto API ou une bibliothèque auditée. Ici, elle sert seulement d’exemple court pour manipuler un tableau de bytes.

Chargement Vite et wrapper typé

Après le build, vous obtenez pkg/wasm_lab.js et pkg/wasm_lab.d.ts. Dans Vite, importez le module généré, attendez init(), puis exposez une petite API TypeScript. Cette couche évite que les composants UI appellent Wasm avant l’initialisation ou répètent le chargement à chaque interaction.

// src/wasm-client.ts
import init, {
  fnv1a32,
  invert_rgba,
  sum_csv_column,
} from "../pkg/wasm_lab";

export type WasmClient = {
  invertImage(imageData: ImageData): Promise<ImageData>;
  sumCsvColumn(csv: string, columnIndex: number): Promise<number>;
  checksum(bytes: Uint8Array): Promise<number>;
};

let initPromise: Promise<void> | undefined;

async function ensureWasm(): Promise<void> {
  initPromise ??= init().then(() => undefined);
  return initPromise;
}

export const wasmClient: WasmClient = {
  async invertImage(imageData) {
    await ensureWasm();

    const pixels = new Uint8Array(
      imageData.data.buffer,
      imageData.data.byteOffset,
      imageData.data.byteLength,
    );

    invert_rgba(pixels);
    return imageData;
  },

  async sumCsvColumn(csv, columnIndex) {
    await ensureWasm();
    return sum_csv_column(csv, columnIndex);
  },

  async checksum(bytes) {
    await ensureWasm();
    return fnv1a32(bytes);
  },
};

// src/main.ts
import { wasmClient } from "./wasm-client";

const fileInput = document.querySelector<HTMLInputElement>("#csv-file");
const output = document.querySelector<HTMLPreElement>("#output");

fileInput?.addEventListener("change", async () => {
  const file = fileInput.files?.[0];
  if (!file || !output) return;

  const csv = await file.text();
  const total = await wasmClient.sumCsvColumn(csv, 2);
  output.textContent = `column 2 total: ${total.toFixed(2)}`;
});

Avec wasm-pack --target web, commencez par la configuration Vite standard. Les plugins deviennent utiles si vous importez directement un fichier .wasm brut ou si votre bundling dépend du top-level await. Au début, les erreurs viennent surtout des chemins et de l’ordre d’initialisation.

Prompt de revue pour Claude Code

Claude Code doit produire le code, puis le revoir avec un prompt plus strict. La revue doit porter sur l’initialisation asynchrone, les copies, le DOM, les types, les benchmarks et les commandes réellement exécutables.

Review only these files:
- src/lib.rs
- pkg/wasm_lab.d.ts
- src/wasm-client.ts
- src/main.ts
- src/bench.ts

Goal:
Integrate the Rust WebAssembly module into the Vite app without changing UI behavior.

Check:
1. init() is awaited before any exported Wasm function is called.
2. init() is cached and not repeated for every click or file upload.
3. Large arrays cross the JS-Wasm boundary at most once per user action.
4. DOM updates stay in TypeScript, not inside Rust.
5. The wrapper exposes typed methods and keeps generated pkg files out of hand edits.
6. Benchmarks compare the same input data for JavaScript and Wasm.

Run:
wasm-pack build --target web --out-dir pkg
npm run typecheck
npm run build

Pour une équipe, placez ces règles dans CLAUDE.md. Vous éviterez les revues dépendantes de la mémoire d’une personne et chaque changement Wasm sera contrôlé de la même manière.

Benchmark et vérification

Ne validez pas une migration Wasm parce qu’elle semble plus rapide. Mesurez le même input et le même résultat. Le benchmark suivant compare une inversion RGBA en JavaScript et en Wasm.

// src/bench.ts
import { wasmClient } from "./wasm-client";

function invertJs(pixels: Uint8Array): void {
  for (let index = 0; index < pixels.length; index += 4) {
    pixels[index] = 255 - pixels[index];
    pixels[index + 1] = 255 - pixels[index + 1];
    pixels[index + 2] = 255 - pixels[index + 2];
  }
}

function cloneImageData(source: Uint8Array, width: number, height: number): ImageData {
  return new ImageData(new Uint8ClampedArray(source), width, height);
}

export async function runBench(): Promise<void> {
  const width = 1920;
  const height = 1080;
  const source = new Uint8Array(width * height * 4);
  crypto.getRandomValues(source);

  const jsPixels = new Uint8Array(source);
  const wasmImage = cloneImageData(source, width, height);

  const jsStart = performance.now();
  invertJs(jsPixels);
  const jsMs = performance.now() - jsStart;

  const wasmStart = performance.now();
  await wasmClient.invertImage(wasmImage);
  const wasmMs = performance.now() - wasmStart;

  console.table({
    javascriptMs: Number(jsMs.toFixed(2)),
    wasmMs: Number(wasmMs.toFixed(2)),
    ratio: Number((jsMs / wasmMs).toFixed(2)),
  });
}

wasm-pack build --target web --out-dir pkg
npm run typecheck
npm run build
npm run dev

Si le résultat déçoit, inspectez d’abord les conversions de données. Canvas, ImageData, les strings et le mode développement peuvent masquer le gain réel. Donnez la sortie à Claude Code et demandez s’il faut garder Wasm, déplacer le calcul dans un Web Worker ou optimiser JavaScript.

Pièges fréquents

Premier piège : l’initialisation est asynchrone. init() doit être résolu avant tout appel exporté. Cachez cette promesse dans le wrapper.

Deuxième piège : la taille du bundle. Chaque crate Rust peut augmenter le .wasm. Commencez avec une seule fonction et inspectez le build de production.

Troisième piège : le coût de frontière JS-Wasm. Évitez les appels minuscules en boucle ; passez des arrays, strings ou buffers plus gros.

Quatrième piège : vouloir manipuler le DOM depuis Wasm. Les événements, le rendu, l’accessibilité et les messages d’erreur restent côté TypeScript.

Cinquième piège : les copies mémoire invisibles. Typed arrays, strings et ImageData peuvent être copiés par les bindings. Le benchmark doit inclure cette conversion.

Sixième piège : compatibilité navigateur et en-têtes de sécurité. Wasm de base est largement supporté, mais Wasm threads et SharedArrayBuffer demandent COOP et COEP. Testez tôt si le site utilise publicité, iframes ou CDN.

Déploiement en équipe et CTA

Pour une expérimentation individuelle, ce code suffit. En équipe, il faut décider ce qui part en Rust, ce qui reste en TypeScript, comment gérer les fichiers générés dans pkg, quels navigateurs supporter et quel benchmark bloque une fusion. Ces règles doivent vivre dans CLAUDE.md.

ClaudeCodeLab peut vous aider à transformer ce guide en workflow sur votre dépôt : choix du bon cas d’usage Wasm, revue d’actifs Rust/C++, conception de benchmarks et formation de l’équipe aux prompts de revue. Si WebAssembly touche la performance de production, les données sensibles ou l’architecture frontend partagée, commencez par Claude Code training and consultation.

Note de vérification

Lors de l’essai, le point difficile n’était pas la fonction Rust, mais l’endroit où attendre init(). En centralisant l’initialisation dans wasm-client.ts, image, CSV et checksum ont suivi le même chemin. Sur de petits inputs, JavaScript restait suffisant ; sur des buffers Full HD et de gros CSV, le compromis devenait visible. Il faut donc mesurer toute la frontière, pas seulement le corps de la fonction.