Skip to content
Jump to references/definitions using ag & js2-mode's AST in Emacs
Emacs Lisp
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.


Type Name Latest commit message Commit time
Failed to load latest commit information.


The GitHub repository is mirrored from

xref-js2 adds navigation to definitions or references to JavaScript projects in Emacs.

xref-js2 adds an xref backend for JavaScript files.

Instead of using a tag system, it relies on ag to query the codebase of a project. This might sound crazy at first, but it turns out that ag is so fast that jumping using xref-js2 is most of the time instantaneous, even on fairly large JavaScript codebases (it has been tested on 50k lines of JS code).

Because line by line regexp search has its limitations, xref-js2 does a second pass on result candidates and eliminates possible false positives using js2-mode's AST, thus giving very accurate results.



If you use js2-mode, M-. will be bound by js2, you might want to unbind it:

(define-key js2-mode-map (kbd "M-.") nil)

Then you need to add the xref backend:

(add-hook 'js2-mode-hook (lambda ()
  (add-hook 'xref-backend-functions #'xref-js2-xref-backend nil t)))


By default, xref-js2 will use ag for search operations, to switch to using rg put the following into your config file and ensure the ripgrep executeable is visible from your PATH environment variable:

(setq xref-js2-search-program 'rg)

If you have issues with xref-js2 using rg not searching certain files, ensure the extension of those files is included in xref-js2-js-extensions.

You can further customize the execution of ag or rg by xref-js2 by changing xref-js2-ag-arguments & xref-js2-rg-arguments respectively. Though take care when doing so, many of these are used to produce an output which xref-js2 can understand.


xref-js2 uses the xref, so the same keybindings and UI as other xref backends is used:

  • M-. Jump to definition
  • M-? Jump to references
  • M-, Pop back to where M-. was last invoked


Jumping to definitions and back


Finding references


You can’t perform that action at this time.