[api] Expose API client modules from VS Code extension

[Andrew Branch (andrewbranch)]

Our VS Code extension already exposes a way for third-party extensions to connect a TypeScript API client to the user's currently running TypeScript LSP server. But since the API client and server need to be version-matched, and users can choose between a workspace version of TypeScript or one of potentially multiple built-in versions for their LSP server, the VS Code extension really needs to give those third-party extensions a way to resolve the correct version of the API client to use.

Previously, third-party extensions would do something like this:

import { API } from "typescript/async"; // <-- extension dependency version!

export function activate(context: vscode.ExtensionContext) {
  const extension = vscode.extensions.getExtension<ExtensionAPI>("TypeScriptTeam.native-preview")!;
  const extensionAPI = await extension.activate();
  const listener = extensionAPI.onLanguageServerInitialized(async () => {
    // ⚠️ *should* only do this inside onLanguageServerInitialized!
    const pipe = await extensionAPI.initializeAPIConnection();
    // 🚨 Establish potentially version-mismatched client/server connection!
    const api = await API.fromLSPConnection({ pipe });
  });
  context.subscriptions.push(listener);
}

With this PR, that will change to:

import type { ExtensionAPI } from "typescript/vscode"; // <-- devDependency for types

export function activate(context: vscode.ExtensionContext) {
  const extension = vscode.extensions.getExtension<ExtensionAPI>("TypeScriptTeam.native-preview")!;
  const extensionAPI = await extension.activate();
  const listener = extensionAPI.onLanguageServerInitialized(async tssdk => {
    // ✅ *can* only do this inside onLanguageServerInitialized
    const pipe = await tssdk.initializeAPIConnection();
    // ✅ Get the client that shipped with the server
    console.log("Resolved TypeScript client version ", tssdk.version);
    const { API } = await tssdk.importModule("typescript/async");
    const api = await API.fromLSPConnection({ pipe });
  });
  context.subscriptions.push(listener);
}

Of course, this means that your API client types are effectively a devDependency representing a peerDependency whose versions could be mismatched at runtime. Extensions should type check and test against multiple versions, and use runtime probes to conditionally access newer client features:

if (api.newMethodAddedInTypeScript7_4) {
  const res = await api.newMethodAddedInTypeScript7_4();
}

More guidance on version compatibility will be documented soon.

Doing the same thing from a third-party LSP server

If you're launching an LSP server that connects to the TypeScript API, the method above won't help you, since you can't access the extension API from another process. For convenience, the same typed module loader is exported from "typescript/vscode". If you're bundling your extension, you can import from that module without bundling in the actual API client:

// extension.ts
import type { ExtensionAPI } from "typescript/vscode";

export async function activate(context: vscode.ExtensionContext) {
  const extension = vscode.extensions.getExtension<ExtensionAPI>("TypeScriptTeam.native-preview")!;
  const extensionAPI = await extension.activate();
  const listener = extensionAPI.onLanguageServerInitialized(async sdk => {
    const client = new LanguageClient("my-server", "My Server", serverOptions, {
      initializationOptions: {
        typescriptPackageJsonPath: sdk.packageJsonPath!,
        typescriptAPIPipe: await sdk.initializeAPIConnection(),
      },
    });
    await client.start();
  });
  context.subscriptions.push(listener);
});

// server.ts
import { createTypeScriptModuleLoader } from "typescript/vscode";

connection.onInitialize(async params => {
    const { typescriptPackageJsonPath, typescriptAPIPipe } =
        params.initializationOptions;

    const loader = createTypeScriptModuleLoader(typescriptPackageJsonPath);
    const { API } = await loader.importModule("typescript/async");
    api = await API.fromLSPConnection({ pipe: typescriptAPIPipe });

    return { capabilities: {} };
});

VSIX structure

This changes VSIX packaging to include node_modules containing typescript and @typescript/typescript-${os}-${arch} instead of the bare tsc executable in lib/.

Manually tested the LSP + an API connection with the packed VSIX, that plus the nightly VSIX, and local dev, but extra eyes on the output are appreciated.

[Andrew Branch (andrewbranch)]

Type names also valid for bikeshedding

[Andrew Branch (andrewbranch)]

I opted to have a fallback here so you could use a newer import path than your types expose, but I'm not sure if there's much reason not to just install the latest types as soon as you want to use the latest features. Would it be better to remove this?

[Copilot]

Copilot review overview

🟡 Changes recommended

Package-change detection can permit unverifiable versions and abort restarts when a manifest becomes unreadable.

Review effort: Balanced
Findings: 2

Open (2)

• Handle unreadable active workspace manifests during SDK restart · New
• Reject SDK manifests with missing or non-string versions · New

Resolved since last review (4)

• Align async import documentation with the exported subpath
• Isolate module caches across in-place SDK upgrades
• Dispose subscriptions when the immediate callback throws
• Add unstable/path to the typed runtime export map

[Jake Bailey (jakebailey)]

I assume we're stuck not using import.meta.resolve? Or someone's shim for it? Seems odd to pull out require just for this

[Jake Bailey (jakebailey)]

Where's the clean go?

[Jake Bailey (jakebailey)]

This is preexisting but now that we don't say tsgo (local), this just says (local) which always seemed wrong to me in the UI 😄

[Jake Bailey (jakebailey)]

Why do we have to set this? Just so we trick vsce?