Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/ananthakumaran/tide

Tide - TypeScript Interactive Development Environment for Emacs
https://github.com/ananthakumaran/tide

emacs typescript

Last synced: 30 days ago
JSON representation

Tide - TypeScript Interactive Development Environment for Emacs

Awesome Lists containing this project

README 

        
# Tide



![Build Status](https://github.com/ananthakumaran/tide/workflows/CI/badge.svg)



*TypeScript Interactive Development Environment for Emacs*



[screencast](http://i.imgur.com/jEwgPsd.gif)



### Installation



* Tide requires Emacs 25 or later. We recommend Emacs 27 or later with native json support.

* Install [node.js](https://nodejs.org/) v0.14.0 or greater.

* Make sure

  [tsconfig.json](http://www.typescriptlang.org/docs/handbook/tsconfig-json.html)

  or

  [jsconfig.json](https://code.visualstudio.com/docs/languages/jsconfig)

  is present in the root folder of the project.

* Tide is available in [melpa](http://melpa.org/#/tide). You can

  install tide via package-install M-x package-install [ret] tide



### Configuration



#### TypeScript

```elisp

(defun setup-tide-mode ()

  (interactive)

  (tide-setup)

  (flycheck-mode +1)

  (setq flycheck-check-syntax-automatically '(save mode-enabled))

  (eldoc-mode +1)

  (tide-hl-identifier-mode +1)

  ;; company is an optional dependency. You have to

  ;; install it separately via package-install

  ;; `M-x package-install [ret] company`

  (company-mode +1))



;; aligns annotation to the right hand side

(setq company-tooltip-align-annotations t)



;; formats the buffer before saving

(add-hook 'before-save-hook 'tide-format-before-save)



;; if you use typescript-mode

(add-hook 'typescript-mode-hook #'setup-tide-mode)

;; if you use treesitter based typescript-ts-mode (emacs 29+)

(add-hook 'typescript-ts-mode-hook #'setup-tide-mode)

```



#### Format options



Format options can be specified in multiple ways.



* via elisp



```elisp

(setq tide-format-options '(:insertSpaceAfterFunctionKeywordForAnonymousFunctions t :placeOpenBraceOnNewLineForFunctions nil))

```



* via tsfmt.json (should be present in the root folder along with tsconfig.json)

```json

{

  "indentSize": 4,

  "tabSize": 4,

  "insertSpaceAfterOpeningAndBeforeClosingTemplateStringBraces": false,

  "placeOpenBraceOnNewLineForFunctions": false,

  "placeOpenBraceOnNewLineForControlBlocks": false

}

```

Check [here][format_options] for the full list of supported format options.



#### TSX without treesitter

```elisp

(require 'web-mode)

(add-to-list 'auto-mode-alist '("\\.tsx\\'" . web-mode))

(add-hook 'web-mode-hook

          (lambda ()

            (when (string-equal "tsx" (file-name-extension buffer-file-name))

              (setup-tide-mode))))

;; enable typescript-tslint checker

(flycheck-add-mode 'typescript-tslint 'web-mode)

```

#### TSX with treesitter

Treesitter comes with tsx major mode built in.

```elisp

(add-hook 'tsx-ts-mode-hook #'setup-tide-mode)

```



Tide also provides support for editing js & jsx files. Tide checkers

`javascript-tide` and `jsx-tide` are not enabled by default for js &

jsx files. It can be enabled by setting [`flycheck-checker`](http://www.flycheck.org/en/latest/user/syntax-checkers.html#variable-flycheck-checker)



#### JavaScript



Create `jsconfig.json` in the root folder of your project.

`jsconfig.json` is `tsconfig.json` with `allowJs` attribute set to

true.



```json

{

  "compilerOptions": {

    "target": "es2017",

    "allowSyntheticDefaultImports": true,

    "noEmit": true,

    "checkJs": true,

    "jsx": "react",

    "lib": [ "dom", "es2017" ]

  }

}

```



```elisp

(add-hook 'js2-mode-hook #'setup-tide-mode)

;; configure javascript-tide checker to run after your default javascript checker

(flycheck-add-next-checker 'javascript-eslint 'javascript-tide 'append)

```



#### JSX

```elisp

(require 'web-mode)

(add-to-list 'auto-mode-alist '("\\.jsx\\'" . web-mode))

(add-hook 'web-mode-hook

          (lambda ()

            (when (string-equal "jsx" (file-name-extension buffer-file-name))

              (setup-tide-mode))))

;; configure jsx-tide checker to run after your default jsx checker

(flycheck-add-mode 'javascript-eslint 'web-mode)

(flycheck-add-next-checker 'javascript-eslint 'jsx-tide 'append)

```



#### Use Package

```elisp

;; if you use typescript-mode

(use-package tide

  :ensure t

  :after (typescript-mode company flycheck)

  :hook ((typescript-mode . tide-setup)

         (typescript-mode . tide-hl-identifier-mode)

         (before-save . tide-format-before-save)))

         

;; if you use treesitter based typescript-ts-mode (emacs 29+)

(use-package tide

  :ensure t

  :after (company flycheck)

  :hook ((typescript-ts-mode . tide-setup)

         (tsx-ts-mode . tide-setup)

         (typescript-ts-mode . tide-hl-identifier-mode)

         (before-save . tide-format-before-save)))

```



### Commands



Keyboard shortcuts                  | Description

------------------------------------|----------

M-.                      | Jump to the definition of the symbol at point. With a prefix arg, Jump to the type definition.

M-,                      | Return to your pre-jump position.



M-x tide-restart-server Restart tsserver. This would come

in handy after you edit tsconfig.json or checkout a different branch.



M-x tide-documentation-at-point Load the documentation for the

symbol at point to buffer `*tide-documentation*`.



M-x tide-references List all references to the symbol

at point in a buffer. References can be navigated using n

and p. Press enter to open the file.



M-x tide-project-errors List all errors in the

project. Errors can be navigated using n and

p. Press enter to open the file.



M-x tide-error-at-point Load the details of the error at point

to buffer `*tide-error*`.



M-x tide-rename-symbol Rename all occurrences of the symbol

at point.



M-x tide-rename-file Rename current file and all it's

references in other files.



M-x tide-format Format the current region or buffer.



M-x tide-fix Apply code fix for the error at point. When

invoked with a prefix arg, apply code fix for all the errors in the file

that are similar to the error at point.



M-x tide-add-tslint-disable-next-line If the point is on

one or more tslint errors, add a `tslint:disable-next-line` flag on

the previous line to silence the errors. Or, if a flag already exists

on the previous line, modify the flag to silence the errors.



M-x tide-refactor Refactor code at point or current region.



M-x tide-jsdoc-template Insert JSDoc comment template at

point.



M-x tide-verify-setup Show the version of tsserver.



M-x tide-organize-imports Organize imports in the file.



M-x tide-list-servers List the `tsserver` processes launched by

tide.



### Features



* Xref

* ElDoc

* Auto complete

* Flycheck

* Jump to definition, Jump to type definition

* Find occurrences

* Rename symbol

* Imenu

* Compile On Save

* Highlight Identifiers

* Code Fixes

* Code Refactor

* Organize Imports



### Debugging



![architecture](https://github.com/ananthakumaran/tide/raw/master/doc/architecture.mmd.png)



Tide uses

[tsserver](https://github.com/Microsoft/TypeScript/wiki/Standalone-Server-%28tsserver%29) as the

backend for most of the features. It writes out a comprehensive log

file which can be captured by setting

`tide-tsserver-process-environment` variable.



```lisp

(setq tide-tsserver-process-environment '("TSS_LOG=-level verbose -file /tmp/tss.log"))

```



[format_options]: https://github.com/Microsoft/TypeScript/blob/v3.3.1/src/server/protocol.ts#L2858-L2890



### FAQ?



**How do I configure tide to use a specific version of TypeScript compiler?**



For TypeScript 2.0 and above, you can customize the

`tide-tsserver-executable` variable. For example

```lisp

(setq tide-tsserver-executable "node_modules/typescript/bin/tsserver")

```



Sadly, this won't work for TypeScript < 2.0. You can clone the repo

locally and checkout the old version though.



**How do I copy the type information shown in the minibuffer?**



Tide has the command `tide-documentation-at-point` to load the

documentation for the symbol at point to buffer `*tide-documentation*`

from where it can be copied. By default, tide will not open this buffer

if only type information is available. This behavior can be

overridden by setting `(setq tide-always-show-documentation t)`



### Custom Variables



##### tide-sync-request-timeout `2`



The number of seconds to wait for a sync response.



##### tide-tsserver-flags `nil`



List of additional flags to provide when starting tsserver.



##### tide-tsserver-process-environment `'nil`



List of extra environment variables to use when starting tsserver.



##### tide-tsserver-executable `nil`



Name of tsserver executable to run instead of the bundled tsserver.



This may either be an absolute path or a relative path. Relative

paths are resolved against the project root directory.



Note that this option only works with TypeScript version 2.0 and

above.



##### tide-tscompiler-executable `nil`



Name of tsc executable.



This may either be an absolute path or a relative path. Relative

paths are resolved against the project root directory.



##### tide-node-executable `"node"`



Name or path of the node executable binary file.



##### tide-node-flags `nil`



List of flags to provide to node when starting tsserver.



Useful for large TypeScript codebases which need to set

max-old-space-size to a higher value.



##### tide-post-code-edit-hook `nil`



Hook run after code edits are applied in a buffer.



##### tide-sort-completions-by-kind `nil`



Whether completions should be sorted by kind.



##### tide-format-options `'nil`



Format options plist.



##### tide-user-preferences `'(:includeCompletionsForModuleExports t :includeCompletionsWithInsertText t :allowTextChangesInNewFiles t :generateReturnInDocTemplate t)`



User preference plist used on the configure request.



Check https://github.com/Microsoft/TypeScript/blob/17eaf50b/src/server/protocol.ts#L2684

for the full list of available options.



##### tide-disable-suggestions `nil`



Disable suggestions.



If set to non-nil, suggestions will not be shown in flycheck

errors and tide-project-errors buffer.



##### tide-completion-setup-company-backend `t`



Add `company-tide` to `company-backends`.



##### tide-completion-ignore-case `nil`



CASE will be ignored in completion if set to non-nil.



##### tide-completion-show-source `nil`



Completion dropdown will contain completion source if set to non-nil.



##### tide-completion-fuzzy `nil`



Allow fuzzy completion.



By default only candidates with exact prefix match are shown. If

set to non-nil, candidates with match anywhere inside the name

are shown.



##### tide-completion-detailed `nil`



Completion dropdown will contain detailed method information if set to non-nil.



##### tide-completion-enable-autoimport-suggestions `t`



Whether to include external module exports in completions.



##### tide-enable-xref `t`



Whether to enable xref integration.



##### tide-navto-item-filter `#'tide-navto-item-filter-default`



The filter for items returned by tide-nav. Defaults to class, interface, type, enum



##### tide-jump-to-definition-reuse-window `t`



Reuse existing window when jumping to definition.



##### tide-imenu-flatten `nil`



Imenu index will be flattened if set to non-nil.



##### tide-allow-popup-select `'(code-fix refactor)`



The list of commands where popup selection is allowed.



##### tide-always-show-documentation `nil`



Show the documentation window even if only type information is available.



##### tide-server-max-response-length `102400`



Maximum allowed response length from tsserver. Any response greater than this would be ignored.



##### tide-tsserver-locator-function `#'tide-tsserver-locater-npmlocal-projectile-npmglobal`



Function used by tide to locate tsserver.



##### tide-project-cleanup-delay `60`



The number of idle seconds to wait before cleaning up unused tsservers.

Use `nil` to disable automatic cleanups.  See also `tide-do-cleanups`.



##### tide-tsserver-start-method `'immediate`



The method by which tide starts tsserver. `immediate` causes tide to start a tsserver instance

as soon as `tide-mode` is turned on. `manual` means that tide will start a tsserver only when the

user manually starts one.



##### tide-default-mode `"TS"`



The default mode to open buffers not backed by files (e.g. Org

source blocks) in.



##### tide-recenter-after-jump `t`



Recenter buffer after jumping to definition



##### tide-jump-to-fallback `#'tide-jump-to-fallback-not-given`



The fallback jump function to use when implementations aren't available.



##### tide-filter-out-warning-completions `nil`



Completions whose `:kind` property is "warning" will be filtered out if set to non-nil.

This option is useful for Javascript code completion, because tsserver often returns a lot of irrelevant

completions whose `:kind` property is "warning" for Javascript code. You can fix this behavior by setting

this variable to non-nil value for Javascript buffers using `setq-local` macro.



##### tide-native-json-parsing `(and

 (>= emacs-major-version 27)

 (functionp 'json-serialize)

 (functionp 'json-parse-buffer)

 (functionp 'json-parse-string))`



Use native JSON parsing (only emacs >= 27).



##### tide-save-buffer-after-code-edit `t`



Save the buffer after applying code edits.



##### tide-hl-identifier-idle-time `0.5`



How long to wait after user input before highlighting the current identifier.