tc39/ecma262: the repository behind the ECMAScript specification

What ECMA-262 actually is, and who the repository serves

The README opens with a plain statement of scope: this repository contains the source for the current draft of ECMA-262, the ECMAScript Language Specification. The published, human-readable version lives at https://tc39.es/ecma262/. That distinction matters more than it looks. The repository is not the specification; it is the input from which the specification is generated. The README also points at searchfox for readers who want to explore how the specification was written with its history attached.

The audience follows from that. If you are implementing a JavaScript engine, writing a parser or a static analysis tool, or arguing about whether some behaviour is required or merely permitted, the normative text is the thing you cite. If you are building a web application, this repository will not help you directly. It has no runtime, no polyfills and no compatibility data. The primary language listed for the repository is HTML, which is a fair description of what it mostly contains: spec.html, a large structured document plus a set of generated Unicode property tables at the top level (table-binary-unicode-properties.html, table-nonbinary-unicode-properties.html, table-binary-unicode-properties-of-strings.html).

One boundary is worth stating early. ECMA-262 defines the language. It does not define the DOM, fetch, Node APIs or browser behaviour. Those live in other specifications. A question that starts with "does JavaScript do X" often ends in a host environment document rather than this one.

How the spec builds: ecmarkup, spec.html and the out directory

The mechanism is a static build. spec.html is written in ecmarkup, a markup dialect for specification prose, algorithms and grammar. The build script in package.json invokes ecmarkup against spec.html and writes the result into out. The devDependencies list ecmarkup and jsdom, and nothing else. There is no server component and no database.

The build pipeline has a few stages worth knowing about. The prebuild-only script removes out, recreates it, and copies the img directory into it, which means images are handled outside ecmarkup. The build-only script then runs ecmarkup with --verbose, spec.html as input, and --multipage out as output, so the default result is a directory of linked pages rather than one enormous file. The build script wraps build-only with --lint-spec --strict, which turns spec linting into a build failure. That is a real constraint on contributors: a change that breaks the lint rules does not produce a build at all.

Two other targets exist. build-for-pdf runs the same ecmarkup pass with --assets external --assets-dir out --printable and also lints strictly. The pdf script chains build-for-pdf with prince-books, an external binary, to emit out/ECMA-262.pdf. If your goal is the PDF rather than the HTML, the README does not document how prince-books is installed; that dependency is outside the npm tree.

There is also a formatting tool. The format script runs emu-format --write spec.html, so the source has a canonical layout, and check-commit runs node scripts/check-commit. Neither emu-format nor the check-commit script is described in the README, which means a first-time contributor learns what they enforce by reading scripts/ or by having a pull request rejected.

Building the spec locally: install and first run

The README gives the whole workflow in three sentences: clone, run npm install, then npm run build or npm run watch. The results appear in out. The clean script deletes that directory.

Start with the install. From the repository root:

npm install

That installs ecmarkup and jsdom from devDependencies. Nothing is published from this package; package.json sets "private": true, so npm install here is purely a local toolchain step.

For a one-off build, run the default target. It lints strictly, so a spec edit that violates a lint rule will fail the command rather than produce output:

npm run build

After it finishes, out contains the multipage HTML rendering of spec.html. Open out/index.html in a browser. You should see the same structure as the published specification, with a table of contents linking into per-clause pages.

If you are editing spec.html and want to see changes without rerunning the build by hand, use the watch target. It runs the same non-strict build inside a watch loop:

npm run watch

Note the asymmetry: watch calls build-only with --lint-spec --watch, while build calls build-head, which adds --strict. So a lint warning that stops npm run build may still let npm run watch produce output. If you are preparing a contribution, build is the target that matches what CI-style strictness expects. To start over, npm run clean removes out entirely; the next build recreates it.

Where the repository stops: proposals, engines and the wrong use case

The most common mistake with this repository is treating it as the home of JavaScript's future. It is not. The README states that proposals follow the TC39 process and are tracked in the proposals repository, with links out to finished proposals, active proposals, stage 1, stage 0 and inactive lists. If you want to know whether a syntax feature is coming, this is the wrong repository. If you want to know what is already required, it is the right one.

A second limitation is the build dependency on ecmarkup's version. The devDependencies pin ecmarkup to ^25.0.2 and jsdom to ^27.0.0. Because spec.html is written in ecmarkup's dialect, a change in ecmarkup's parsing or lint rules can change what the build accepts. The repository does not describe a compatibility policy for that. Anyone maintaining a fork of spec.html, for example an engine team annotating the text, inherits that coupling.

A third is the PDF path. It depends on prince-books, which is not an npm dependency and is not covered by the README's install instructions. The npm run pdf target will only work for someone who has already solved that separately.

Finally, the licence. package.json declares "SEE LICENSE IN https://tc39.es/ecma262/#sec-copyright-and-software-license", and the repository metadata reports NOASSERTION rather than a standard SPDX identifier. The LICENSE.md file exists at the top level, but if you need a machine-readable licence tag for a dependency scanner, this repository will not give you one. Whether that matters to you depends on how you redistribute the text, and it is worth reading the linked section rather than assuming a permissive default.

ecma262 against esmeta and the proposals repository

The closest thing to an alternative in the same ecosystem is not another spec; it is a different way of consuming this one. The repository ships esmeta-ignore.json at the top level, which is a hint that the text is also fed into esmeta, a project that extracts an executable model from the specification. The difference in approach is stark. This repository produces prose and algorithms for humans. esmeta consumes that same source and produces something a machine can run. If your goal is to test an engine against the specification automatically, reading spec.html will not get you there; the extracted model is the relevant artifact, and this repository only marks which parts to skip.

Compared with the proposals repository, the split is temporal. tc39/proposals tracks what might become part of the language, with stage numbers and links. tc39/ecma262 holds what already is, plus the draft of what is next in line to be ratified. A team tracking feature support needs both, and neither replaces the other.

Compared with MDN or any tutorial site, the difference is authority and cost. A tutorial tells you what engines do today. ECMA-262 tells you what an implementation is required to do. The cost is that the specification is written for implementers: algorithms are numbered steps, grammar is formal, and there is no runnable example anywhere in the build output. Reading it is slow, and that is by design.

Maintenance, releases and what a fork costs you

The repository is not archived, and the last push was on 2026-09-20. Recent releases show a steady rhythm tied to the annual cycle: es2026-candidate-2026-03-31 in March 2026, es2026 in July 2026, and es2026-errata, labelled "ES2026, take two", on 2026-07-28. The errata release is the interesting one. It confirms that a ratified edition still receives corrections, so pinning to a release tag does not mean the text you pinned is the last word on that edition.

Upgrade cost for a consumer is low in one sense and high in another. There is no API to migrate and no runtime to redeploy. But if you have copied text, anchors or section numbers into your own documentation, engine comments or test names, those references move when the draft is reorganised. Section anchors are the stable handle here, which is why citing a clause by its anchor rather than by page position is the practical habit.

For contributors the cost is the toolchain. You need Node, npm install, a working ecmarkup build, and a passing strict lint before your change produces output. The repository provides npm run format for spec.html layout and npm run check-commit as a pre-submission check, but the README does not explain what either enforces. Expect to read scripts/ and CONTRIBUTING.md before your first pull request. On licensing, the npm package is private and the licence is referenced by URL rather than declared as an SPDX identifier; if you plan to redistribute the specification text or a derived build, read the linked copyright and software licence section in full rather than treating the metadata field as an answer.

Editorial conclusion

Adopt this repository if you write a JavaScript engine, a parser, a linter, a transpiler or a runtime, and you need the normative text rather than a summary of it. Do not adopt it if you want a library to install, a polyfill, a version matrix or a compatibility table: ECMA-262 defines the language, not the host environments, and the README points elsewhere for proposals. Before relying on any clause, open https://tc39.es/ecma262/, find the section anchor you need, and check the same anchor in the repository's spec.html at the commit you are targeting, because the built page tracks the draft and the draft moves.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. tc39/ecma262 on GitHub