@stackline/esprima

Compatibility-first maintained Esprima 4 parser with a dependency-free runtime, reproducible build, and first-party types.

Documentation | npm | Issues | Repository

Current package version: 1.0.3

Why this package?

A compatibility-first maintained continuation of esprima@4.0.1. It parses and tokenizes ECMAScript 2017 and JSX using the established Esprima API, while shipping a reproducible build, first-party TypeScript declarations, and no production dependencies.

This project is independent. It is not affiliated with or endorsed by the JS Foundation, OpenJS Foundation, jQuery, Ariya Hidayat, or the upstream Esprima project.

Compatibility

• the six enumerable exports from esprima@4.0.1 are preserved;
• parse, parseScript, parseModule, tokenize, Syntax, and the compatibility value version === '4.0.1' retain their upstream behavior;
• CommonJS, browser-global, AMD, esparse, and esvalidate entry points are preserved;
• the generated runtime is ES5 and is validated on Node.js 8 through current supported Node releases;
• TypeScript declarations are additive and compile with TypeScript 3.9;
• the package has no production, optional, or peer dependency edges.

@stackline/esprima uses its own package version. The first Stackline release is 1.0.0, while the public esprima.version value intentionally remains 4.0.1 for drop-in compatibility.

See COMPATIBILITY_CONTRACT.md for the exact boundary and MIGRATION.md for migration guidance.

Installation

Install

npm install @stackline/esprima

Existing applications can preserve require('esprima') and imports from esprima with an npm alias:

Usage

npm install esprima@npm:@stackline/esprima

const esprima = require('esprima')
const program = esprima.parseScript('const answer = 42')

The alias changes dependency resolution only. Application source code does not need to change.

Features and Integrations

Parsing

const esprima = require('@stackline/esprima')

const program = esprima.parseScript('const answer = 42', {
  loc: true,
  range: true,
  tokens: true
})

console.log(program.body[0].type)

Use parseModule for ECMAScript modules:

const moduleProgram = esprima.parseModule('export default 42')

The historical parse method is also preserved. Set sourceType: 'module' when parsing module source through that method.

Tokenizing

const tokens = esprima.tokenize('answer += 1', {
  loc: true,
  range: true
})

JSX

const program = esprima.parseScript('<Panel value={answer} />', {
  jsx: true
})

JSX support remains experimental, matching upstream 4.0.1.

Command line

esparse --loc source.js
esvalidate source.js

Both commands also accept standard input with -.

Scope

This is an ECMAScript 2017 compatibility parser. It does not claim support for newer JavaScript grammar such as optional chaining, class fields, import attributes, or current proposal syntax. Consumers that need a modern language grammar should select a parser designed for that grammar instead of assuming that a maintenance release changes Esprima's accepted language.

Release quality

Every release is gated by the original fixture and regression suites, differential checks against esprima@4.0.1, hostile-environment and malformed input tests, browser and CLI checks, TypeScript 3.9/current compilation, warning-free packed installs, valid dependency trees, and zero audit findings.

Security

Report suspected vulnerabilities privately as described in SECURITY.md. Parsing untrusted source still requires caller limits for input size, concurrency, memory, and execution deadlines.

Local Development

git clone https://github.com/alexandroit/stackline-esprima.git
cd stackline-esprima
npm ci
npm run verify

Release tooling uses Node.js 24.20.0 and npm 11.19.0. The consumer runtime contract remains the one documented above.

Consumer Smoke Test

Run the repository's existing consumer/package check after installing development dependencies:

npm run test:smoke

Release Checklist

Run npm run verify and inspect the package contents before release. Publish a new version through the GitHub Actions publishing workflow, using the SHA-512 digest of the reviewed tarball. Verify the exact published version, tarball integrity, and npm provenance after the run.

License

BSD-2-Clause. The complete upstream copyright and license are retained in LICENSE, NOTICE, and THIRD_PARTY_LICENSES.md.

Credits and original authors

• Stackline Maintainers.
• Ariya Hidayat.
• JS Foundation and other Esprima contributors.
• Stackline maintenance: Alexandro Paixao Marques and Stackline contributors.

Original copyright, license notices and contributor acknowledgements remain part of this distribution. Stackline maintenance does not replace authorship of the original work.

Community and Links

• Stackline website
• GitHub projects
• npm packages
• Reddit community — r/Stackline
• Maintainer LinkedIn

Use this repository's issue tracker for reproducible bugs and feature requests. Join r/Stackline for examples, usage questions and release discussions.