Web: provide a workbench.web.api.d.ts for an embedder to develop against

[bpasero]

We provide an API surface for an embedder of our web UI:

vscode/src/vs/workbench/workbench.web.api.ts

Line 238 in 7a83e5a

interface IWorkbenchConstructionOptions {

We also require some specific setup to load our web UI pieces as indicated by our yarn web implementation:

vscode/src/vs/code/browser/workbench/workbench.html

Line 42 in c87c95a

paths: {

We should:

• investigate to produce a workbench.web.api.d.ts (similar to monaco.d.ts) for the workbench.web.api for an embedder to develop against
• consider to extract the loader configuration into something reusable (amdconfig.js?) that an embedder can just point to

[lramos15]

Loader piece is done will defer the .d.ts to a later date

[connor4312]

Following up on discussion on other internal issues, I suggest not automatically generating the .d.ts, and instead have the web api .d.ts checked into VS Code and with manually duplicated types.

The reason is that we have dependency on code and typings for embedders, but it is very easy for team members to not realize that code they're working is exposed in this API and depended upon by the embedder. This may result in breakages, especially if it's something as easy and innocent as an automated refactor for a property rename. Causing a compilation error unless the web .d.ts is manually and explicitly updated would reduce the likelihood of accidental breakages.

[bpasero]

I think there are 2 camps: vscode.d.ts is handcrafted but monaco.d.ts for example is not and both have API users.

[joaomoreno]

My 2c. I love that monaco.d.ts is automatically created, though I don't envy @alexdima from maintaining that 700 LoC machinery. I love manually authoring vscode.d.ts because it lets us craft that file so well, including docs and make sure we are properly exposed, but the overhead of maintaining two worlds is real. Maybe @jrieken's would be the PoV I'm more interested in.

[jrieken]

I suggest not automatically generating the .d.ts, and instead have the web api .d.ts checked into VS Code and with manually duplicated types.

+💯. Creating those types manually is IMO the only way to guarantee awareness of changes in API and to "design" the API explicitly. That's also the different between vscode.d.ts and monaco.d.ts - the latter is a slightly cherry-picked but mostly AS-IS representation of the "internal" API.

[bpasero]

I am fine handpicking the API for embedder but I wonder how we could validate the correctness of the API then: we need to ensure we implement the API also in the workbench to get type failures early. In other words, we cannot just hand craft a d.ts file and not validate it with our actual code. I think vscode.d.ts does that.

[jrieken]

Yeah, we explicitly implement the API in src/vs/workbench/api/common/extHost.api.impl.ts, we define a type which is of the vscode-module here:

vscode/src/vs/workbench/api/common/extHost.api.impl.ts

Line 1138 in 527d631

return <typeof vscode>{

[bpasero]

@joaomoreno pointed out this tool which maybe could help: https://api-extractor.com/

Naive first run and error: microsoft/rushstack#3738

[samdenty]

@bpasero i'm interested in this, any progress?

[samdenty]

I tried using api-extractor by using the new typescript 5.6.0 noCheck option to compile a separate folder of .d.ts for the src folder in hopes stripping out the code causing the error and just using the types would help. But after i did that i ran into a new error Child declaration not found for the specified node, it was happening on pretty much any import from vs/.

Then I tried using https://github.com/timocov/dts-bundle-generator and it worked a charm, I created:

declarations/package.json:

{
  "name": "declaration",
  "version": "1.0.0",
  "main": "index.js",
  "license": "MIT",
  "overrides": {},
  "dependencies": {
    "dts-bundle-generator": "^9.5.1",
    "typescript": "5.6.0-dev.20240723"
  },
  "resolutions": {
    "**/typescript": "5.6.0-dev.20240723"
  },
  "scripts": {
    "build": "dts-bundle-generator -o workbench.d.ts --project tsconfig.json ../src/vs/workbench/browser/web.api.ts"
  }
}

declarations/tsconfig.json:

{
	"compilerOptions": {
		"moduleResolution": "node",
		"baseUrl": "../src",
		"paths": {
			"vs/*": ["../src/vs/*"]
		},
		"target": "es2022",
		"skipLibCheck": true,
		"noCheck": true,
		"lib": ["ES2022", "DOM", "DOM.Iterable", "WebWorker.ImportScripts"]
	},
	"include": [
		"../src/vs/**/*.ts",
		"vscode-dts/vscode.proposed.*.d.ts",
		"vscode-dts/vscode.d.ts"
	]
}

and then run yarn build and i get a nicely compiled workbench.d.ts

[bpasero]

Cool, can you attach the resulting file here? Curious how it compares to the one we manually craft.

[bpasero]

Btw when I try I get an error:

~/Development/Microsoft/vscode/declarations> yarn build
yarn run v1.22.22
$ dts-bundle-generator -o workbench.d.ts --project tsconfig.json ../src/vs/workbench/browser/web.api.ts
Compiling input files...
error TS5023: Unknown compiler option 'noCheck'.

Error: Error while processing tsconfig compiler options
error Command failed with exit code 1.
info Visit https://yarnpkg.com/en/docs/cli/run for documentation about this command.
~/Development/Microsoft/vscode/declarations>   

Update: nevermind, I did not have TS 5.6.x installed. The resulting file is:

workbench.d.ts.zip