Skip to content
Tutorials Center
My learning

Topics

TypeScript Reference ยท The tsc Command Line

tsserver and the TypeScript language service

How editors talk to TypeScript: what tsserver is, the JSON message protocol, the commands behind hover, completion and errors, and how to read its logs.

tsserver is the long-running process that powers TypeScript in your editor. Instead of starting the compiler for every keystroke, an editor starts tsserver once, sends it the files you have open, and asks questions: what is the type under the cursor, what completions fit here, where is this symbol defined, which errors does this file have. The server keeps the whole program in memory and updates it incrementally, which is why hover and completion feel instant.

The same engine is exposed to programs as the language service API. Editors such as VS Code talk to tsserver over standard input and output with a small JSON protocol, so any tool can do the same. With TypeScript 7 the native compiler ships its own language server that speaks the Language Server Protocol, but the concepts below (open files, a project per tsconfig.json, request and response messages) are the same.

TEXT
tsc --version
node node_modules/typescript/lib/tsserver.js --logVerbosity verbose --logFile ts.log

Try it

The site cannot start a language server, so these examples are small stand-ins that show the shape of the protocol: requests carry a sequence number and a command, responses point back at the request they answer.

TypeScript Building protocol requests

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

TypeScript Reading framed responses

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or readFileSync(0)), it gets the next line from this box.

Syntax

This is a concept page. A session looks like this:

  1. Start. The editor spawns tsserver with Node and talks over stdin and stdout. Each request is one line of JSON; each response is a block with a Content-Length header followed by JSON.
  2. Open files. open tells the server a file is being edited. The server finds the nearest tsconfig.json and creates (or reuses) a project for it. Files that no config includes go into an inferred project.
  3. Change. change (or updateOpen) sends edits so the server never has to re-read the disk for open files.
  4. Ask. Common commands are in the table below.
  5. Events. The server also pushes events without being asked, for example syntaxDiag and semanticDiag after you call geterr.
Command Purpose
open, close, change Tell the server which files are being edited.
quickinfo Type and documentation shown on hover.
completionInfo Completion list at a position.
definition, references, rename Navigation and refactoring.
semanticDiagnosticsSync, syntacticDiagnosticsSync Errors for one file, returned directly.
geterr Ask for diagnostics of several files; results arrive as events.
configure Set preferences such as import-module specifier style.

Positions: line and offset are both 1-based, unlike the 0-based positions in most APIs.

Usage notes

  • Editor and tsc can disagree. The editor uses the TypeScript version it bundles or the workspace one you select; tsc uses the one in node_modules. In VS Code, pick "Select TypeScript Version" if errors differ.
  • Restart when confused. After changing tsconfig.json or installing types, "Restart TS Server" clears stale state. It is the first thing to try when the editor shows an error tsc does not.
  • Logs. Start the server with --logVerbosity verbose --logFile <path> (VS Code: the typescript.tsserver.log setting) to see every request and how long it took.
  • Memory and speed. One huge project means one huge in-memory program. Project references split the work so an editor only loads the projects it needs.
  • Plugins. Language service plugins listed under compilerOptions.plugins wrap the service (for example to add checks for template strings). They affect the editor only, never tsc.
  • Not a build tool. tsserver does not emit files by default; use tsc or a bundler for output.