Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
CharStreams
✓ import { CharStreams } from 'antlr4';
✗ import { ANTLRInputStream } from 'antlr4'; // ANTLRInputStream is deprecated
`CharStreams.fromString()` is the recommended way to create an input stream from a string since ANTLR 4.9. The older `ANTLRInputStream` is still available but deprecated.
CommonTokenStream
✓ import { CommonTokenStream } from 'antlr4';
✗ const CommonTokenStream = require('antlr4').CommonTokenStream;
The library supports both ES Modules and CommonJS. Use named imports for ESM. CJS users should access exports directly from the main `antlr4` module.
ParserRuleContext
✓ import { ParserRuleContext } from 'antlr4';
Base class for all generated parser rule contexts. Essential for working with parse trees.
error.ErrorListener
✓ import { error } from 'antlr4';
const { ErrorListener } = error;
Error handling components are nested under the `error` namespace.
This quickstart demonstrates the core pipeline of using the ANTLR 4 JavaScript runtime to parse a simple input string. It shows how to initialize `CharStreams`, `CommonTokenStream`, and use placeholder lexer and parser classes (which would be generated by the ANTLR tool from your grammar), including custom error handling.
import { CharStreams, CommonTokenStream, error } from 'antlr4';
// IMPORTANT: MyLexer and MyParser are GENERATED by the ANTLR tool from your grammar.
// For example, if you have 'Hello.g4', run 'antlr4 -Dlanguage=JavaScript Hello.g4'
// This will create 'HelloLexer.js', 'HelloParser.js', etc. in your output directory.
// Replace './MyLexer' and './MyParser' with the correct paths to your generated files.
// A minimal mock for demonstration. In a real app, these would be generated.
class MyLexer extends error.DefaultErrorListener {
constructor(input) { super(input); this.tokenFactory = null; this.charPositionInLine = 0; this.line = 1; }
nextToken() { return null; /* Real lexer logic */ }
getAllTokens() { return [{ type: 1, text: 'hello' }, { type: 2, text: 'world' }]; }
}
class MyParser extends error.DefaultErrorListener {
constructor(tokens) { super(tokens); this.ruleNames = ['start']; this.errorHandler = null; this.tokenStream = tokens; }
start() { return { text: 'parsed hello world' }; /* Real parser logic */ }
}
class CustomErrorListener extends error.ErrorListener {
syntaxError(recognizer, offendingSymbol, line, charPositionInLine, msg, e) {
console.error(`Line ${line}, column ${charPositionInLine}: ${msg}`);
}
}
// 1. Create an input stream from your source code
const input = CharStreams.fromString('hello world');
// 2. Create a lexer (tokenizer) from the input stream
// (Replace MyLexer with your generated lexer, e.g., 'HelloLexer')
const lexer = new MyLexer(input);
lexer.removeErrorListeners(); // Remove default console error listener
lexer.addErrorListener(new CustomErrorListener());
// 3. Create a token stream from the lexer
const tokens = new CommonTokenStream(lexer);
// 4. Create a parser from the token stream
// (Replace MyParser with your generated parser, e.g., 'HelloParser')
const parser = new MyParser(tokens);
parser.removeErrorListeners(); // Remove default console error listener
parser.addErrorListener(new CustomErrorListener());
// 5. Invoke the parser's entry rule (e.g., 'start')
const tree = parser.start();
console.log('Successfully attempted to parse:', input.getText());
// In a real scenario, 'tree' would be a parse tree object
// console.log('Parse tree:', tree.toStringTree(parser.ruleNames));
Debug
Known issues
breakingANTLR's versioning does not strictly follow npm semantic versioning, prioritizing consistency across its 10 target languages. This means minor version updates (e.g., 4.x.0 to 4.y.0) can introduce breaking changes. Developers are strongly advised to remove the `^` or `~` from `antlr4` entries in `package.json` to pin specific versions (e.g., `"antlr4": "4.13.2"`) and manually update.fixUpdate your `package.json` to pin the exact version of `antlr4` you are using (e.g., `"antlr4": "4.13.2"`) to prevent unexpected breaking changes with `npm install`.
affects: >=4.0.0
breakingStarting with ANTLR 4.10.0, lexers and parsers generated by the ANTLR tool are often incompatible with code generated by previous versions of the tool. While the JavaScript runtime specifically noted 'except probably javascript' for 4.10.0, this general rule applies across targets. If you upgrade the `antlr4` runtime, you should also regenerate all your grammar-based lexer and parser code using the ANTLR tool (e.g., the `antlr4` JAR) of the *same major version* as the runtime to ensure compatibility.fixAfter updating the `antlr4` npm package, regenerate your lexer and parser JavaScript files using the ANTLR tool (e.g., `java -jar antlr-4.13.2-complete.jar -Dlanguage=JavaScript MyGrammar.g4`) matching the new runtime version.
affects: >=4.10.0
breakingThe `antlr4` package requires Node.js version 16 or newer. Using it with older Node.js versions will result in runtime errors or failures during installation.fixEnsure your Node.js environment is updated to version 16 or higher. You can use `nvm` or your system's package manager to upgrade Node.js.
affects: <4.0.0 (exact version depends on previous updates but >=16 is current)
deprecatedThe `ANTLRInputStream` class, used for creating input streams, has been deprecated in favor of `CharStreams.fromString()` (or other `CharStreams` methods for files/buffers). While still functional, using `ANTLRInputStream` directly is discouraged.fixReplace `new ANTLRInputStream(inputString)` with `CharStreams.fromString(inputString)`.
affects: >=4.9.0
Errors
Common errors & fixes
Error: The '`MyLexer`' class extends '`Lexer`' but is missing the following properties from type '`Lexer`': `tokenFactory`
This error typically occurs in TypeScript projects when the generated lexer/parser files (e.g., `MyLexer.js` or `MyLexer.ts`) are out of sync with the `antlr4` runtime library's type definitions. This happens after upgrading the `antlr4` package without regenerating the grammar files.
fixRegenerate your lexer and parser JavaScript/TypeScript files using the ANTLR tool that matches the version of your `antlr4` npm package. For example, if you updated to `antlr4@4.13.2`, use `antlr-4.13.2-complete.jar` to generate your grammar files.
TypeError: Cannot read properties of undefined (reading 'CommonTokenStream')
This usually indicates an incorrect CommonJS `require` call where the named export is not directly accessible or a missing dependency.
fixFor CommonJS, use `const { CommonTokenStream } = require('antlr4');` or `const antlr4 = require('antlr4'); const CommonTokenStream = antlr4.CommonTokenStream;`. Ensure `antlr4` is installed. Error [ERR_REQUIRE_ESM]: require() of ES Module ... not supported. Instead change the require of ... to a dynamic import()
This error occurs in a CommonJS context when a module, explicitly marked as ESM-only, is attempted to be `require()`-d. While `antlr4` supports both, specific deep imports or usage in older build tools might trigger this.
fixIf your project is CommonJS-based, ensure you are using `const { NamedExport } = require('antlr4');`. If this specific error persists for deep imports, consider refactoring the affected part of your code to use dynamic `import()` or switch your project to ES Modules. Audit
Dependencies
No dependency data recorded yet.