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
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
Comma-separated list of global TypeScript plugins to load.tsserver --globalPlugins typescript-plugin-css-modules
Comma-separated list of additional locations to probe for plugins.tsserver --pluginProbeLocations ./plugins
Allow loading plugins from local node_modules.tsserver --allowLocalPluginLoads
Project Options
--useSingleInferredProject
Use a single inferred project for all files.tsserver --useSingleInferredProject
--useInferredProjectPerProjectRoot
Use an inferred project per project root.tsserver --useInferredProjectPerProjectRoot
Diagnostic Options
--suppressDiagnosticEvents
Suppress diagnostic events from being sent to the client.tsserver --suppressDiagnosticEvents
--noGetErrOnBackgroundUpdate
Don’t send getErr events on background updates.tsserver --noGetErrOnBackgroundUpdate
Watch Options
Enable file system watcher events.tsserver --canUseWatchEvents
Logging Options
Path to log file for debugging.tsserver --logFile /tmp/tsserver.log
Set logging verbosity level.Valid values: terse, normal, verbosetsserver --logVerbosity verbose
Protocol Overview
tsserver uses a JSON-based request/response protocol over stdin/stdout.
{
"seq": 1,
"type": "request",
"command": "open",
"arguments": {
"file": "/path/to/file.ts",
"fileContent": "const x: number = 42;"
}
}
{
"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
}
}
{
"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
}
}
{
"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)
Syntactic Mode
Partial Semantic Mode
Full language service with type checking and all features. Faster mode with only syntactic features (no type checking).tsserver --serverMode syntactic
Hybrid mode with partial type checking.tsserver --serverMode partialSemantic
Configuration via tsconfig.json
tsserver respects compiler options and plugin configuration from 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:
{
"typescript.tsserver.log": "verbose",
"typescript.tsserver.trace": "messages",
"typescript.tsserver.pluginPaths": ["./plugins"]
}
Vim with coc.nvim
{
"tsserver.enable": true,
"tsserver.log": "verbose",
"tsserver.pluginRoot": "./plugins"
}
Neovim with nvim-lspconfig
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
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
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 usageCheck for circular dependencies or very large union types. Enable logging to diagnose.
Stale completionsEnsure the editor is sending change events when files are modified.
Plugin not loadingVerify plugin path and use --allowLocalPluginLoads if loading from node_modules.
Source Code Reference
The TypeScript language server implementation:
The tsserver binary (bin/tsserver) is a wrapper that loads the compiled server from lib/tsserver.js.
