This page documents the communication protocol used by tsserver — the JSON-based message format, the full set of protocol commands, and how the Session class receives, dispatches, and responds to client messages. For background on how tsserver manages TypeScript projects and the language service lifecycle, see the Project Management page. For how tsserver is initialized and fits into the overall architecture, see Language Server (tsserver).
tsserver communicates with editor clients using a line-delimited JSON protocol over stdin/stdout. Each message is a self-contained JSON object. There are three message kinds:
| Kind | Direction | Purpose |
|---|---|---|
request | Client → Server | Ask the server to perform an operation |
response | Server → Client | Reply to a specific request (success or failure) |
event | Server → Client | Unsolicited notification (e.g., diagnostics ready) |
All message definitions live in src/server/protocol.ts and are re-exported through the ts.server.protocol namespace, visible in tests/baselines/reference/api/typescript.d.ts17-18
By default, messages are newline-terminated JSON objects. The Session class in src/server/session.ts also supports a Content-Length framing mode (similar to LSP) when constructed with useServerMode: true.
Newline-delimited mode (default):
{"seq":1,"type":"request","command":"open","arguments":{...}}\n
{"seq":1,"type":"response","request_seq":1,"success":true,"command":"open","body":{}}\n
Content-Length framing mode:
Content-Length: 72\r\n
\r\n
{"seq":1,"type":"request","command":"open","arguments":{...}}
The base Message interface and its three subtypes form the protocol's type hierarchy.
Protocol message type hierarchy
Sources: src/server/protocol.ts1-50 tests/baselines/reference/api/typescript.d.ts127-200
All commands are enumerated in CommandTypes in src/server/protocol.ts and reflected in tests/baselines/reference/api/typescript.d.ts49-126 Each value is a string literal that appears in the command field of a Request or Response message.
Command reference by category
| Category | Commands |
|---|---|
| File management | open, close, change, reload, saveto, updateOpen |
| Diagnostics | geterr, geterrForProject, semanticDiagnosticsSync, syntacticDiagnosticsSync, suggestionDiagnosticsSync |
| Navigation | definition, definitionAndBoundSpan, typeDefinition, implementation, findSourceDefinition, references, fileReferences |
| Completions | completionInfo, completions (deprecated), completionEntryDetails |
| Hover / Info | quickinfo, signatureHelp |
| Code fixes | getCodeFixes, getCombinedCodeFix, applyCodeActionCommand, getSupportedCodeFixes |
| Refactoring | getApplicableRefactors, getEditsForRefactor, getMoveToRefactoringFileSuggestions |
| Formatting | format, formatonkey |
| Rename / Search | rename, navto, documentHighlights |
| Navigation bar | navbar, navtree, navtree-full |
| Organize imports | organizeImports, getEditsForFileRename |
| Inlay hints | provideInlayHints |
| Call hierarchy | prepareCallHierarchy, provideCallHierarchyIncomingCalls, provideCallHierarchyOutgoingCalls |
| Project / config | projectInfo, configure, compilerOptionsForInferredProjects, reloadProjects, status |
| Plugins | configurePlugin |
| Misc | brace, braceCompletion, selectionRange, getOutliningSpans, todoComments, indentation, docCommentTemplate, jsxClosingTag, mapCode |
Sources: tests/baselines/reference/api/typescript.d.ts49-126 src/server/protocol.ts1-200
The Session class in src/server/session.ts is the central component of tsserver. It:
Request object.command.ProjectService and its associated LanguageService.Response or Event back to the output stream.Session dispatch flow
Sources: src/server/session.ts1-100 src/server/editorServices.ts1-50
openNotifies the server that a file is now open in the editor. The server registers the file with the appropriate Project and begins tracking changes.
Request arguments:
No response body is sent; the server sends success: true.
changeApplies an incremental text edit to an open file.
Request arguments:
Positions are 1-based line/offset in the tsserver protocol (unlike 0-based positions used internally by the compiler). The Session class converts these before calling language service APIs.
geterr and Diagnostic EventsDiagnostics are asynchronous in tsserver. A client sends a geterr request listing files to check; the server enqueues analysis and later sends event messages of type semanticDiag, syntacticDiag, and suggestionDiag as analysis completes.
Diagnostic flow (sequence)
Sources: src/server/session.ts1-100 src/server/editorServices.ts202-210
completionInfoReturns completion candidates at a given position.
Request arguments:
The response body is a CompletionInfo object containing an array of CompletionEntry items. The Session handler calls LanguageService.getCompletionsAtPosition() and converts the result to protocol types.
definitionReturns the definition location(s) for the symbol at the given position.
Request arguments:
Response body is an array of FileSpan objects ({ file, start, end }).
referencesReturns all references to the symbol at the given position.
Response body is a ReferencesResponseBody containing an array of ReferencesResponseItem objects, each including file, start, end, lineText, and isWriteAccess.
configureSends client-side preferences to the server. Common uses include setting formatOptions, preferences (e.g., includePackageJsonAutoImports), and watchOptions.
The protocol uses 1-based line and offset (column) for all positions, represented as { line: number, offset: number }. Internally, the compiler uses 0-based character offsets. The Session class performs this conversion using computeLineAndCharacterOfPosition from src/compiler/utilities.ts when building responses and computePositionOfLineAndCharacter when processing requests.
| Coordinate space | Example |
|---|---|
| Protocol (1-based) | { line: 5, offset: 10 } |
| Compiler internal (0-based) | position = 45 |
The Session class bridges the protocol types defined in src/server/protocol.ts and the language service types in src/services/types.ts and src/services/services.ts Each handler function performs this translation.
Mapping: protocol commands → language service methods
Sources: src/server/session.ts1-220 src/services/services.ts1-50 src/server/editorServices.ts1-200
Beyond responses to requests, tsserver sends unsolicited event messages to the client:
| Event name | Trigger | Body type |
|---|---|---|
semanticDiag | Background semantic analysis complete | DiagnosticEventBody |
syntacticDiag | Syntactic analysis complete | DiagnosticEventBody |
suggestionDiag | Suggestion analysis complete | DiagnosticEventBody |
projectsUpdatedInBackground | Background project refresh | ProjectsUpdatedInBackgroundEventBody |
projectLoadingStart | Project load begins | ProjectLoadingStartEventBody |
projectLoadingFinish | Project load ends | ProjectLoadingFinishEventBody |
configFileDiag | Error in tsconfig.json | ConfigFileDiagEventBody |
projectLanguageServiceState | Language service disabled/enabled | ProjectLanguageServiceStateEventBody |
largeFileReferenced | File exceeds size limit | LargeFileReferencedEventBody |
telemetry | Telemetry data | TelemetryEventBody |
Event name constants like ProjectsUpdatedInBackgroundEvent and ConfigFileDiagEvent are defined as string constants in src/server/editorServices.ts202-210
The protocol types in src/server/protocol.ts are part of the public API surface of TypeScript. Changes to them trigger a bot-driven review process (see Pull Request Process). The ts.server.protocol namespace re-exports these types in the public typescript package, as seen in tests/baselines/reference/api/typescript.d.ts17-126
Many protocol types directly re-export language service types:
protocol.UserPreferences → ts.UserPreferencesprotocol.SignatureHelpParameter → ts.SignatureHelpParameterprotocol.SymbolDisplayPart → ts.SymbolDisplayPartprotocol.ApplicableRefactorInfo → ts.ApplicableRefactorInfotests/baselines/reference/api/typescript.d.ts19-37
Full component relationship
Sources: src/server/session.ts src/server/protocol.ts src/server/editorServices.ts src/server/project.ts src/server/scriptInfo.ts
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.