js2-mode gives Emacs a JavaScript syntax tree other packages can use

The AST is the product, not the highlighting

The mode is described as an improved JavaScript editing mode for GNU Emacs, but the interesting part is stated further down: the See Also section lists third-party modes that use the generated syntax tree, and among them are js2-refactor and skewer-mode. So the value of js2-mode is not that it colours JavaScript better than the built-in mode. It is that it produces a parse tree other Emacs Lisp code can walk, which is what makes refactoring and semantic tooling possible at all. The project's own bug guidance points at the same distinction: indentation problems should be reported with the Emacs bug reporter after trying to reproduce them with `js-mode` first, and the reason given is that starting with Emacs 25, js2-mode delegates indentation to the indentation engine of `js-mode`. In other words, the built-in mode owns the layout and js2-mode owns the tree.

For React and JSX, the built-in mode is the recommendation

The React and JSX section is where the documentation tells you not to use this package, which is a good sign. The currently recommended solution is to install Emacs 27, either built from source or from a PPA snapshot, and use `js-mode` as the major mode. The reason is that `js-mode` in Emacs 27 includes full support for syntax highlighting and indenting of JSX syntax. To make use of the JS2 AST and the packages that integrate with it, the documentation recommends `js2-minor-mode` instead, which is a minor mode layered over the built-in one rather than a replacement for it. The instructions point into the Commentary section of the source file for the details, and an alternative exists in rjsx-mode, which comes with certain trade-offs that the README does not enumerate.

Two package archives, two different things

Installation goes through one of two archives, and the distinction between them matters for what you get. The stable versions are hosted at GNU ELPA and are reachable from the built-in package list with `M-x list-packages`. The latest development version comes from MELPA. For a package that is part of the GNU Emacs ecosystem and subject to the same copyright assignment policy as Emacs itself, the ELPA/MELPA split is the usual one, and it means an ELPA install gives you a version that has gone through the package review process. The requirements are Emacs 24.1 or newer and `cl-lib`, either built in or installed from GNU ELPA, so on an old Emacs there is one more thing to install before this one. The README also links a NEWS.md file for the latest user-visible changes, which is the right place to look for what a new version actually changed.

Byte-compilation issues after an Emacs upgrade

The bug section documents a specific failure mode that will waste your afternoon if you hit it cold. If you see broken syntax highlighting and timer errors, and you recently upgraded Emacs from version 24.2 or earlier, the fix is to reinstall or byte-recompile the package. The reason is not spelled out, but the cause is a known property of the Emacs Lisp loader: a package compiled against an older Emacs can carry stale byte code that does not match the newer runtime, and the symptoms are highlighting and timers misbehaving rather than an error message. The issue tracker link is given for the long form of the explanation. The second bug rule is about indentation problems, which should be reported as Emacs bugs rather than js2-mode bugs, again because js2-mode delegates indentation to js-mode.

Contributions come with a copyright assignment form

The contributing section is where the project explains itself in a way that very few README files do. js2-mode is subject to the same copyright assignment policy as Emacs itself, org-mode, CEDET and other packages in GNU ELPA. The practical consequence is stated plainly: any legally significant contributions can only be accepted after the author has completed their paperwork, and you have to ask for the request form, which will be sent to you. That is the GNU convention for a package that will live in ELPA, where the copyright needs to be held in a way that survives a maintainer change. It also tells you something about the project's status: it is not a casual weekend package but one intended to be a long term part of the Emacs distribution, and the barrier to contributing is deliberate.

The repository is small and builds with a plain Makefile

The top level is three Emacs Lisp source files and a test directory, plus the usual metadata: `js2-mode.el` is the mode itself, `js2-imenu-extras.el` adds to the imenu, and `js2-old-indent.el` is the older indentation implementation kept around. There is a `tests/` directory, a `Makefile`, a `NEWS.md` for the user-visible changes, a `.dir-locals.el` and a `.elpaignore`. The Makefile compiles the sources non-interactively with a clean environment, using batch flags of `-batch -Q`, and the test target runs the ERT test suite in batch mode:

test: all
	${EMACS} $(BATCHFLAGS) -L . \
	  $(addprefix -l ,$(OBJS)) \
	  -f ert-run-tests-batch-and-exit

The `-Q` flag is the one that matters, since it starts Emacs without loading your personal configuration, so the tests see the package as a user would see it rather than as your own setup makes it. There is a GitHub Actions workflow for the test suite, and the licence is GPL 3.0. The last push to the master branch was on 2026-06-27.

Editorial conclusion

Adopt js2-mode if you edit JavaScript in Emacs and want a parse tree that other tools can query, since that is the specific thing it adds over the built-in mode and what packages like js2-refactor and skewer-mode depend on. Do not adopt it if your only need is syntax highlighting, because js-mode in a recent Emacs already covers JSX highlighting and indentation. Verify first which major mode you actually want, since the documentation recommends the built-in js-mode for most work and js2-minor-mode only when you need the AST, and note that the copyright assignment policy means a substantial contribution comes with paperwork.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. mooz/js2-mode on GitHub
4. README