# engine262: a spec-first JavaScript interpreter written in TypeScript

> engine262 implements ECMA-262 in JavaScript and TypeScript, built so that a language proposal can be added as a small diff to the parser and evaluator. Its stated priorities are spec compliance, introspection and ease of modification, with speed explicitly given up.

**engine262/engine262** — An implementation of ECMA-262 in JavaScript

- Repository: https://github.com/engine262/engine262
- Website: https://engine262.js.org
- Stars: 948 · Forks: 76
- Language: TypeScript
- License: MIT
- Published: 2026-10-20 · Updated: 2026-10-20 · Language: en
- Canonical page: https://hysenlabs.com/projects/engine262-engine262

## Why a second JavaScript engine exists at all

The stated reason for engine262 is experimental, not competitive. The documentation explains that while helping develop new features for JavaScript, the most useful way to find what works and what does not is to actually run code using the new feature. Babel is described as fantastic for this, but sometimes features cannot be nicely represented with it. Implementing a feature directly in an existing engine is a large undertaking, involving long compile times and annoying bugs with the optimizing compilers. engine262 is presented as a playground where new features can be quickly prototyped and explored. The project also claims a second use: it has been used to find bugs in ECMA-262 and in test262, the test suite for conforming JavaScript implementations. So the audience is narrow and identifiable: specification contributors, compiler engineers, and people who want to read how a proposal behaves rather than infer it from a proposal document. The repository topics list interpreter, reference-implementation and ecma262, and the homepage is engine262.js.org.

## Three goals and one explicit non-goal

The project documentation lists the goals as 100% Spec Compliance, Introspection and Ease of modification, and then a single non-goal: speed at the expense of any of the goals. That ordering tells you how to read the codebase. Because spec compliance comes first, behaviour is anchored to the written specification rather than to what popular engines happen to do, which makes the engine a useful oracle when the spec text and the shipped engines disagree. Introspection as a second goal means the running engine exposes its own internals for inspection, and the CLI documentation supports that with a section on not exposing the $ and $262 global variables for the test262 test suite. Ease of modification is the third goal and the one the documentation's diff is there to demonstrate. The cost of this prioritisation is explicit: a slow interpreter. Nothing in the documentation suggests engine262 is intended to run production traffic.

## Adding do expressions as a parser diff and an evaluator case

The documentation backs the ease-of-modification claim with a concrete example. Adding do expressions to the engine is presented as a diff touching two files, src/evaluator.mts and src/parser/ExpressionParser.mts. The parser side adds a case for Token.DO that starts a node, advances the token stream, parses a block, and finishes the node as DoExpression. The evaluator side adds a case for 'DoExpression' that yields the evaluation of the node's Block. The same simplicity is claimed for optional chaining, pattern matching, and the pipeline operator. Two observations for a newcomer. First, the engine is structured around a switch in the evaluator, so adding a syntax form means touching a dispatch table, not rewriting a compiler. Second, the code in the diff is TypeScript in .mts files, and the top level of the repository carries tsconfig.json, tsconfig.base.json, babel.config.json and eslint.config.mjs, so the build toolchain is part of the experience rather than a hidden detail.

## Installing from npm and running the CLI with the documented flags

The project is installable from npm, and gives three package managers.

```shell
npm install @engine262/engine262
yarn install @engine262/engine262
pnpm install @engine262/engine262
```

The package name in package.json is @engine262/engine262, and a global install gives you the CLI. The documented flags are the interesting part for experimentation. --module and -m evaluate the file as a module. --eval and -e evaluate a given string and exit, which is what you want when checking a single expression. --features=<featureA,featureB> and --features=all select which ECMAScript features are enabled, and engine262 --list-features prints the full set. Two flags remove behaviour rather than add it: --no-test262 stops the engine exposing $ and $262 as globals, and --no-inspector stops the inspector from starting. There is also --no-preview to disable the preview feature in the inspector.

## The inspector on ws://localhost:9229 is where the debugging happens

By default engine262 starts an inspector on ws://localhost:9229/, which the documentation compares it to Node.js with --inspector, and points at the Node.js debugging guide for connecting an inspector client. The classic playground and a Chrome Devtools style playground are both hosted at engine262.js.org, with the latter at engine262.js.org/devtools.html. For anyone working on engine262 itself, the documentation says debugging engine262 mainly happens in the inspector website, and package.json exposes an npm run inspector script that starts the site with a specific configuration flag. The pairing of a websocket inspector with a browser frontend is a deliberate design choice. It gives you a window into the evaluator state while a proposal is half-implemented, which is exactly the phase where a spec author needs to see what the engine actually did.

## The build and test commands that a contributor needs

The development workflow is short enough to list in full.

```shell
npm run build
npm run watch
npm run test:test262
npm start
npm run inspector
```

npm run build and npm run watch build and watch the build, npm run test:test262 runs the test262 suite and accepts runner options after -- --help, npm start starts the engine262 CLI, and npm run inspector starts the debugging website. The test262 runner lives at test/test262/test262.mts and, like the CLI at bin/engine262.js, requires a recent version of Node.js. To run engine262 itself you need an engine with support for recent ECMAScript features, which means the bootstrap dependency is a modern engine running an interpreter written in that same language. The tree also shows a .gitmodules entry and a test/ directory, and a vitest.config.mts, so the repository supports more than the test262 suite alone.

## No GitHub releases, and a package version of 0.0.1

The maintenance picture is unusual and needs reading carefully. The repository is not archived and the last push was on 2026-10-19, so the tree is being worked on. But the repository has no GitHub releases, and the version field in package.json reads 0.0.1 with the packageManager pinned to npm@9.8.0. Those two facts together mean there is no changelog to consult and no version history to roll back to. The MIT licence on the package and the LICENSE file at the root cover the code as long as the copyright notice is kept, though it says nothing about the licences of the code you might write on top. Other projects in the same space, listed in the project as reference, are JS-Interpreter by NeilFraser, metaes, and sval, and the documentation is explicit that engine262 is not based on any of them. That independence is a design choice, not an accident, and it means the interpreter's internal structure is free to follow the spec rather than another project's architecture.

## Conclusion

engine262 is worth your time if you are a TC39 contributor, a compiler engineer, or anyone who needs to run a proposal before it ships in a production engine, and it is the wrong tool for application work because the project lists speed at the expense of its goals as a non-goal. Before adopting it, check the version field in package.json, which reads 0.0.1 even though the last push was on 2026-10-19, and confirm that the Node.js version you have can run the CLI, since the documentation states that bin/engine262.js requires a recent version of Node.js.

## FAQ

### How do I install engine262?

Installation is from npm using npm install @engine262/engine262, with equivalent yarn and pnpm commands. A global install gives you the engine262 CLI.

### Which JavaScript proposals does engine262 support?

The documentation names do expressions, optional chaining, pattern matching and the pipeline operator as proposals that were simple to add, showing the do expression diff against src/evaluator.mts and src/parser/ExpressionParser.mts. You can also run engine262 --list-features to see all ECMAScript features that can be switched.

### What are the Node.js requirements for engine262?

The documentation states that to run engine262 itself you need an engine with support for recent ECMAScript features, and that the CLI at bin/engine262.js and the test262 runner at test/test262/test262.mts require a recent version of Node.js.

## Sources

- [engine262/engine262 on GitHub](https://github.com/engine262/engine262)
- [Issues](https://github.com/engine262/engine262/issues)
- [License: MIT](https://github.com/engine262/engine262/blob/main/LICENSE)
- [Project website](https://engine262.js.org)
- [README](https://github.com/engine262/engine262/blob/main/README.md)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/engine262-engine262