{"id":25823,"library":"kaitai-struct-compiler","title":"Kaitai Struct Compiler","description":"Kaitai Struct Compiler is a tool that generates parsers for binary data formats from a declarative YAML or JSON definition (KSY format). Current stable version is 0.11.0, released September 2025. It supports multiple target languages including C++, C#, Java, JavaScript, Python, Ruby, Rust, and Go. The compiler is part of the Kaitai Struct ecosystem, which provides a language-agnostic way to describe binary formats and then compile those descriptions into efficient, reusable parsers in various programming languages. Unlike hand-written parsers, Kaitai Struct ensures consistency across languages and reduces maintenance overhead. The compiler is distributed as a standalone JAR file, available via releases on GitHub.","status":"active","version":"0.11.0","language":"javascript","source_language":"en","source_url":"https://github.com/kaitai-io/kaitai_struct_compiler","tags":["javascript","kaitai","struct","compiler","binary","parsing","stream","runtime","file"],"install":[{"cmd":"npm install kaitai-struct-compiler","lang":"bash","label":"npm"},{"cmd":"yarn add kaitai-struct-compiler","lang":"bash","label":"yarn"},{"cmd":"pnpm add kaitai-struct-compiler","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The compiler is a command-line tool, not a library. It is installed globally via npm for convenience.","wrong":"npm install kaitai-struct-compiler --global","symbol":"KaitaiStructCompiler","correct":"npm install kaitai-struct-compiler"},{"note":"Use -t for target language, not --target. The short flag is -t.","wrong":"kaitai-struct-compiler --target=javascript myformat.ksy","symbol":"compile","correct":"kaitai-struct-compiler -t javascript myformat.ksy"},{"note":"KaitaiStream is a subclass exported from the npm package 'kaitai-struct' (the runtime library). The compiler generates code that uses this stream class.","wrong":"import { KaitaiStream } from 'kaitai-struct';","symbol":"BinaryParser","correct":"import KaitaiStream from 'kaitai-struct/KaitaiStream';"}],"quickstart":{"code":"// First, install the compiler globally\nnpm install kaitai-struct-compiler -g\n\n// Create a simple KSY file example.ksy\n// (YAML format describing a binary format)\nkaitai-struct-compiler -t javascript example.ksy\n\n// The compiler outputs example.js, which can be used with the runtime:\nnpm install kaitai-struct\n\n// In Node.js:\nconst KaitaiStream = require('kaitai-struct/KaitaiStream');\nconst Example = require('./example.js');\n\nconst buf = Buffer.from(...); // your binary data\nconst stream = new KaitaiStream(buf);\nconst parsed = new Example(stream);\nconsole.log(parsed);","lang":"javascript","description":"Demonstrates installing the compiler, compiling a KSY file to JavaScript, and using the generated parser with the kaitai-struct runtime."},"warnings":[{"fix":"Explicitly specify -t java if you previously relied on the default.","message":"v0.9 changed the default target language from Java to JavaScript.","severity":"breaking","affected_versions":">=0.9"},{"fix":"Use short flags (-t, -o) instead of long options.","message":"The --help flag outputs usage information; long-form options like --target are deprecated since v0.10.","severity":"deprecated","affected_versions":">=0.10"},{"fix":"Install JRE 8+ and ensure java is in PATH.","message":"Compiler requires Java Runtime Environment (JRE) 8 or later to run.","severity":"gotcha","affected_versions":"all"},{"fix":"Download the JAR directly from GitHub releases if offline.","message":"The npm package 'kaitai-struct-compiler' is a wrapper that downloads the JAR; it does not work offline.","severity":"gotcha","affected_versions":"all"},{"fix":"Use require('kaitai-struct/KaitaiStream') instead of require('kaitai-struct').","message":"In v0.10, the runtime package 'kaitai-struct' changed its import path for KaitaiStream.","severity":"breaking","affected_versions":">=0.10"},{"fix":"Remove the flag from your compilation commands.","message":"v0.11 removed support for the --ksc-exception flag (no longer needed).","severity":"breaking","affected_versions":">=0.11"}],"env_vars":null,"last_verified":"2026-05-01T00:00:00.000Z","next_check":"2026-07-30T00:00:00.000Z","problems":[{"fix":"Run 'npm install kaitai-struct' to install the runtime.","cause":"The runtime package 'kaitai-struct' is not installed or version mismatch.","error":"Error: Cannot find module 'kaitai-struct/KaitaiStream'"},{"fix":"Install JRE 8+ and ensure the kaitai-struct-compiler JAR is in the expected location.","cause":"Java is not installed or the JAR file is missing.","error":"Error: Could not find or load main class io.kaitai.struct.Main"},{"fix":"Add npm global bin directory to PATH or reinstall with -g.","cause":"The global npm installation path is not in PATH.","error":"kaitai-struct-compiler: command not found"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}