Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

JSX Documentation #531

Merged
merged 11 commits into from
Jun 6, 2019
Merged

JSX Documentation #531

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
11 commits
Select commit Hold shift + click to select a range
46aed6d
Extend explanation to disclaim key issue but provide an alternative
jacksonrayhamilton Jun 4, 2019
d9bba5b
Update recommendations for using JSX with respect to Emacs 27
jacksonrayhamilton Jun 4, 2019
1662cb8
Document changes with relation to JSX support added in Emacs 27
jacksonrayhamilton Jun 4, 2019
41ca3ad
Reference latest revision of the commentary
jacksonrayhamilton Jun 4, 2019
6cc0a8a
Merge paragraphs so the information reads better
jacksonrayhamilton Jun 5, 2019
037bcf7
Clarify what is likely to fail
jacksonrayhamilton Jun 5, 2019
e785721
Reference latest revision of the commentary
jacksonrayhamilton Jun 5, 2019
14113fe
Remove date
jacksonrayhamilton Jun 6, 2019
8e2cdd4
Revert extra added information
jacksonrayhamilton Jun 6, 2019
bb73461
Revert doc changes and explain JSX options for all emacsen later
jacksonrayhamilton Jun 6, 2019
2d2fb4b
Reference latest revision of the commentary
jacksonrayhamilton Jun 6, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions NEWS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,13 @@
# History of user-visible changes

## 2019-06-03
jacksonrayhamilton marked this conversation as resolved.
Show resolved Hide resolved

* Emacs 27 now provides improved JSX indentation support, along with
new JSX highlighting and detection support. Install Emacs 27 and use
`js-mode` with `js2-minor-mode` (see README), rather than
`js2-jsx-mode`.
* Using `js2-jsx-mode` will now trigger a warning in Emacs 27.

## 2019-02-19

* Changed the default of `js2-strict-trailing-comma-warning` to nil.
Expand Down
21 changes: 17 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -30,13 +30,26 @@ or e.g. install a snapshot from a
use `js-mode` as the major mode. To make use of the JS2 AST and the
packages that integrate with it, we recommend `js2-minor-mode`. See
the corresponding [instructions in the
Commentary](https://github.com/mooz/js2-mode/blob/ae9fea81cf9ed80f403c161fde4d8aff1ceb3769/js2-mode.el#L57).
Commentary](https://github.com/mooz/js2-mode/blob/6cc0a8a87a9178e44c51203e1fe34c57f246a7de/js2-mode.el#L60).

`js-mode` in Emacs 27 includes full support for syntax highlighting
and indenting of JSX syntax.
and indenting of JSX syntax. Try it out!

[rjsx-mode](https://github.com/felipeochoa/rjsx-mode/) is an
alternative option which comes with certain tradeoffs.
Until [#527](https://github.com/mooz/js2-mode/issues/527) is
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't really mind either way, but... should this go into the wiki instead?

This section is getting a bit long, and it's not like all of our users need to read all this.

Also: if #527 is resolved, we'll probably rewrite the whole recommendation, including the use of the minor mode.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Less is more. I’ve removed my changes here.

addressed, linting of JSX code is likely to fail. If that bothers you,
you may elect to disable linting:

```lisp
(setq js2-mode-show-parse-errors nil)
(setq js2-mode-show-strict-warnings nil)
```

In lieu of linting,
[Flycheck](https://www.flycheck.org/)+[ESLint](https://eslint.org/) is
an alternative.

Emacs 27 aside, [rjsx-mode](https://github.com/felipeochoa/rjsx-mode/)
is an alternative option which comes with certain tradeoffs.

Bugs
====
Expand Down
29 changes: 18 additions & 11 deletions js2-mode.el
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -51,21 +51,18 @@

;; (add-to-list 'auto-mode-alist '("\\.js\\'" . js2-mode))

;; Alternatively, to install it as a minor mode just for JavaScript linting,
;; you must add it to the appropriate major-mode hook. Normally this would be:
;; Alternatively, you can install it as a minor mode just for JavaScript linting
;; and/or to use packages that integrate with it. (Also, in Emacs 27, the new
;; JSX features added in that release are only accessible within this minor
;; mode. Linting of JSX code is also likely to fail.) To install it as a minor
;; mode:

;; (add-hook 'js-mode-hook 'js2-minor-mode)

;; You may also want to hook it in for shell scripts running via node.js:

;; (add-to-list 'interpreter-mode-alist '("node" . js2-mode))

;; Support for JSX is available via the derived mode `js2-jsx-mode'. If you
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Can we really remove this part, keeping in mind that pre-Emacs 27 it is the way to go?

Thinking more about it, maybe that's also the section that the Emacs 27 JSX instructions should go to instead. The "install it as a minor mode" section above gets too bloated with that extra info. Here, though, you can enumerate the cases. Use Emacs 27? Minor mode is the way to go (a note about linting problems would also be more relevant here). Use Emacs 26 or earlier? Do the stuff below.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yeah. The organization and wording needed more massaging. I made this change.

;; also want JSX support, use that mode instead:

;; (add-to-list 'auto-mode-alist '("\\.jsx?\\'" . js2-jsx-mode))
;; (add-to-list 'interpreter-mode-alist '("node" . js2-jsx-mode))

;; To customize how it works:
;; M-x customize-group RET js2-mode RET

Expand Down Expand Up @@ -11762,18 +11759,28 @@ Selecting an error will jump it to the corresponding source-buffer error.
;; Schedule parsing for after when the mode hooks run.
(js2-mode-reset-timer)))

;; We may eventually want js2-jsx-mode to derive from js-jsx-mode, but that'd be
;; a bit more complicated and it doesn't net us much yet.
;;;###autoload
(define-derived-mode js2-jsx-mode js2-mode "JSX-IDE"
"Major mode for editing JSX code.
"Major mode for editing JSX code in Emacs 26 and earlier.

To edit JSX code in Emacs 27, use `js-mode' as your major mode
with `js2-minor-mode' enabled.

To customize the indentation for this mode, set the SGML offset
variables (`sgml-basic-offset' et al) locally, like so:

(defun set-jsx-indentation ()
(setq-local sgml-basic-offset js2-basic-offset))
(add-hook \\='js2-jsx-mode-hook #\\='set-jsx-indentation)"
(unless (version< emacs-version "27.0")
;; Emacs 27 causes a regression in this mode since JSX indentation
;; begins to rely on js-mode’s `syntax-propertize-function', which
;; JS2 is not currently using.
;; https://github.com/mooz/js2-mode/issues/529 should address
;; this. https://github.com/mooz/js2-mode/issues/530 also has a
;; piece related to the design of `js2-jsx-mode'. Until these
;; issues are addressed, ward Emacs 27 users away from this mode.
(display-warning 'js2-mode "For JSX support, use js-mode with js2-minor-mode"))
jacksonrayhamilton marked this conversation as resolved.
Show resolved Hide resolved
(set (make-local-variable 'indent-line-function) #'js2-jsx-indent-line))

(defun js2-mode-exit ()
Expand Down