flatc-wasm

26.1.32 verified Fri May 01 auth: no javascript

FlatBuffers compiler (flatc) compiled to WebAssembly, enabling schema management, JSON/binary conversion, and code generation in Node.js (18+) and modern browsers without native dependencies. Current stable version 26.1.32, released February 2025. Key differentiators: self-contained with inlined WASM binaries, zero native deps, supports 13 code generation languages (C++, TypeScript, Go, Rust, Python, Java, etc.), per-field AES-256-CTR encryption, streaming APIs for large data, JSON Schema import/export, and embedded language runtimes. Licensed under Apache 2.0. Maintained by DigitalArsenal on GitHub.

Common errors

error Error: WebAssembly.instantiate(): expected magic word 00 61 73 6d ↓

cause The WASM binary is corrupted or not fully loaded due to network issues in browser or incorrect bundler configuration.

fix

Ensure the WASM binary is served with the correct MIME type 'application/wasm' and loaded via fetch or import. In webpack, add a rule to load .wasm files as WebAssemblyModule.

error TypeError: Cannot read properties of undefined (reading 'addSchema') ↓

cause FlatcRunner.create() not awaited; runner object is undefined.

fix

Use const runner = await FlatcRunner.create();

error Error: Schema 'monster' not found ↓

cause Schema was not added before calling conversion or code generation functions.

fix

Call await runner.addSchema('monster', schemaContent) first.

error RangeError: offset is out of bounds ↓

cause ArrayBuffer passed to binaryToJson is too small or the binary format is malformed.

fix

Verify that the binary was generated by flatc or by jsonToBinary with the correct schema and root type.

Warnings

breaking WASM module initialization changed from synchronous to async in v26.0.0. FlatcRunner.create() must be awaited. ↓

fix Use await FlatcRunner.create() instead of new FlatcRunner().

deprecated The low-level API 'createFlatcModule' is deprecated in favor of 'FlatcRunner' since v25.12.0. ↓

fix Migrate to FlatcRunner API for easier usage and better error handling.

gotcha Binary output from jsonToBinary is an ArrayBuffer, not a Buffer. Use Buffer.from() before writing to file. ↓

fix const buffer = Buffer.from(await runner.jsonToBinary(...));

breaking Node.js minimum version raised to 18.0.0 in v25.0.0. Older versions are not supported. ↓

fix Upgrade Node.js to 18.0.0 or later.

gotcha Schema names are case-sensitive and must match the schema file name (without .fbs). Adding a schema with the wrong name will fail silently. ↓

fix Ensure schema name matches the file stem, e.g., 'monster' for 'monster.fbs'.

Install

npm install flatc-wasm

yarn add flatc-wasm

pnpm add flatc-wasm

Imports

FlatcRunner

wrong

const FlatcRunner = require('flatc-wasm').FlatcRunner

correct

import { FlatcRunner } from 'flatc-wasm'

ES module import; also works with dynamic import()

createFlatcModule

wrong

const createFlatcModule = require('flatc-wasm')

correct

import { createFlatcModule } from 'flatc-wasm'

Low-level module factory for manual WASM initialization

AlignedType
wrong
```
import { AlignedTypes } from 'flatc-wasm'
```
correct
```
import { AlignedType } from 'flatc-wasm'
```
Enum used for aligned binary format; type import also available: import type { AlignedType }

Quickstart

Demonstrates loading a FlatBuffers schema, converting between JSON and binary, and generating TypeScript code using FlatcRunner.

import { FlatcRunner } from 'flatc-wasm';
import { readFileSync, writeFileSync } from 'fs';

async function main() {
  // Create runner instance
  const runner = await FlatcRunner.create();
  
  // Load a FlatBuffers schema
  const schema = readFileSync('monster.fbs', 'utf8');
  await runner.addSchema('monster', schema);
  
  // Convert JSON to FlatBuffer binary
  const jsonData = JSON.stringify({ name: 'Orc', hp: 300 });
  const binary = await runner.jsonToBinary('monster', jsonData, 'MyGame.Sample.Monster');
  writeFileSync('monster.bin', Buffer.from(binary));
  
  // Convert binary back to JSON (auto-detects schema)
  const binaryBuf = readFileSync('monster.bin');
  const jsonOut = await runner.binaryToJson('monster', new Uint8Array(binaryBuf));
  console.log(jsonOut);
  
  // Generate TypeScript code
  const tsCode = await runner.generateCode('monster', 'typescript');
  writeFileSync('monster_generated.ts', tsCode);
}

main().catch(console.error);