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.
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.
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.
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:
- Start. The editor spawns
tsserverwith Node and talks over stdin and stdout. Each request is one line of JSON; each response is a block with aContent-Lengthheader followed by JSON. - Open files.
opentells the server a file is being edited. The server finds the nearesttsconfig.jsonand creates (or reuses) a project for it. Files that no config includes go into an inferred project. - Change.
change(orupdateOpen) sends edits so the server never has to re-read the disk for open files. - Ask. Common commands are in the table below.
- Events. The server also pushes events without being asked, for example
syntaxDiagandsemanticDiagafter you callgeterr.
| 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
tsccan disagree. The editor uses the TypeScript version it bundles or the workspace one you select;tscuses the one innode_modules. In VS Code, pick "Select TypeScript Version" if errors differ. - Restart when confused. After changing
tsconfig.jsonor installing types, "Restart TS Server" clears stale state. It is the first thing to try when the editor shows an errortscdoes not. - Logs. Start the server with
--logVerbosity verbose --logFile <path>(VS Code: thetypescript.tsserver.logsetting) 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.pluginswrap the service (for example to add checks for template strings). They affect the editor only, nevertsc. - Not a build tool.
tsserverdoes not emit files by default; usetscor a bundler for output.