Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?


Failed to load latest commit information.
Latest commit message
Commit time

antlr4ts - TypeScript/JavaScript target for ANTLR 4

Join the chat at

Build status



  • Releases: See the GitHub Releases page for release notes and links to the distribution
  • Feedback: Use GitHub Issues for issues (bugs, enhancements, features, and questions)


This project has separate requirements for developers and end users.

💡 The requirements listed on this page only cover user scenarios - that is, scenarios where developers wish to use ANTLR 4 for parsing tasks inside of a TypeScript application. If you are interested in contributing to ANTLR 4 itself, see for contributor documentation.

End user requirements

Parsers generated by the ANTLR 4 TypeScript target have a runtime dependency on the antlr4ts package. The package is tested and known to work with Node.js 6.7.

Development requirements

The tool used to generate TypeScript code from an ANTLR 4 grammar is written in Java. To fully utilize the ANTLR 4 TypeScript target (including the ability to regenerate code from a grammar file after changes are made), a Java Runtime Environment (JRE) needs to be installed on the developer machine. The generated code itself uses several features new to TypeScript 2.0.

  • Java Runtime Environment 1.6+ (1.8+ recommended)
  • TypeScript 2.0+

Getting started

  1. Install antlr4ts as a runtime dependency using your preferred package manager.
npm install antlr4ts --save
yarn add antlr4ts
  1. Install antlr4ts-cli as a development dependency using your preferred package manager.
npm install antlr4ts-cli --save-dev
yarn add -D antlr4ts-cli
  1. Add a grammar to your project, e.g. path/to/MyGrammar.g4

  2. Add a script to package.json for compiling your grammar to TypeScript

    "scripts": {
      // ...
      "antlr4ts": "antlr4ts -visitor path/to/MyGrammar.g4"
  3. Use your grammar in TypeScript

    import { ANTLRInputStream, CommonTokenStream } from 'antlr4ts';
    // Create the lexer and parser
    let inputStream = new ANTLRInputStream("text");
    let lexer = new MyGrammarLexer(inputStream);
    let tokenStream = new CommonTokenStream(lexer);
    let parser = new MyGrammarParser(tokenStream);
    // Parse the input, where `compilationUnit` is whatever entry point you defined
    let tree = parser.compilationUnit();

    The two main ways to inspect the tree are by using a listener or a visitor, you can read about the differences between the two here.

    Listener Approach
    // ...
    import { MyGrammarParserListener } from './MyGrammarParserListener'
    import { FunctionDeclarationContext } from './MyGrammarParser'
    import { ParseTreeWalker } from 'antlr4ts/tree/ParseTreeWalker'
    class EnterFunctionListener implements MyGrammarParserListener {
      // Assuming a parser rule with name: `functionDeclaration`
      enterFunctionDeclaration(context: FunctionDeclarationContext) {
        console.log(`Function start line number ${context._start.line}`)
        // ...
      // other enterX functions...
    // Create the listener
    const listener: MyGrammarParserListener = new EnterFunctionListener();
    // Use the entry point for listeners
    ParseTreeWalker.DEFAULT.walk(listener, tree)
    Visitor Approach

    Note you must pass the -visitor flag to antlr4ts to get the generated visitor file.

    // ...
    import { MyGrammarParserVisitor } from './MyGrammarParserVisitor'
    import { AbstractParseTreeVisitor } from 'antlr4ts/tree/AbstractParseTreeVisitor'
    // Extend the AbstractParseTreeVisitor to get default visitor behaviour
    class CountFunctionsVisitor extends AbstractParseTreeVisitor<number> implements MyGrammarParserVisitor<number> {
      defaultResult() {
        return 0
      aggregateResult(aggregate: number, nextResult: number) {
        return aggregate + nextResult
      visitFunctionDeclaration(context: FunctionDeclarationContext): number {
        return 1 + super.visitChildren(context)
    // Create the visitor
    const countFunctionsVisitor = new CountFunctionsVisitor()
    // Use the visitor entry point