You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.

66 lines
2.3 KiB

6 years ago
7 years ago
7 years ago
7 years ago
7 years ago
  1. # xref-js2
  2. The GitHub repository is mirrored from [](
  3. `xref-js2` adds navigation to definitions or references to JavaScript projects
  4. in Emacs.
  5. `xref-js2` adds an xref backend for JavaScript files.
  6. Instead of using a tag system, it relies on `ag` to query the codebase of a
  7. project. This might sound crazy at first, but it turns out that `ag` is so fast
  8. that jumping using `xref-js2` is most of the time instantaneous, even on fairly
  9. large JavaScript codebases (it has been tested on 50k lines of JS code).
  10. Because line by line regexp search has its limitations, `xref-js2` does a second
  11. pass on result candidates and eliminates possible false positives using
  12. `js2-mode`'s AST, thus giving very accurate results.
  13. ## Requirements
  14. - Emacs 25.1
  15. - `ag` (the [silver searcher](
  16. - or `rg` ([ripgrep](
  17. - js2-mode
  18. ## Installation
  19. If you use `js2-mode`, `M-.` will be bound by `js2`, you might want to unbind it:
  20. ```elisp
  21. (define-key js2-mode-map (kbd "M-.") nil)
  22. ```
  23. Then you need to add the xref backend:
  24. ```elisp
  25. (add-hook 'js2-mode-hook (lambda ()
  26. (add-hook 'xref-backend-functions #'xref-js2-xref-backend nil t)))
  27. ```
  28. ## Customisations
  29. 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:
  30. ```elisp
  31. (setq xref-js2-search-program 'rg)
  32. ```
  33. 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`.
  34. 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.
  35. ## Keybindings
  36. `xref-js2` uses the `xref`, so the same keybindings and UI as other xref backends is used:
  37. - `M-.` Jump to definition
  38. - `M-?` Jump to references
  39. - `M-,` Pop back to where `M-.` was last invoked
  40. ## Demo
  41. ### Jumping to definitions and back
  42. ![jump-to-definition.gif](screencasts/jump-to-definition.gif)
  43. ### Finding references
  44. ![jump-to-references.gif](screencasts/jump-to-references.gif)