typescript-tools.nvim

^{⚡ TypeScript integration NeoVim deserves ⚡}

🚧 Warning 🚧

Please note that the plugin is currently in the early beta version, which means you may encounter bugs.

⁉️ Why?

1. Drop in, pure lua replacement for typescript-language-server
2. If you work on a large TS/JS project, you probably understand why this plugin came into existence. The typescript-language-server can be extremely slow in such projects, and it often fails to provide accurate completions or just crash.

✨ Features

• ⚡ Blazingly fast, thanks to the utilization of the native Tsserver communication protocol, similar to Visual Studio Code
• 🪭 Supports a wide range of TypeScript versions 4.0 and above
• 🌍 Supports the nvim LSP plugin ecosystem
• 🔀 Supports multiple instances of Tsserver
• 💻 Supports both local and global installations of TypeScript
• 🔨 Supports tsserver installed from Mason
• 💅 Provides out-of-the-box support for styled-components, which is not enabled by default (see Installation and Configuration)
• ✨ Improved code refactor capabilities e.g. extracting to variable or function

🚀 How it works?

 NeoVim                                                    Tsserver Instance
┌────────────────────────────────────────────┐            ┌────────────────┐
│                                            │            │                │
│  LSP Handlers          Tsserver LSP Loop   │            │                │
│ ┌─────────┐           ┌──────────────────┐ │            │                │
│ │         │           │                  │ │            │                │
│ │         │ Request   │ ┌──────────────┐ │ │            │                │
│ │         ├───────────┤►│ Translation  │ │ │            │                │
│ │         │ Response  │ │    Layer     │ │ │            │                │
│ │         ◄───────────┼─┤              │ │ │            │                │
│ │         │           │ └───┬─────▲────┘ │ │            │                │
│ │         │           │     │     │      │ │            │                │
│ │         │           │ ┌───▼─────┴────┐ │ │ Request    │                │
│ │         │           │ │   I/O Loop   ├─┼─┼────────────►                │
│ │         │           │ │              │ │ │ Response   │                │
│ │         │           │ │              ◄─┼─┼────────────┤                │
│ │         │           │ └──────────────┘ │ │            │                │
│ │         │           │                  │ │            │                │
│ └─────────┘           └──────────────────┘ │            │                │
│                                            │            │                │
└────────────────────────────────────────────┘            └────────────────┘

📦 Installation

❗️ IMPORTANT: As mentioned earlier, this plugin serves as a replacement for typescript-language-server, so you should remove the nvim-lspconfig setup for it.

⚡️ Requirements

• NeoVim >= 0.11.0
• plenary.nvim
• TypeScript >= 4.0
• Node supported suitable for TypeScript version you use

lazy.nvim

{
  "pmizio/typescript-tools.nvim",
  dependencies = { "nvim-lua/plenary.nvim", "neovim/nvim-lspconfig" },
  opts = {},
}

packer.nvim

use {
  "pmizio/typescript-tools.nvim",
  requires = { "nvim-lua/plenary.nvim" },
  config = function()
    require("typescript-tools").setup {}
  end,
}

⚙️ Configuration

require("typescript-tools").setup {
  on_attach = function() ... end,
  handlers = { ... },
  ...
  settings = {
    -- spawn additional tsserver instance to calculate diagnostics on it
    separate_diagnostic_server = true,
    -- "change"|"insert_leave" determine when the client asks the server about diagnostic
    publish_diagnostic_on = "insert_leave",
    -- array of strings("fix_all"|"add_missing_imports"|"remove_unused"|
    -- "remove_unused_imports"|"organize_imports") -- or string "all"
    -- to include all supported code actions
    -- specify commands exposed as code_actions
    expose_as_code_action = {},
    -- string|nil - specify a custom path to `tsserver.js` file, if this is nil or file under path
    -- not exists then standard path resolution strategy is applied
    tsserver_path = nil,
    -- specify a list of plugins to load by tsserver, e.g., for support `styled-components`
    -- (see 💅 `styled-components` support section)
    tsserver_plugins = {},
    -- this value is passed to: https://nodejs.org/api/cli.html#--max-old-space-sizesize-in-megabytes
    -- memory limit in megabytes or "auto"(basically no limit)
    tsserver_max_memory = "auto",
    -- described below
    tsserver_format_options = {},
    tsserver_file_preferences = {},
    -- locale of all tsserver messages, supported locales you can find here:
    -- https://github.com/microsoft/TypeScript/blob/3c221fc086be52b19801f6e8d82596d04607ede6/src/compiler/utilitiesPublic.ts#L620
    tsserver_locale = "en",
    -- mirror of VSCode's `typescript.suggest.completeFunctionCalls`
    complete_function_calls = false,
    include_completions_with_insert_text = true,
    -- CodeLens
    -- WARNING: Experimental feature also in VSCode, because it might hit performance of server.
    -- possible values: ("off"|"all"|"implementations_only"|"references_only")
    code_lens = "off",
    -- by default code lenses are displayed on all referencable values and for some of you it can
    -- be too much this option reduce count of them by removing member references from lenses
    disable_member_code_lens = true,
    -- JSXCloseTag
    -- WARNING: it is disabled by default (maybe you configuration or distro already uses nvim-ts-autotag,
    -- that maybe have a conflict if enable this feature. )
    jsx_close_tag = {
        enable = false,
        filetypes = { "javascriptreact", "typescriptreact" },
    }
  },
}

Note that handlers can be used to override certain LSP methods. For example, you can use the filter_diagnostics helper to ignore specific errors:

local api = require("typescript-tools.api")
require("typescript-tools").setup {
  handlers = {
    ["textDocument/publishDiagnostics"] = api.filter_diagnostics(
      -- Ignore 'This may be converted to an async function' diagnostics.
      { 80006 }
    ),
  },
}

You can also pass custom configuration options that will be passed to tsserver instance. You can find available options in typescript repository (e.g. for version 5.0.4 of typescript):

• tsserver_file_preferences
• tsserver_format_options

To pass those options to plugin pass them to the plugin setup function:

require("typescript-tools").setup {
  settings = {
    ...
    tsserver_file_preferences = {
      includeInlayParameterNameHints = "all",
      includeCompletionsForModuleExports = true,
      quotePreference = "auto",
      ...
    },
    tsserver_format_options = {
      allowIncompleteCompletions = false,
      allowRenameOfImportPath = false,
      ...
    }
  },
}

If you want to make tsserver_format_options or tsserver_file_preferences filetype dependant you need to may set them as functions returning tables eg.

require("typescript-tools").setup {
  settings = {
    ...
    tsserver_file_preferences = function(ft)
      -- Some "ifology" using `ft` of opened file
      return {
        includeInlayParameterNameHints = "all",
        includeCompletionsForModuleExports = true,
        quotePreference = "auto",
        ...
      }
    end,
    tsserver_format_options = function(ft)
      -- Some "ifology" using `ft` of opened file
      return {
        allowIncompleteCompletions = false,
        allowRenameOfImportPath = false,
        ...
      }
    end
  },
}

The default values for preferences and format_options are in this file

💅 styled-components support

npm i -g @styled/typescript-styled-plugin typescript-styled-plugin

require("typescript-tools").setup {
  settings = {
    ...
    tsserver_plugins = {
      -- for TypeScript v4.9+
      "@styled/typescript-styled-plugin",
      -- or for older TypeScript versions
      -- "typescript-styled-plugin",
    },
  },
}

Custom user commands

This plugin provides several custom user commands (they are only applied to current buffer):

• TSToolsOrganizeImports - sorts and removes unused imports
• TSToolsSortImports - sorts imports
• TSToolsRemoveUnusedImports - removes unused imports
• TSToolsRemoveUnused - removes all unused statements
• TSToolsAddMissingImports - adds imports for all statements that lack one and can be imported
• TSToolsFixAll - fixes all fixable errors
• TSToolsGoToSourceDefinition - goes to source definition (available since TS v4.7)
• TSToolsRenameFile - allow to rename current file and apply changes to connected files
• TSToolsFileReferences - find files that reference the current file (available since TS v4.2)

Supported LSP methods

🚦 Roadmap

• textDocument/linkedEditingRange - #32
• Embedded language support(JS inside of HTML) - #43

🔨 Development

Useful links:

• nvim-lua-guide
• plenary.nvim

🐛 Run tests

The unit testing environment is automatically bootstrapped, just run:

make test

Or if you want to run a single test file:

make file=test_spec.lua test

💐 Credits

• null-ls.nvim - for the idea to monkeypatch nvim API to start a custom LSP I/O loop
• typescript-language-server - for ideas on how to translate certain Tsserver responses
• Visual Studio Code(TypeScript extension) - for insights on using the Tsserver protocol and performance optimizations