Language Server (tsserver)

Relevant source files

• src/compiler/binder.ts
• src/compiler/checker.ts
• src/compiler/commandLineParser.ts
• src/compiler/core.ts
• src/compiler/diagnosticMessages.json
• src/compiler/emitter.ts
• src/compiler/moduleNameResolver.ts
• src/compiler/moduleSpecifiers.ts
• src/compiler/parser.ts
• src/compiler/program.ts
• src/compiler/resolutionCache.ts
• src/compiler/scanner.ts
• src/compiler/sys.ts
• src/compiler/types.ts
• src/compiler/utilities.ts
• src/harness/client.ts
• src/harness/fourslashImpl.ts
• src/harness/fourslashInterfaceImpl.ts
• src/harness/harnessLanguageService.ts
• src/harness/harnessUtils.ts
• src/harness/runnerbase.ts
• src/jsTyping/jsTyping.ts
• src/server/editorServices.ts
• src/server/project.ts
• src/server/protocol.ts
• src/server/scriptInfo.ts
• src/server/scriptVersionCache.ts
• src/server/session.ts
• src/server/typingInstallerAdapter.ts
• src/server/utilities.ts
• src/services/codefixes/importFixes.ts
• src/services/completions.ts
• src/services/exportInfoMap.ts
• src/services/findAllReferences.ts
• src/services/goToDefinition.ts
• src/services/importTracker.ts
• src/services/services.ts
• src/services/types.ts
• src/services/utilities.ts
• src/testRunner/_namespaces/Harness.ts
• src/testRunner/parallel/host.ts
• src/testRunner/parallel/worker.ts
• src/testRunner/runner.ts
• src/testRunner/unittests/tscWatch/resolutionCache.ts
• src/testRunner/unittests/tsserver/applyChangesToOpenFiles.ts
• src/testRunner/unittests/tsserver/cachingFileSystemInformation.ts
• src/testRunner/unittests/tsserver/codeFix.ts
• src/testRunner/unittests/tsserver/compileOnSave.ts
• src/testRunner/unittests/tsserver/configuredProjects.ts
• src/testRunner/unittests/tsserver/events/projectUpdatedInBackground.ts
• src/testRunner/unittests/tsserver/exportMapCache.ts
• src/testRunner/unittests/tsserver/externalProjects.ts
• src/testRunner/unittests/tsserver/inferredProjects.ts
• src/testRunner/unittests/tsserver/openFile.ts
• src/testRunner/unittests/tsserver/projectErrors.ts
• src/testRunner/unittests/tsserver/projectReferenceErrors.ts
• src/testRunner/unittests/tsserver/projects.ts
• src/testRunner/unittests/tsserver/resolutionCache.ts
• src/testRunner/unittests/tsserver/symLinks.ts
• src/testRunner/unittests/tsserver/typingsInstaller.ts
• src/tsserver/common.ts
• src/tsserver/nodeServer.ts
• src/tsserver/server.ts
• src/typingsInstaller/nodeTypingsInstaller.ts
• src/typingsInstallerCore/typingsInstaller.ts
• tests/baselines/reference/api/typescript.d.ts
• tests/baselines/reference/tscWatch/resolutionCache/when-dir-watcher-is-invoked-without-file-change.js
• tests/baselines/reference/tsserver/codeFix/install-package-rejects-invalid-package-names.js
• tests/baselines/reference/tsserver/codeFix/install-package-when-serialized.js
• tests/baselines/reference/tsserver/codeFix/install-package.js
• tests/baselines/reference/tsserver/exportMapCache/invalidates-the-cache-when-a-file-is-opened-with-different-contents.js
• tests/baselines/reference/tsserver/projectReferenceErrors/when-options-for-dependency-project-are-different-from-usage-project.js
• tests/baselines/reference/tsserver/typingsInstaller/expired-cache-entry-lockFile3.js
• tests/baselines/reference/tsserver/typingsInstaller/non-expired-cache-entry-lockFile3.js
• tests/cases/fourslash/fourslash.ts
• tests/cases/fourslash/server/completionsOverridingMethodCrash2.ts

This page introduces tsserver as the long-running editor server process, describes its overall architecture, and explains how its major components relate to each other. For detailed coverage of the communication protocol, see tsserver Protocol. For project lifecycle management, see Project Management. For automatic type acquisition, see Automatic Type Acquisition. For the underlying language services that tsserver exposes, see Language Service.

---

Purpose

tsserver is a long-running Node.js process that exposes the TypeScript Language Service to editors and IDEs over a line-delimited JSON protocol. Instead of re-launching the compiler on every keystroke, the editor spawns a single tsserver process at startup, keeps it alive for the duration of the editing session, and exchanges request/response/event messages through its standard input and output streams.

All rich editing features that editors provide—completions, diagnostics, go-to-definition, rename, code fixes—are ultimately served by tsserver calling into the language service on behalf of the client.

---

High-Level Architecture

tsserver component hierarchy

Sources: src/server/session.ts1-110 src/server/editorServices.ts1-200 src/server/project.ts1-70

---

Entry Point and Initialization

tsserver is launched by editors as a child process. The canonical entry point is src/tsserver/server.ts (or src/tsserver/nodeServer.ts for Node-specific environments). It constructs a Session and starts the communication loop.

The initialization sequence is:

1. A ServerHost implementation (wrapping sys) is provided to Session.
2. Session constructs a ProjectService src/server/editorServices.ts190 which in turn creates a DocumentRegistry and sets up file watchers.
3. The session enters a read loop, parsing newline-delimited JSON from stdin.
4. On receiving an open request for a file, ProjectService locates or creates the appropriate Project (see Project Management).
5. The project instantiates a LanguageService backed by a fresh or reused Program.

Initialization flow

Sources: src/server/editorServices.ts197-210 src/server/project.ts25-30 src/server/session.ts1-50

---

Communication Model

All messages are JSON objects, one per line, transmitted over stdio. There are three message shapes defined in src/server/protocol.ts:

Shape	Key field	Direction	Description
Request	"type": "request"	Editor → tsserver	A command with a sequence number and optional arguments
Response	"type": "response"	tsserver → Editor	Result for a specific request sequence number
Event	"type": "event"	tsserver → Editor	Unsolicited notification (e.g. diagnostics ready)

The seq field links responses to requests tests/baselines/reference/api/typescript.d.ts134 Responses include a success boolean and a body containing the result.

The full set of commands is defined in the CommandTypes enum in src/server/protocol.ts tests/baselines/reference/api/typescript.d.ts49-126

---

Core Components

Session (src/server/session.ts)

Session owns the read loop and the command dispatch table. It:

• Reads newline-terminated JSON from stdin via ServerHost.
• Parses each line into a protocol.Request.
• Dispatches to a handler method by command string.
• Serializes handler results back to stdout as protocol.Response.
• Schedules deferred work (e.g. diagnostic computation) via ThrottledOperations src/server/editorServices.ts192

The handler methods are named after their commands (e.g. getCompletions, getDefinition) and delegate to ProjectService to find the active project and then call through to the project's LanguageService.

ProjectService (src/server/editorServices.ts)

ProjectService is the central coordinator. It manages:

• A registry of open files (ScriptInfo objects src/server/editorServices.ts186).
• The set of active Project instances.
• File system watchers for tsconfig.json files and source files.
• Routing each open file to the correct project.

Key constants defined here:

• maxProgramSizeForNonTsFiles = 20 MB — threshold above which JS files are excluded from a program src/server/editorServices.ts198
• maxFileSize = 4 MB — per-file size limit src/server/editorServices.ts200

Events emitted by ProjectService (as string constants):

Constant	Value	Meaning
ProjectsUpdatedInBackgroundEvent	"projectsUpdatedInBackground"	Background update finished src/server/editorServices.ts202
ProjectLoadingStartEvent	"projectLoadingStart"	Project starting to load src/server/editorServices.ts203
ProjectLoadingFinishEvent	"projectLoadingFinish"	Project finished loading src/server/editorServices.ts204
ConfigFileDiagEvent	"configFileDiag"	tsconfig.json diagnostics available src/server/editorServices.ts206

ScriptInfo (src/server/scriptInfo.ts)

Each open or referenced file is represented as a ScriptInfo. It stores:

• The file's normalized path (NormalizedPath).
• The current in-memory text (possibly edited but not yet saved).
• The ScriptKind (TS, JS, TSX, etc.).
• A list of projects that contain this file.

ScriptInfo acts as the shared, version-tracked document store that all projects access through the LanguageServiceHost interface.

Project Types (src/server/project.ts)

Three concrete project types inherit from the abstract Project base src/server/editorServices.ts182:

Type	Description
ConfiguredProject	Backed by a tsconfig.json / jsconfig.json file src/server/editorServices.ts153
InferredProject	Created for files that have no tsconfig.json src/server/editorServices.ts162
ExternalProject	Client-defined project (used by non-VS Code integrations) src/server/editorServices.ts159
AutoImportProviderProject	Auxiliary project used to compute auto-import completions src/server/editorServices.ts149

Each project owns a LanguageService instance and a DocumentRegistry (shared across projects to avoid parsing the same file twice).

---

Request Dispatch Diagram

How a completions request travels through tsserver

Sources: src/server/session.ts1-220 src/server/editorServices.ts1-200 src/server/project.ts1-70

---

Relationship to the Language Service and Compiler

tsserver does not duplicate language service or compiler logic. The dependency chain is strictly layered:

• src/compiler/ implements all parsing, type-checking, and emit logic.
• src/services/services.ts wraps the compiler in the LanguageService interface src/services/services.ts212 adding editor-oriented features.
• src/server/ wraps the language service in a protocol layer, adding project management and file watching.

Sources: src/services/services.ts212 src/server/project.ts25-30

---

Diagnostic Delivery

Unlike most requests, diagnostics are often delivered as events. The workflow is:

1. The editor sends a Geterr request tests/baselines/reference/api/typescript.d.ts71
2. tsserver schedules syntactic and semantic diagnostics as separate throttled operations.
3. Results are pushed back to the editor as semanticDiag, syntacticDiag, and suggestionDiag events.

This allows the editor to remain responsive while the type checker works in the background.

Sources: src/server/session.ts1-100 tests/baselines/reference/api/typescript.d.ts49-126

---

Sub-Pages

Page	Topic
tsserver Protocol	Full JSON message format, key command reference, Session dispatch details
Project Management	ProjectService, ConfiguredProject, InferredProject, ExternalProject lifecycle
Automatic Type Acquisition	TypingsInstaller, jsTyping, @types discovery and npm integration