Where is vscode.proposed.d.ts? · Issue #136964 · microsoft/vscode (original) (raw)

The vscode.proposed.d.ts-file has been split up into separate files, each representing one proposal. This enables scoped access to proposals (see #131165 for details and discussion)

Extensions need to opt into specific proposals via the new package.json#enabledApiProposals-property. The enableProposedApi-property will stop working soon.

Migration Guide

  1. First, validate that you still need proposed API access. Often proposals have been finalized and using proposed API isn't needed anymore. Try this:
    1. get latest vscode.d.ts via @types/vscode or >npx vscode-dts main
    2. delete the vscode.proposed.d.ts-file
    3. compile your project
    4. iff there are no errors, you are done. You can also delete the package.json#enableProposedApi-property.
    5. go to step 3 ❗
  2. You have validated that your extension still depends on proposed API. Do the following:
    1. Spell out each proposal you want at package.json#enabledApiProposals. It's this property that enables proposals!
    2. delete the vscode.proposed.d.ts-file
    3. get latest vscode-dts and run npx vscode-dts dev to fetch the proposal-definitions you need.
    4. go to step 3 ❗
  3. More tricky is proposed API usage that isn't TypeScript, namely proposed contribution points or properties of package.json. This is fortunately rare and but some manual labor and diligence is needed. Check the vscode.proposed.contribXYZ.d.ts files for package.json-properties you are using and add the proposal names to the package.json#enabledApiProposals-property

FAQ

Sample

This is a sample commit microsoft/vscode-anycode@cf73d4d that migrates anycode onto a specific API proposal.

Is this a breaking change?

Not yet. For now we are breaking up vscode.proposed.d.ts but we still honor the enableProposedApi-property for a bit. So, you likely see TypeScript compile errors but the runtime behavior isn't changed yet.

Are changes to package.json and to vscode.proposed.XYZ.d.ts needed?

The changes to package.json#enabledApiProposals are absolutely needed, they are the truth while dts files are "only" needed for the TypeScript compiler.

What about package.json#enableProposedApi

When your extension is enabled via our product.json-file you can safely remove the property. VS Code will enable your extension, also older version which don't support enabledApiProposals yet.