typescript-language-server

What is typescript-language-server?

The typescript-language-server is an implementation of the Language Server Protocol (LSP) for TypeScript. It provides a range of features to enhance the development experience in editors and IDEs by offering functionalities like auto-completion, go-to-definition, and more.

What are typescript-language-server's main functionalities?

Auto-completion

This code sets up a basic TypeScript Language Server that provides auto-completion suggestions. When the user types, the server can suggest completions like 'console.log'.

const { createConnection, TextDocuments } = require('vscode-languageserver');
const connection = createConnection();
const documents = new TextDocuments();

connection.onInitialize(() => {
  return {
    capabilities: {
      textDocumentSync: documents.syncKind,
      completionProvider: {
        resolveProvider: true
      }
    }
  };
});

connection.onCompletion(() => {
  return [
    {
      label: 'console.log',
      kind: 1,
      data: 1
    }
  ];
});

connection.listen();

Go-to-definition

This code sets up a TypeScript Language Server that provides go-to-definition functionality. When the user requests the definition of a symbol, the server responds with the location of the definition.

const { createConnection, TextDocuments } = require('vscode-languageserver');
const connection = createConnection();
const documents = new TextDocuments();

connection.onInitialize(() => {
  return {
    capabilities: {
      textDocumentSync: documents.syncKind,
      definitionProvider: true
    }
  };
});

connection.onDefinition((params) => {
  return {
    uri: params.textDocument.uri,
    range: {
      start: { line: 0, character: 0 },
      end: { line: 0, character: 10 }
    }
  };
});

connection.listen();

Diagnostics

This code sets up a TypeScript Language Server that provides diagnostics. It scans the document for 'TODO' comments and reports them as warnings.

const { createConnection, TextDocuments, Diagnostic, DiagnosticSeverity } = require('vscode-languageserver');
const connection = createConnection();
const documents = new TextDocuments();

connection.onInitialize(() => {
  return {
    capabilities: {
      textDocumentSync: documents.syncKind
    }
  };
});

documents.onDidChangeContent((change) => {
  const diagnostics = [];
  const text = change.document.getText();
  const pattern = /TODO/g;
  let match;
  while ((match = pattern.exec(text))) {
    diagnostics.push({
      severity: DiagnosticSeverity.Warning,
      range: {
        start: change.document.positionAt(match.index),
        end: change.document.positionAt(match.index + match[0].length)
      },
      message: `TODO found: ${match[0]}`,
      source: 'ex'
    });
  }
  connection.sendDiagnostics({ uri: change.document.uri, diagnostics });
});

connection.listen();

Other packages similar to typescript-language-server

vscode-json-languageserver

The vscode-json-languageserver is a Language Server Protocol implementation for JSON. It provides similar functionalities like auto-completion, go-to-definition, and diagnostics but is specifically tailored for JSON files. Compared to typescript-language-server, it is focused on JSON rather than TypeScript.

vscode-css-languageserver-bin

The vscode-css-languageserver-bin is a Language Server Protocol implementation for CSS. It offers features like auto-completion, go-to-definition, and diagnostics for CSS files. While typescript-language-server is for TypeScript, this package is specialized for CSS.

vscode-html-languageserver-bin

The vscode-html-languageserver-bin is a Language Server Protocol implementation for HTML. It provides functionalities such as auto-completion, go-to-definition, and diagnostics for HTML files. This package is similar to typescript-language-server but is designed for HTML.

README

TypeScript Language Server

Language Server Protocol implementation for TypeScript wrapping tsserver.

Based on concepts and ideas from https://github.com/prabirshrestha/typescript-language-server and originally maintained by TypeFox

Maintained by a community of contributors like you

• Installing
• Running the language server
• CLI Options
• initializationOptions
• workspace/didChangeConfiguration
• Code actions on save
• Workspace commands (workspace/executeCommand)
  • Go to Source Definition
  • Apply Workspace Edits
  • Apply Code Action
  • Apply Refactoring
  • Organize Imports
  • Rename File
• Inlay hints (typescript/inlayHints) (experimental)
• Callers and callees (textDocument/calls) (experimental)
• Supported Protocol features
  • Experimental
• Development
  • Build
  • Test
  • Watch
  • Publishing

Installing

npm install -g typescript-language-server typescript

Running the language server

typescript-language-server --stdio

CLI Options

  Usage: typescript-language-server [options]


  Options:

    -V, --version                          output the version number
    --stdio                                use stdio (required option)
    --log-level <log-level>                A number indicating the log level (4 = log, 3 = info, 2 = warn, 1 = error). Defaults to `3`.
    --tsserver-log-file <tsServerLogFile>  Specify a tsserver log file. example: --tsserver-log-file=ts-logs.txt
    --tsserver-log-verbosity <verbosity>   Specify tsserver log verbosity (off, terse, normal, verbose). Defaults to `normal`. example: --tsserver-log-verbosity=verbose
    --tsserver-path <path>                 Specify path to tsserver directory. example: --tsserver-path=/Users/me/typescript/lib/
    -h, --help                             output usage information

Note: The path passed to --tsserver-path should ideally be a path to the /.../typescript/lib/ directory and not to the shell script /.../node_modules/.bin/tsserver or tsserver. Though for backward-compatibility reasons, the server will try to do the right thing even when passed a path to the shell script.

initializationOptions

The language server accepts various settings through the initializationOptions object passed through the initialize request. Refer to your LSP client's documentation on how to set these. Here is the list of supported options:

Setting	Type	Description
hostInfo	string	Information about the host, for example "Emacs 24.4" or "Sublime Text v3075". Default: undefined
disableAutomaticTypingAcquisition	boolean	Disables tsserver from automatically fetching missing type definitions (@types packages) for external modules.
logVerbosity	string	The verbosity level of the information printed in the log by tsserver. Accepts values: "off", "terse", "normal", "requesttime", "verbose". Default: undefined ("off").
maxTsServerMemory	number	The maximum size of the V8's old memory section in megabytes (for example 4096 means 4GB). The default value is dynamically configured by Node so can differ per system. Increase for very big projects that exceed allowed memory usage. Default: undefined
npmLocation	string	Specifies the path to the NPM executable used for Automatic Type Acquisition.
locale	string	The locale to use to show error messages.
plugins	object[]	An array of { name: string, location: string } objects for registering a Typescript plugins. Default: []
preferences	object	Preferences passed to the Typescript (tsserver) process. See below for more info.

The preferences object is an object specifying preferences for the internal tsserver process. Those options depend on the version of Typescript used but at the time of writing Typescript v4.4.3 contains these options:

interface UserPreferences {
    disableSuggestions: boolean;
    quotePreference: "auto" | "double" | "single";
    /**
     * If enabled, TypeScript will search through all external modules' exports and add them to the completions list.
     * This affects lone identifier completions but not completions on the right hand side of `obj.`.
     */
    includeCompletionsForModuleExports: boolean;
    /**
     * Enables auto-import-style completions on partially-typed import statements. E.g., allows
     * `import write|` to be completed to `import { writeFile } from "fs"`.
     */
    includeCompletionsForImportStatements: boolean;
    /**
     * Allows completions to be formatted with snippet text, indicated by `CompletionItem["isSnippet"]`.
     */
    includeCompletionsWithSnippetText: boolean;
    /**
     * If enabled, the completion list will include completions with invalid identifier names.
     * For those entries, The `insertText` and `replacementSpan` properties will be set to change from `.x` property access to `["x"]`.
     */
    includeCompletionsWithInsertText: boolean;
    /**
     * Unless this option is `false`, or `includeCompletionsWithInsertText` is not enabled,
     * member completion lists triggered with `.` will include entries on potentially-null and potentially-undefined
     * values, with insertion text to replace preceding `.` tokens with `?.`.
     */
    includeAutomaticOptionalChainCompletions: boolean;
    /**
     * If enabled, completions for class members (e.g. methods and properties) will include
     * a whole declaration for the member.
     * E.g., `class A { f| }` could be completed to `class A { foo(): number {} }`, instead of
     * `class A { foo }`.
     * @since 4.5.2
     * @default true
     */
    includeCompletionsWithClassMemberSnippets: boolean;
    /**
     * If enabled, object literal methods will have a method declaration completion entry in addition
     * to the regular completion entry containing just the method name.
     * E.g., `const objectLiteral: T = { f| }` could be completed to `const objectLiteral: T = { foo(): void {} }`,
     * in addition to `const objectLiteral: T = { foo }`.
     * @since 4.7.2
     * @default true
     */
    includeCompletionsWithObjectLiteralMethodSnippets: boolean;
    /**
     * Indicates whether {@link CompletionEntry.labelDetails completion entry label details} are supported.
     * If not, contents of `labelDetails` may be included in the {@link CompletionEntry.name} property.
     * Only supported if the client supports `textDocument.completion.completionItem.labelDetailsSupport` capability
     * and a compatible TypeScript version is used.
     * @since 4.7.2
     * @default true
     */
    useLabelDetailsInCompletionEntries: boolean;
    /**
     * Allows import module names to be resolved in the initial completions request.
     * @default false
     */
    allowIncompleteCompletions: boolean;
    importModuleSpecifierPreference: "shortest" | "project-relative" | "relative" | "non-relative";
    /** Determines whether we import `foo/index.ts` as "foo", "foo/index", or "foo/index.js" */
    importModuleSpecifierEnding: "auto" | "minimal" | "index" | "js";
    allowTextChangesInNewFiles: boolean;
    lazyConfiguredProjectsFromExternalProject: boolean;
    providePrefixAndSuffixTextForRename: boolean;
    provideRefactorNotApplicableReason: boolean;
    allowRenameOfImportPath: boolean;
    includePackageJsonAutoImports: "auto" | "on" | "off";
    /**
     * Preferred style for JSX attribute completions:
     * - `"auto"` - Insert `={}` or `=\"\"` after attribute names based on the prop type.
     * - `"braces"` - Insert `={}` after attribute names.
     * - `"none"` - Only insert attribute names.
     * @since 4.5.2
     * @default 'auto'
     */
    jsxAttributeCompletionStyle: "auto" | "braces" | "none";
    displayPartsForJSDoc: boolean;
    generateReturnInDocTemplate: boolean;

    includeInlayParameterNameHints: "none" | "literals" | "all";
    includeInlayParameterNameHintsWhenArgumentMatchesName: boolean;
    includeInlayFunctionParameterTypeHints: boolean,
    includeInlayVariableTypeHints: boolean;
    includeInlayPropertyDeclarationTypeHints: boolean;
    includeInlayFunctionLikeReturnTypeHints: boolean;
    includeInlayEnumMemberValueHints: boolean;
}

From the preferences options listed above, this server explicilty sets the following options (all other options use their default values):

{
    allowIncompleteCompletions: true,
    allowRenameOfImportPath: true,
    allowTextChangesInNewFiles: true,
    displayPartsForJSDoc: true,
    generateReturnInDocTemplate: true,
    includeAutomaticOptionalChainCompletions: true,
    includeCompletionsForImportStatements: true,
    includeCompletionsForModuleExports: true,
    includeCompletionsWithClassMemberSnippets: true,
    includeCompletionsWithObjectLiteralMethodSnippets: true,
    includeCompletionsWithInsertText: true,
    includeCompletionsWithSnippetText: true,
    jsxAttributeCompletionStyle: "auto",
    providePrefixAndSuffixTextForRename: true,
}

workspace/didChangeConfiguration

Some of the preferences can be controlled through the workspace/didChangeConfiguration notification. Below is a list of supported options that can be passed. Note that the settings are specified separately for the typescript and javascript files so [language] can be either javascript or typescript.

// Formatting preferences
[language].format.baseIndentSize: number;
[language].format.convertTabsToSpaces: boolean;
[language].format.indentSize: number;
[language].format.indentStyle: 'None' | 'Block' | 'Smart';
[language].format.insertSpaceAfterCommaDelimiter: boolean;
[language].format.insertSpaceAfterConstructor: boolean;
[language].format.insertSpaceAfterFunctionKeywordForAnonymousFunctions: boolean;
[language].format.insertSpaceAfterKeywordsInControlFlowStatements: boolean;
[language].format.insertSpaceAfterOpeningAndBeforeClosingEmptyBraces: boolean;
[language].format.insertSpaceAfterOpeningAndBeforeClosingJsxExpressionBraces: boolean;
[language].format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBraces: boolean;
[language].format.insertSpaceAfterOpeningAndBeforeClosingNonemptyBrackets: boolean;
[language].format.insertSpaceAfterOpeningAndBeforeClosingNonemptyParenthesis: boolean;
[language].format.insertSpaceAfterOpeningAndBeforeClosingTemplateStringBraces: boolean;
[language].format.insertSpaceAfterSemicolonInForStatements: boolean;
[language].format.insertSpaceAfterTypeAssertion: boolean;
[language].format.insertSpaceBeforeAndAfterBinaryOperators: boolean;
[language].format.insertSpaceBeforeFunctionParenthesis: boolean;
[language].format.insertSpaceBeforeTypeAnnotation: boolean;
[language].format.newLineCharacter: string;
[language].format.placeOpenBraceOnNewLineForControlBlocks: boolean;
[language].format.placeOpenBraceOnNewLineForFunctions: boolean;
[language].format.semicolons: 'ignore' | 'insert' | 'remove';
[language].format.tabSize: number;
[language].format.trimTrailingWhitespace: boolean;
// Inlay Hints preferences
[language].inlayHints.includeInlayEnumMemberValueHints: boolean;
[language].inlayHints.includeInlayFunctionLikeReturnTypeHints: boolean;
[language].inlayHints.includeInlayFunctionParameterTypeHints: boolean;
[language].inlayHints.includeInlayParameterNameHints: 'none' | 'literals' | 'all';
[language].inlayHints.includeInlayParameterNameHintsWhenArgumentMatchesName: boolean;
[language].inlayHints.includeInlayPropertyDeclarationTypeHints: boolean;
[language].inlayHints.includeInlayVariableTypeHints: boolean;
/**
 * Complete functions with their parameter signature.
 * @default false
 */
completions.completeFunctionCalls: boolean;
// Diagnostics code to be omitted when reporting diagnostics.
// See https://github.com/microsoft/TypeScript/blob/master/src/compiler/diagnosticMessages.json for a full list of valid codes.
diagnostics.ignoredCodes: number[];

Code actions on save

Server announces support for the following code action kinds:

• source.addMissingImports.ts - adds imports for used but not imported symbols
• source.fixAll.ts - despite the name, fixes a couple of specific issues: unreachable code, await in non-async functions, incorrectly implemented interface
• source.removeUnused.ts - removes declared but unused variables
• source.organizeImports.ts - organizes and removes unused imports

This allows editors that support running code actions on save to automatically run fixes associated with those kinds.

Those code actions, if they apply in the current code, should also be presented in the list of "Source Actions" if the editor exposes those.

The user can enable it with a setting similar to (can vary per-editor):

"codeActionsOnSave": {
    "source.organizeImports.ts": true,
    // or just
    "source.organizeImports": true,
}

Workspace commands (workspace/executeCommand)

See LSP specification.

Most of the time, you'll execute commands with arguments retrieved from another request like textDocument/codeAction. There are some use cases for calling them manually.

lsp refers to the language server protocol types, tsp refers to the typescript server protocol types.

Go to Source Definition

• Request:

  {
      command: `_typescript.goToSourceDefinition`
      arguments: [
          lsp.DocumentUri,  // String URI of the document
          lsp.Position,     // Line and character position (zero-based)
      ]
  }
  

• Response:

  lsp.Location[] | null
  

(This command is supported from Typescript 4.7.)

Apply Workspace Edits

• Request:

  {
      command: `_typescript.applyWorkspaceEdit`
      arguments: [lsp.WorkspaceEdit]
  }
  

• Response:

  lsp.ApplyWorkspaceEditResult
  

Apply Code Action

• Request:

  {
      command: `_typescript.applyCodeAction`
      arguments: [
          tsp.CodeAction,  // TypeScript Code Action object
      ]
  }
  

• Response:

  void
  

Apply Refactoring

• Request:

  {
      command: `_typescript.applyRefactoring`
      arguments: [
          tsp.GetEditsForRefactorRequestArgs,
      ]
  }
  

• Response:

  void
  

Organize Imports

• Request:

  {
      command: `_typescript.organizeImports`
      arguments: [
          // The "skipDestructiveCodeActions" argument is supported from Typescript 4.4+
          [string] | [string, { skipDestructiveCodeActions?: boolean }],
      ]
  }
  

• Response:

  void
  

Rename File

• Request:

  {
      command: `_typescript.applyRenameFile`
      arguments: [
          { sourceUri: string; targetUri: string; },
      ]
  }
  

• Response:

  void
  

Inlay hints (typescript/inlayHints) (experimental)

!!! This implementation is deprecated. Use the spec-compliant textDocument/inlayHint request instead. !!!

Supports experimental inline hints.

type Request = {
  textDocument: TextDocumentIdentifier,
  range?: Range,
}

type Response = {
  inlayHints: InlayHint[];
}

type InlayHint = {
    text: string;
    position: lsp.Position;
    kind: 'Type' | 'Parameter' | 'Enum';
    whitespaceBefore?: boolean;
    whitespaceAfter?: boolean;
};

For the request to return any results, some or all of the following options need to be enabled through preferences:

// Not officially part of UserPreferences yet but you can send them along with the UserPreferences just fine:
export interface InlayHintsOptions extends UserPreferences {
    includeInlayParameterNameHints: 'none' | 'literals' | 'all';
    includeInlayParameterNameHintsWhenArgumentMatchesName: boolean;
    includeInlayFunctionParameterTypeHints: boolean;
    includeInlayVariableTypeHints: boolean;
    includeInlayPropertyDeclarationTypeHints: boolean;
    includeInlayFunctionLikeReturnTypeHints: boolean;
    includeInlayEnumMemberValueHints: boolean;
}

Callers and callees (textDocument/calls) (experimental)

Supports showing callers and calles for a given symbol. If the editor has support for appropriate UI, it can generate a tree of callers and calles for a document.

type Request = {
    /**
     * The text document.
     */
    textDocument: TextDocumentIdentifier;
    /**
     * The position inside the text document.
     */
    position: Position;
    /**
     * Outgoing direction for callees.
     * The default is incoming for callers.
     */
    direction?: CallDirection;
}

export enum CallDirection {
    /**
     * Incoming calls aka. callers
     */
    Incoming = 'incoming',
    /**
     * Outgoing calls aka. callees
     */
    Outgoing = 'outgoing',
}

type Result = {
    /**
     * The symbol of a definition for which the request was made.
     *
     * If no definition is found at a given text document position, the symbol is undefined.
     */
    symbol?: DefinitionSymbol;
    /**
     * List of calls.
     */
    calls: Call[];
}

interface Call {
    /**
     * Actual location of a call to a definition.
     */
    location: Location;
    /**
     * Symbol refered to by this call. For outgoing calls this is a callee,
     * otherwise a caller.
     */
    symbol: DefinitionSymbol;
}

interface DefinitionSymbol {
    /**
     * The name of this symbol.
     */
    name: string;
    /**
     * More detail for this symbol, e.g the signature of a function.
     */
    detail?: string;
    /**
     * The kind of this symbol.
     */
    kind: SymbolKind;
    /**
     * The range enclosing this symbol not including leading/trailing whitespace but everything else
     * like comments. This information is typically used to determine if the the clients cursor is
     * inside the symbol to reveal in the symbol in the UI.
     */
    location: Location;
    /**
     * The range that should be selected and revealed when this symbol is being picked, e.g the name of a function.
     * Must be contained by the the `range`.
     */
    selectionRange: Range;
}

Supported Protocol features

• textDocument/codeAction
• textDocument/completion (incl. completion/resolve)
• textDocument/definition
• textDocument/didChange (incremental)
• textDocument/didClose
• textDocument/didOpen
• textDocument/didSave
• textDocument/documentHighlight
• textDocument/documentSymbol
• textDocument/executeCommand
• textDocument/formatting
• textDocument/hover
• textDocument/inlayHint (no support for inlayHint/resolve or workspace/inlayHint/refresh)
• textDocument/rangeFormatting
• textDocument/references
• textDocument/rename
• textDocument/signatureHelp
• workspace/symbol
• workspace/didChangeConfiguration
• workspace/executeCommand

Experimental

• textDocument/calls (experimental)
• typescript/inlayHints (experimental, supported from Typescript v4.4.2) DEPRECATED (use textDocument/inlayHint instead)

Development

Build

yarn

Test

• yarn test - run all tests
• yarn test:watch - run all tests and enable watch mode for developing

By default only console logs of level warn and higher are printed to the console. You can override the CONSOLE_LOG_LEVEL level in package.json to either log, info, warn or error to log other levels.

Watch

yarn watch

Publishing

New version of the package is published automatically on pushing new tag to the upstream repo.

Changelog

1.1.2 (2022-08-25)

Bug Fixes

• definition request crashing on getting span (#574) (4e1c82b)