{"id":14468,"library":"blake3-wasm","title":"BLAKE3 Hashing (WebAssembly)","description":"The `blake3-wasm` package provides high-performance WebAssembly bindings for the BLAKE3 cryptographic hash function, enabling efficient hashing operations in JavaScript environments, including Node.js (>=16) and modern browsers. BLAKE3 is renowned for its speed, security, and parallel processing capabilities, making it a robust choice for various applications. This package specifically wraps the BLAKE3 WebAssembly module, offering a lean implementation focused solely on WASM performance rather than hybrid native bindings. The current stable version, 3.0.0, marks a significant shift to an ES Modules-only API and requires explicit asynchronous initialization. While the major version hasn't seen frequent updates since its release (October 2022), the underlying `connor4312/blake3` project, from which this package is derived, appears to be actively maintained, suggesting a stable, feature-complete API for `blake3-wasm`.","status":"active","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/connor4312/blake3","tags":["javascript","blake3","webassembly","wasm","hash","typescript"],"install":[{"cmd":"npm install blake3-wasm","lang":"bash","label":"npm"},{"cmd":"yarn add blake3-wasm","lang":"bash","label":"yarn"},{"cmd":"pnpm add blake3-wasm","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Since v3.0.0, this package is ESM-only. The `init()` function must be called and awaited once before any other BLAKE3 operations can be performed, ensuring the WebAssembly module is loaded.","wrong":"const { init, hash } = require('blake3-wasm');","symbol":"init","correct":"import { init, hash } from 'blake3-wasm';\nawait init();"},{"note":"The `hash` function performs a one-shot hash. It expects `Uint8Array` as input and returns a `Uint8Array`. Ensure `init()` has been awaited.","wrong":"const result = blake3.hash(data); // if blake3 imported as default","symbol":"hash","correct":"import { init, hash } from 'blake3-wasm';\n// ... after await init() ...\nconst data = new Uint8Array([1, 2, 3]);\nconst result = hash(data);"},{"note":"Use `createHasher()` for incremental hashing of large inputs. The returned hasher object exposes `update()` for adding data chunks and `digest()` to finalize the hash.","wrong":"const finalHash = createHasher(data).digest(); // missing update step for streaming","symbol":"createHasher","correct":"import { init, createHasher } from 'blake3-wasm';\n// ... after await init() ...\nconst hasher = createHasher();\nhasher.update(new TextEncoder().encode('hello'));\nhasher.update(new TextEncoder().encode('world'));\nconst finalHash = hasher.digest();"}],"quickstart":{"code":"import { init, hash, createHasher } from 'blake3-wasm';\n\nasync function runBlake3Example() {\n  console.log('Initializing BLAKE3 WebAssembly module...');\n  await init();\n  console.log('BLAKE3 module initialized.');\n\n  // --- One-shot hashing ---\n  const dataOneShot = new TextEncoder().encode('Hello, BLAKE3!');\n  const hashResult = hash(dataOneShot);\n  console.log('One-shot hash (Uint8Array):', hashResult);\n  console.log('One-shot hash (hex):', Array.from(hashResult).map(b => b.toString(16).padStart(2, '0')).join(''));\n\n  // --- Incremental hashing ---\n  const hasher = createHasher();\n  const chunk1 = new TextEncoder().encode('This is the first part');\n  const chunk2 = new TextEncoder().encode(' and this is the second part.');\n\n  hasher.update(chunk1);\n  hasher.update(chunk2);\n\n  const streamingHashResult = hasher.digest();\n  console.log('Streaming hash (Uint8Array):', streamingHashResult);\n  console.log('Streaming hash (hex):', Array.from(streamingHashResult).map(b => b.toString(16).padStart(2, '0')).join(''));\n\n  // Example with custom output length (e.g., 16 bytes)\n  const customLengthHash = hash(new TextEncoder().encode('Short hash example'), { length: 16 });\n  console.log('Custom length hash (16 bytes hex):', Array.from(customLengthHash).map(b => b.toString(16).padStart(2, '0')).join(''));\n}\n\nrunBlake3Example().catch(console.error);","lang":"typescript","description":"Demonstrates asynchronous initialization, one-shot hashing, and incremental hashing using `createHasher` for larger data streams, including custom output lengths."},"warnings":[{"fix":"Migrate your project to use ES Modules. For Node.js, ensure your `package.json` has `\"type\": \"module\"` or use `.mjs` file extension. Replace `require('blake3-wasm')` with `import { ... } from 'blake3-wasm'`.","message":"Version 3.0.0 completely drops CommonJS (require) support. It is now an ES Module (import) only package.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Always call and `await` the `init()` function once at the start of your application before attempting to use `hash` or `createHasher`. Example: `import { init, hash } from 'blake3-wasm'; await init();`","message":"Explicit asynchronous initialization via `await init()` is now mandatory before using any hashing functions.","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Ensure the `.wasm` file (if external) is correctly served with `application/wasm` MIME type and is accessible from your application's origin. Handle potential `init()` rejection gracefully with a `try...catch` block.","message":"WebAssembly module loading can fail due to network issues, incorrect paths, or improper MIME types when served in a browser environment.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For large inputs, instantiate a hasher with `createHasher()`, feed data in chunks using `hasher.update(chunk)`, and retrieve the final hash with `hasher.digest()`.","message":"The `hash` function is designed for convenience with smaller inputs. For very large files or data streams, `createHasher` offers better performance and memory efficiency.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure your project is configured for ES Modules. Add `\"type\": \"module\"` to your `package.json` or rename your file to `.mjs`. If using Node.js, upgrade to version 16 or newer.","cause":"Attempting to use ES `import` syntax in a CommonJS context (e.g., a `.js` file without `\"type\": \"module\"` in `package.json`, or a Node.js version prior to v16).","error":"SyntaxError: Cannot use import statement outside a module"},{"fix":"Make sure `await init()` is called once and completes successfully before any calls to `hash()` or `createHasher()`.","cause":"The WebAssembly module was not loaded or initialized by calling `await init()` before a hashing function was invoked.","error":"Error: BLAKE3 module not initialized. Call init() first."},{"fix":"Verify that `await init()` has completed and that you are using named imports: `import { init, hash } from 'blake3-wasm';`.","cause":"This can occur if `init()` was not `await`ed, or if the `blake3-wasm` module was imported incorrectly (e.g., trying to use a default import for named exports).","error":"TypeError: hash is not a function"},{"fix":"Check your server configuration to ensure `.wasm` files are served with the `Content-Type: application/wasm` header. Verify the `.wasm` file path is correct and accessible. If self-hosting, ensure proper CORS headers are set if loading from a different origin.","cause":"This browser-specific error usually indicates a network issue loading the `.wasm` file (e.g., CORS, incorrect path) or an invalid MIME type from the server.","error":"WebAssembly.instantiateStreaming failed"}],"ecosystem":"npm"}