acorn-typescript

acorn-typescript is a plugin for Acorn, the small and fast JavaScript parser, that teaches it to understand TypeScript. Rather than shipping a separate standalone parser, it hooks into Acorn’s Parser.extend() mixin mechanism to layer TypeScript-specific grammar — type annotations, interfaces, enums, type aliases, generics, decorators, and ambient declare contexts — directly on top of Acorn’s existing ECMAScript parsing pipeline.

This makes it useful for any tool already built on Acorn (bundlers, linters, codemods, static analyzers) that wants TypeScript support without switching to a heavier parser like the full TypeScript compiler or Babel. It also ships a JSX extension so .tsx files parse in the same pass, a dedicated decorators module for class/method/property decorators, an import-assertions extension, and a dts mode for correctly parsing .d.ts declaration files. The project validates its grammar coverage against the official test262 conformance suite in CI alongside its own Jest snapshot tests.

What You Get

• A drop-in Acorn plugin usable via acorn.Parser.extend(tsPlugin())
• Parsing support for core TypeScript syntax: types, interfaces, enums, type aliases, generics, and satisfies
• A decorators extension covering class, method, and property decorators
• A JSX/TSX extension (including XHTML entity handling) for parsing React-style TypeScript files
• A dts mode for parsing ambient declaration files and declare module blocks
• An import-assertions extension for parsing import assertion syntax

Common Use Cases

• Adding TypeScript support to an existing Acorn-based bundler, linter, or codemod tool without switching parsers
• Building lightweight TypeScript/TSX tooling that needs an ESTree-compatible AST without the overhead of the full TypeScript compiler
• Parsing .d.ts declaration files via the dts option for tooling that inspects ambient type declarations
• Validating custom syntax extensions against the test262 conformance suite when contributing new TypeScript grammar support

Under The Hood

Architecture The plugin follows Acorn’s mixin-extension pattern: src/index.ts (a single ~5,500-line module) returns a class-extension function that patches Acorn’s Parser prototype with TypeScript-aware overrides of statement, expression, and class-member parsing methods, coordinating with middleware.ts (which declares the shape of the extended AcornParseClass), scopeflags.ts and tokenType.ts (TS-specific scope and token bookkeeping), and parseutil.ts/whitespace.ts for shared parsing helpers. Feature-specific grammar — decorators (extentions/decorators.ts), JSX/TSX (extentions/jsx/), and import assertions (extentions/import-assertions.ts) — is isolated into separate generator functions that are composed into the main plugin, keeping cross-cutting extensions decoupled from the core override even though the core file itself is large and monolithic.

Tech Stack Written in TypeScript and built with microbundle to emit both ESM and CJS bundles plus type declarations, targeting acorn as a peer dependency (>=8.9.0) rather than a bundled fork. The project has no runtime dependencies beyond that peer requirement. Tests run under Jest with ts-jest, and test262-parser-runner drives the official ECMAScript/TypeScript test262 suite via a dedicated ts-node script; standard-version manages release tagging.

Code Quality Test coverage is extensive and organized by feature — dozens of subdirectories under __test__/ (decorators, enum, export, jsx, satisfies, static, try, arrow-function, class, and more) using snapshot-based assertions, backed by conformance testing against test262 in CI with coverage reported to Codecov. Error messages are centralized in error.ts as named, parameterized message generators rather than inline strings, which aids consistency. That said, no ESLint or Prettier configuration is present in the repo, and internal types lean heavily on any in the parser’s extended-class declarations, trading some type safety for flexibility in patching Acorn’s internals.

What Makes It Unique Rather than building or maintaining a fully independent TypeScript parser, acorn-typescript extends an existing, widely-used general-purpose JavaScript parser in place — letting any Acorn-based toolchain gain TypeScript and TSX support incrementally, and letting it validate that support against the same conformance suite the broader JS ecosystem uses to certify parsers.