spacemacs/layers/+lang/typescript/README.org

#+TITLE: TypeScript layer

[[file:img/TypeScript.png]]

* Table of Contents                                         :TOC_4_gh:noexport:
- [[#description][Description]]
  - [[#features][Features:]]
- [[#install][Install]]
  - [[#pre-requisites][Pre-requisites]]
  - [[#choosing-a-backend][Choosing a backend]]
- [[#backends][Backends]]
  - [[#tide][Tide]]
    - [[#notes][Notes]]
  - [[#language-server-protocol][Language Server Protocol]]
- [[#key-bindings][Key bindings]]
  - [[#typescript-major-mode][Typescript Major Mode]]
  - [[#reference-major-mode][Reference Major Mode]]

* Description
This layer adds support for TypeScript and TSX editing.

** Features:
- Multiple backends support: Tide and LSP
- Eldoc-mode
- Documentation at point
- Auto complete
- Flycheck with linter
- Jump to definition, Jump to type definition
- Find occurrences (Imenu-mode)
- Rename symbol
- tsx mode
- formatting
- TypeScript playground integration

* Install
To use this configuration layer, add it to your =~/.spacemacs=. You will need to
add =typescript= to the existing =dotspacemacs-configuration-layers= list in this
file.

#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(typescript))
#+END_SRC

If you need formatting on save:

#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(
  (typescript :variables
              typescript-fmt-on-save t)))
#+END_SRC

You can choose formatting tool:

#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(
  (typescript :variables
              typescript-fmt-tool 'typescript-formatter)))
#+END_SRC

Default is 'tide .

** Pre-requisites
You will need =node.js v0.12.0= or greater.

If you want linting run:

#+BEGIN_SRC shell
npm install -g typescript tslint
#+END_SRC

If you want to use typescript-formatter for formatting run:

#+BEGIN_SRC shell
npm install -g typescript-formatter
#+END_SRC

For best results, make sure that the =auto-completion= (company) and =html=
layers are enabled.

** Choosing a backend
To choose a default backend set the layer variable =typescript-backend=:

#+BEGIN_SRC elisp
(setq-default dotspacemacs-configuration-layers '(
  (typescript :variables typescript-backend 'tide)))
#+END_SRC

Backend can be chosen on a per project basis using directory local variables
(files named =.dir-locals.el= at the root of a project), an example to use the
=lsp= backend:

#+BEGIN_SRC elisp
;;; Directory Local Variables
;;; For more information see (info "(emacs) Directory Variables")

((typescript-mode (typescript-backend . lsp)))
#+END_SRC

*Note:* you can easily add a directory local variable with ~SPC f v d~.

* Backends
** Tide
Tide comes with an embedded Typescript server, it is recommended to use the
server intalled by =npm= instead. To do so set the variable
=tide-tsserver-executable= to the path of the =tsserver= executable.

For example:

#+BEGIN_SRC emacs-lisp
(setq-default dotspacemacs-configuration-layers '(
  (typescript :variables
              tide-tsserver-executable "/usr/local/bin/tsserver")))
#+END_SRC

*** Notes
Make sure to add [[https://github.com/Microsoft/TypeScript/wiki/tsconfig.json][tsconfig.json]] in the project root folder.

tsserver mangles output sometimes [[https://github.com/Microsoft/TypeScript/issues/2758][issue - #2758]], which will result in json parse
error. Try node version 0.12.x if you get this error.

Send to playground requires browser.

Currently tsserver doesn't pickup tsconfig.json file changes. You might need to
restart server after editing it.

** Language Server Protocol
You have to install the following dependencies with npm.

#+BEGIN_SRC shell
npm i -g typescript typescript-language-server
#+END_SRC

* Key bindings
** Typescript Major Mode

| Key Binding | Description                                                  |
|-------------+--------------------------------------------------------------|
| ~SPC m =~   | reformat the buffer                                          |
| ~SPC m g b~ | jump back                                                    |
| ~SPC m g g~ | jump to entity's definition                                  |
| ~SPC m g t~ | jump to entity's type definition                             |
| ~SPC m g u~ | references                                                   |
| ~SPC m h h~ | documentation at point                                       |
| ~SPC m r r~ | rename symbol                                                |
| ~SPC m s p~ | send selected region or current buffer to the web playground |
| ~SPC m s r~ | restart server                                               |

** Reference Major Mode

| Key Binding | Description             |
|-------------+-------------------------|
| ~C-j~       | find previous reference |
| ~C-k~       | find next reference     |
| ~C-l~       | goto reference          |