TypeScript Template Language Service Decorator

2.3.2 verified Sat Apr 25 auth: no javascript

Framework for decorating a TypeScript language service with support for languages embedded inside template strings. Current stable version is 2.3.2, released July 2021. This library abstracts the complexity of handling template string nodes, allowing developers to focus on the embedded language's content. It is primarily used to build TypeScript language service plugins for tagged template literals (e.g., styled-components, lit-html). Unlike custom language service implementations, this decorator seamlessly integrates with TypeScript's existing infrastructure, handling offset mapping and template context automatically. It ships with TypeScript types and is ESM-and-CJS compatible. Release cadence is low; updates are infrequent and focus on maintenance.

Common errors

error TypeError: Cannot read property 'getLanguageService' of undefined ↓

cause Using 'typescript' instead of 'typescript/lib/tsserverlibrary'.

fix

Change import to import * as ts from 'typescript/lib/tsserverlibrary'.

error Module '"typescript-template-language-service-decorator"' has no exported member 'TemplateLanguageService'. ↓

cause Using non-type import on a type-only export; likely missing 'type' keyword.

fix

Use import type { TemplateLanguageService } from 'typescript-template-language-service-decorator'.

error error TS2345: Argument of type '{ tags: string[]; }' is not assignable to parameter of type 'TemplateSettings'. ↓

cause TemplateSettings expects `tags` as `string[]`, but also requires other properties like `enabled`. Provide full object.

fix

Use { tags: ['myTag'], enabled: true }.

Warnings

gotcha The library requires 'typescript/lib/tsserverlibrary' as a peer dependency; using 'typescript' alone will fail. ↓

fix Import from 'typescript/lib/tsserverlibrary' instead of 'typescript'.

breaking In version 2.3.0, `getDefinitionAndBoundSpan` was added; plugins that override this method may need to update their interface. ↓

fix Implement the new optional method or update the interface to include it.

gotcha TemplateContext.text is the raw text of the template string; newlines are preserved and positions are relative to this raw text. ↓

fix Parse text using `context.text.split(/\n/g)` or similar to get lines.

deprecated The old method `getCompletionsAtPosition` used to accept a `string` for relativePosition; now it expects `ts.LineAndCharacter`. ↓

fix Update to use `ts.LineAndCharacter` object.

gotcha If using CommonJS, you must default-import the module due to ESM/CJS interop. ↓

fix Use `import pkg from 'typescript-template-language-service-decorator'` with `esModuleInterop` enabled.

Install

npm install typescript-template-language-service-decorator

yarn add typescript-template-language-service-decorator

pnpm add typescript-template-language-service-decorator

Imports

decorateWithTemplateLanguageService

wrong

const decorateWithTemplateLanguageService = require('typescript-template-language-service-decorator').decorateWithTemplateLanguageService

correct

import { decorateWithTemplateLanguageService } from 'typescript-template-language-service-decorator'

Named import; also available via default import but named is recommended.

TemplateLanguageService

wrong

import { TemplateLanguageService } from 'typescript-template-language-service-decorator'

correct

import type { TemplateLanguageService } from 'typescript-template-language-service-decorator'

This is a type/interface; use `import type` in TypeScript to avoid runtime import.

TemplateContext

import type { TemplateContext } from 'typescript-template-language-service-decorator'

TemplateContext is an interface; use `import type`.

Quickstart

Shows a complete TypeScript server plugin that adds echo completions to template strings tagged with `echo`.

import * as ts from 'typescript/lib/tsserverlibrary';
import { decorateWithTemplateLanguageService, TemplateLanguageService, TemplateContext } from 'typescript-template-language-service-decorator';

class EchoTemplateLanguageService implements TemplateLanguageService {
    getCompletionsAtPosition(
        context: TemplateContext,
        position: ts.LineAndCharacter
    ): ts.CompletionInfo {
        const line = context.text.split(/\n/g)[position.line];
        return {
            isGlobalCompletion: false,
            isMemberCompletion: false,
            isNewIdentifierLocation: false,
            entries: [
                {
                    name: line.slice(0, position.character),
                    kind: '',
                    kindModifiers: 'echo',
                    sortText: 'echo'
                }
            ]
        };
    }
}

export = (mod: { typescript: typeof ts }) => {
    return {
        create(info: ts.server.PluginCreateInfo): ts.LanguageService {
            return decorateWithTemplateLanguageService(
                mod.typescript,
                info.languageService,
                info.project,
                new EchoTemplateLanguageService(),
                { tags: ['echo'] }
            );
        }
    };
};