tsserver - TypeScript Language Server

Complete reference for the TypeScript language server protocol

The tsserver command starts the TypeScript language server, which provides editor services like auto-completion, type checking, and refactoring.

tsserver is typically used by editors and IDEs, not directly by developers. This documentation is for tool authors and advanced users.

Installation

npm install -g typescript

Basic Usage

tsserver

The server communicates via stdin/stdout using JSON messages.

How Editors Use tsserver

Editors like VS Code, Vim, and Sublime Text integrate with tsserver to provide:

• Auto-completion
• Type information on hover
• Error diagnostics
• Go to definition
• Find references
• Refactoring

Command-Line Options

Plugin Options

--globalPlugins · string

Comma-separated list of global TypeScript plugins to load.

tsserver --globalPlugins typescript-plugin-css-modules

--pluginProbeLocations · string

Comma-separated list of additional locations to probe for plugins.

tsserver --pluginProbeLocations ./plugins

--allowLocalPluginLoads · boolean · default: "false"

Allow loading plugins from local node_modules.

tsserver --allowLocalPluginLoads

Project Options

--useSingleInferredProject · boolean · default: "false"

Use a single inferred project for all files.

tsserver --useSingleInferredProject

--useInferredProjectPerProjectRoot · boolean · default: "false"

Use an inferred project per project root.

tsserver --useInferredProjectPerProjectRoot

Diagnostic Options

--suppressDiagnosticEvents · boolean · default: "false"

Suppress diagnostic events from being sent to the client.

tsserver --suppressDiagnosticEvents

--noGetErrOnBackgroundUpdate · boolean · default: "false"

Don’t send getErr events on background updates.

tsserver --noGetErrOnBackgroundUpdate

Watch Options

--canUseWatchEvents · boolean · default: "false"

Enable file system watcher events.

tsserver --canUseWatchEvents

Logging Options

--logFile · string

Path to log file for debugging.

tsserver --logFile /tmp/tsserver.log

--logVerbosity · string · default: "normal"

Set logging verbosity level.

Valid values: terse, normal, verbose

tsserver --logVerbosity verbose

Protocol Overview

tsserver uses a JSON-based request/response protocol over stdin/stdout.

Request Format

{
  "seq": 1,
  "type": "request",
  "command": "open",
  "arguments": {
    "file": "/path/to/file.ts",
    "fileContent": "const x: number = 42;"
  }
}

Response Format

{
  "seq": 0,
  "type": "response",
  "command": "open",
  "request_seq": 1,
  "success": true
}

Common Commands

open

Open a file for editing:

{
  "seq": 1,
  "type": "request",
  "command": "open",
  "arguments": {
    "file": "/path/to/file.ts"
  }
}

quickinfo

Get type information at a position:

{
  "seq": 2,
  "type": "request",
  "command": "quickinfo",
  "arguments": {
    "file": "/path/to/file.ts",
    "line": 1,
    "offset": 7
  }
}

Response:

{
  "seq": 0,
  "type": "response",
  "command": "quickinfo",
  "request_seq": 2,
  "success": true,
  "body": {
    "kind": "const",
    "kindModifiers": "",
    "start": { "line": 1, "offset": 7 },
    "end": { "line": 1, "offset": 8 },
    "displayString": "const x: number",
    "documentation": ""
  }
}

completions

Get auto-completion suggestions:

{
  "seq": 3,
  "type": "request",
  "command": "completions",
  "arguments": {
    "file": "/path/to/file.ts",
    "line": 2,
    "offset": 5
  }
}

Response:

{
  "seq": 0,
  "type": "response",
  "command": "completions",
  "request_seq": 3,
  "success": true,
  "body": [
    {
      "name": "toString",
      "kind": "method",
      "kindModifiers": "declare",
      "sortText": "0"
    },
    {
      "name": "toFixed",
      "kind": "method",
      "kindModifiers": "declare",
      "sortText": "0"
    }
  ]
}

definition

Go to definition:

{
  "seq": 4,
  "type": "request",
  "command": "definition",
  "arguments": {
    "file": "/path/to/file.ts",
    "line": 5,
    "offset": 10
  }
}

references

Find all references:

{
  "seq": 5,
  "type": "request",
  "command": "references",
  "arguments": {
    "file": "/path/to/file.ts",
    "line": 3,
    "offset": 15
  }
}

rename

Rename a symbol:

{
  "seq": 6,
  "type": "request",
  "command": "rename",
  "arguments": {
    "file": "/path/to/file.ts",
    "line": 1,
    "offset": 7
  }
}

geterr

Get diagnostic errors:

{
  "seq": 7,
  "type": "request",
  "command": "geterr",
  "arguments": {
    "files": ["/path/to/file.ts"],
    "delay": 0
  }
}

Event Messages

tsserver sends event messages for background operations:

semanticDiag

{
  "seq": 0,
  "type": "event",
  "event": "semanticDiag",
  "body": {
    "file": "/path/to/file.ts",
    "diagnostics": [
      {
        "start": { "line": 1, "offset": 7 },
        "end": { "line": 1, "offset": 13 },
        "text": "Type 'string' is not assignable to type 'number'.",
        "code": 2322,
        "category": "error"
      }
    ]
  }
}

projectLoadingFinish

{
  "seq": 0,
  "type": "event",
  "event": "projectLoadingFinish",
  "body": {
    "projectName": "/path/to/tsconfig.json"
  }
}

Server Modes

tsserver can run in different modes optimized for different scenarios:

Semantic Mode (Default)

Full language service with type checking and all features.

tsserver

Syntactic Mode

Faster mode with only syntactic features (no type checking).

tsserver --serverMode syntactic

Partial Semantic Mode

Hybrid mode with partial type checking.

tsserver --serverMode partialSemantic

Configuration via tsconfig.json

tsserver respects compiler options and plugin configuration from tsconfig.json:

tsconfig.json

{
  "compilerOptions": {
    "plugins": [
      {
        "name": "typescript-plugin-css-modules",
        "options": {
          "classnameTransform": "camelCase"
        }
      }
    ]
  }
}

Editor Integration Examples

VS Code

VS Code uses tsserver internally via the TypeScript extension:

settings.json

{
  "typescript.tsserver.log": "verbose",
  "typescript.tsserver.trace": "messages",
  "typescript.tsserver.pluginPaths": ["./plugins"]
}

Vim with coc.nvim

coc-settings.json

{
  "tsserver.enable": true,
  "tsserver.log": "verbose",
  "tsserver.pluginRoot": "./plugins"
}

Neovim with nvim-lspconfig

init.lua

require('lspconfig').tsserver.setup({
  init_options = {
    plugins = {
      {
        name = "typescript-plugin-css-modules",
        location = "/path/to/plugin"
      }
    }
  }
})

Debugging tsserver

Enable Logging

tsserver --logFile /tmp/tsserver.log --logVerbosity verbose

Inspect Log Output

tail -f /tmp/tsserver.log

Sample Log:

Info 0    [12:00:00.000] Starting TS Server
Info 1    [12:00:00.001] Version: 5.3.3
Info 2    [12:00:00.002] Arguments: --logFile /tmp/tsserver.log --logVerbosity verbose
Info 3    [12:00:00.003] ServerMode: undefined hasUnknownServerMode: undefined
Info 4    [12:00:00.150] Project: /path/to/project/tsconfig.json
Info 5    [12:00:00.151] Loading inferred project: /path/to/project/tsconfig.json

Performance Tuning

Use --suppressDiagnosticEvents to reduce message overhead in large projects.

Configure skipLibCheck: true in tsconfig.json to speed up type checking.

Use project references for monorepos to improve incremental checking performance.

Common Issues

High CPU usage

Check for circular dependencies or very large union types. Enable logging to diagnose.

Stale completions

Ensure the editor is sending change events when files are modified.

Plugin not loading

Verify plugin path and use --allowLocalPluginLoads if loading from node_modules.

Source Code Reference

The TypeScript language server implementation:

• Main entry point: src/tsserver/server.ts:57
• Session handler: src/server/session.ts
• Protocol definitions: src/server/protocol.ts
• Editor services: src/server/editorServices.ts

The tsserver binary (bin/tsserver) is a wrapper that loads the compiled server from lib/tsserver.js.

Related Documentation

• Compiler Options - Detailed compiler option reference
• tsc Command - TypeScript compiler CLI reference
• TypeScript Handbook - Official TypeScript documentation