{"id":10475,"library":"acorn-typescript","title":"Acorn TypeScript Parser Plugin","description":"acorn-typescript is an experimental alternative plugin for Acorn, a small, fast JavaScript parser. It extends Acorn to parse TypeScript scripts into a TypeScript AST, aiming for faster performance compared to other TypeScript parsers. The current stable version is 1.4.13, and it exhibits an active release cadence, frequently addressing bug fixes related to various TypeScript syntax features like optional class properties, generic types, arrow functions, and decorators. Key differentiators include its integration as an Acorn plugin, allowing existing Acorn users to add TypeScript parsing capabilities, and its specific focus on optimizing parsing speed. It supports standard TypeScript syntax, decorators, and JSX/TSX. It requires `acorn` version `>=8.9.0` as a peer dependency.","status":"active","version":"1.4.13","language":"javascript","source_language":"en","source_url":"https://github.com/TyrealHu/acorn-typescript","tags":["javascript","typescript"],"install":[{"cmd":"npm install acorn-typescript","lang":"bash","label":"npm"},{"cmd":"yarn add acorn-typescript","lang":"bash","label":"yarn"},{"cmd":"pnpm add acorn-typescript","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core parser library that this package extends as a plugin.","package":"acorn","optional":false}],"imports":[{"note":"Primarily used in ESM contexts. While Acorn itself supports CJS, this plugin's usage examples are ESM.","wrong":"const acorn = require('acorn')","symbol":"acorn","correct":"import * as acorn from 'acorn'"},{"note":"This is a default export, not a named export.","wrong":"import { tsPlugin } from 'acorn-typescript'","symbol":"tsPlugin","correct":"import tsPlugin from 'acorn-typescript'"},{"note":"The `extend` method is a static method on the `Parser` class, not directly on the `acorn` module.","wrong":"acorn.extend(tsPlugin())","symbol":"Parser.extend","correct":"acorn.Parser.extend(tsPlugin())"}],"quickstart":{"code":"import * as acorn from 'acorn';\nimport tsPlugin from 'acorn-typescript';\n\n// Example 1: Basic TypeScript parsing\nconst code1 = `\nconst a: number = 1;\ntype MyType = string;\nexport {\n  a,\n  type MyType as RenamedType\n};\nclass MyClass { accessor b = 'hello'; }\n`;\n\nconst ast1 = acorn.Parser.extend(tsPlugin()).parse(code1, {\n  sourceType: 'module',\n  ecmaVersion: 'latest',\n  locations: true // Required for acorn-typescript\n});\n\nconsole.log('Parsed AST 1 (basic):', JSON.stringify(ast1.body[0], null, 2));\n\n// Example 2: Parsing within a TypeScript ambient context (.d.ts files)\nconst code2 = `\ndeclare module 'my-module' {\n  interface MyInterface {\n    name: string;\n    id: number;\n  }\n}\n`;\n\nconst ast2 = acorn.Parser.extend(tsPlugin({ dts: true })).parse(code2, {\n  sourceType: 'module',\n  ecmaVersion: 'latest',\n  locations: true // Still required\n});\n\nconsole.log('Parsed AST 2 (dts context):', JSON.stringify(ast2.body[0], null, 2));\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Always include `{ locations: true }` in the options object passed to `acorn.parse()` or `acorn.Parser.extend(...).parse()`.","message":"The `locations: true` option is mandatory when using `acorn-typescript`. Failing to enable it will result in parsing errors or unexpected AST structures.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure `locations: true` is always provided in the parser options. Refer to the `quickstart` example for correct usage.","message":"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.","severity":"breaking","affected_versions":">=1.3.7"},{"fix":"Install a compatible version of `acorn` alongside `acorn-typescript`: `npm install acorn@^8.9.0` or `yarn add acorn@^8.9.0`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pass `{ dts: true }` to the plugin function: `acorn.Parser.extend(tsPlugin({ dts: true }))`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Add `{ locations: true }` to the options object passed to the `parse` method.","cause":"`locations: true` was not included in the parser options.","error":"Error: The 'locations' option must be enabled for acorn-typescript."},{"fix":"Ensure `acorn@^8.9.0` is installed: `npm install acorn@^8.9.0`.","cause":"The `acorn` package might not be installed, or an incompatible version is present, preventing the `Parser.extend` method from being accessed correctly.","error":"TypeError: Cannot read properties of undefined (reading 'extend')"},{"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.","cause":"Attempting to parse TypeScript specific syntax (e.g., `type`, `interface`, decorators) without correctly extending Acorn with `acorn-typescript` or with incorrect parser options.","error":"SyntaxError: Unexpected token (some_typescript_keyword)"},{"fix":"Use a default import: `import tsPlugin from 'acorn-typescript'`.","cause":"Attempted to import the `acorn-typescript` plugin incorrectly, typically using `import { tsPlugin } from 'acorn-typescript'` instead of a default import.","error":"TypeError: acorn_typescript__WEBPACK_IMPORTED_MODULE_1___default is not a function"}],"ecosystem":"npm"}