Acorn TypeScript Parser Plugin

Common errors

• Error: The 'locations' option must be enabled for acorn-typescript.

  cause `locations: true` was not included in the parser options.
  fix Add `{ locations: true }` to the options object passed to the `parse` method.

• TypeError: Cannot read properties of undefined (reading 'extend')

  cause The `acorn` package might not be installed, or an incompatible version is present, preventing the `Parser.extend` method from being accessed correctly.
  fix Ensure `acorn@^8.9.0` is installed: `npm install acorn@^8.9.0`.

• SyntaxError: Unexpected token (some_typescript_keyword)

  cause Attempting to parse TypeScript specific syntax (e.g., `type`, `interface`, decorators) without correctly extending Acorn with `acorn-typescript` or with incorrect parser options.
  fix Verify that `acorn.Parser.extend(tsPlugin())` is correctly applied to your parser instance and that `ecmaVersion: 'latest'` and `sourceType: 'module'` are set if applicable.

• TypeError: acorn_typescript__WEBPACK_IMPORTED_MODULE_1___default is not a function

  cause Attempted to import the `acorn-typescript` plugin incorrectly, typically using `import { tsPlugin } from 'acorn-typescript'` instead of a default import.
  fix Use a default import: `import tsPlugin from 'acorn-typescript'`.

Warnings

• gotcha The `locations: true` option is mandatory when using `acorn-typescript`. Failing to enable it will result in parsing errors or unexpected AST structures.
  Fix: Always include `{ locations: true }` in the options object passed to `acorn.parse()` or `acorn.Parser.extend(...).parse()`.
• breaking Starting from `v1.3.7`, `acorn-typescript` added explicit validation for `locations` when using `static parse` or `static parseExpression`. While the requirement existed before, this version likely makes the omission an explicit error or warning during parsing.
  Fix: Ensure `locations: true` is always provided in the parser options. Refer to the `quickstart` example for correct usage.
• gotcha This package is a plugin for Acorn. It requires `acorn` as a peer dependency, specifically `acorn@>=8.9.0`. Ensure a compatible version of `acorn` is installed in your project to avoid runtime errors.
  Fix: Install a compatible version of `acorn` alongside `acorn-typescript`: `npm install acorn@^8.9.0` or `yarn add acorn@^8.9.0`.
• gotcha When parsing TypeScript declaration files (`.d.ts`) or code within `declare module` blocks, you must enable the `dts: true` option in the plugin configuration to handle ambient context-specific syntax correctly.
  Fix: Pass `{ dts: true }` to the plugin function: `acorn.Parser.extend(tsPlugin({ dts: true }))`.

Install

• npm install acorn-typescript npm
• yarn add acorn-typescript yarn
• pnpm add acorn-typescript pnpm

Imports

• acorn
  wrong:

  const acorn = require('acorn')

  correct:

  import * as acorn from 'acorn'

  Primarily used in ESM contexts. While Acorn itself supports CJS, this plugin's usage examples are ESM.
• tsPlugin
  wrong:

  import { tsPlugin } from 'acorn-typescript'

  correct:

  import tsPlugin from 'acorn-typescript'

  This is a default export, not a named export.
• Parser.extend
  wrong:

  acorn.extend(tsPlugin())

  correct:

  acorn.Parser.extend(tsPlugin())

  The `extend` method is a static method on the `Parser` class, not directly on the `acorn` module.

Quickstart

Demonstrates how to extend Acorn's parser with the `acorn-typescript` plugin to parse TypeScript code, including basic syntax and ambient contexts using the `dts` option, ensuring `locations: true` is set.

import * as acorn from 'acorn';
import tsPlugin from 'acorn-typescript';

// Example 1: Basic TypeScript parsing
const code1 = `
const a: number = 1;
type MyType = string;
export {
  a,
  type MyType as RenamedType
};
class MyClass { accessor b = 'hello'; }
`;

const ast1 = acorn.Parser.extend(tsPlugin()).parse(code1, {
  sourceType: 'module',
  ecmaVersion: 'latest',
  locations: true // Required for acorn-typescript
});

console.log('Parsed AST 1 (basic):', JSON.stringify(ast1.body[0], null, 2));

// Example 2: Parsing within a TypeScript ambient context (.d.ts files)
const code2 = `
declare module 'my-module' {
  interface MyInterface {
    name: string;
    id: number;
  }
}
`;

const ast2 = acorn.Parser.extend(tsPlugin({ dts: true })).parse(code2, {
  sourceType: 'module',
  ecmaVersion: 'latest',
  locations: true // Still required
});

console.log('Parsed AST 2 (dts context):', JSON.stringify(ast2.body[0], null, 2));