3f:null 40:["$","title",null,{"children":"Bringing the TypeScript Language Server to Observable | Observable | Observable"}] 46:[{"id":"18d929901383fce8dfffd144fc08ad9d998d2a7a0ce5473fc70a1e5622a8c9e8757a599ac484a5a20e38f368db07b68c70b2abd6a82f85e08b0e2dbdeae84609","href":"https://static.observableusercontent.com/files/18d929901383fce8dfffd144fc08ad9d998d2a7a0ce5473fc70a1e5622a8c9e8757a599ac484a5a20e38f368db07b68c70b2abd6a82f85e08b0e2dbdeae84609","name":"Editor_Hints_Blog.png","type":"image/png","lastModified":1668710425157.454,"size":86087},{"id":"d1c0930c41f7854d2d7c5f666262c4356310d43d1e8557fa2d48907912ef4272b36fd6abea6b53b8f80dbd0daf277c8a03ede36b36cfe3dce79da92bea3f5403","href":"https://static.observableusercontent.com/files/d1c0930c41f7854d2d7c5f666262c4356310d43d1e8557fa2d48907912ef4272b36fd6abea6b53b8f80dbd0daf277c8a03ede36b36cfe3dce79da92bea3f5403","name":"image@1.png","type":"image/png","lastModified":1668710425157.454,"size":119505},{"id":"be852d9e294b982f8f4938aad1eab0684e3ecf3900dacbeefce5ef0a8aaaff83a85ed50e95a65b2704c67958d8ec0951281de7ba0f5cc0869e0aeaa2136c0e3b","href":"https://static.observableusercontent.com/files/be852d9e294b982f8f4938aad1eab0684e3ecf3900dacbeefce5ef0a8aaaff83a85ed50e95a65b2704c67958d8ec0951281de7ba0f5cc0869e0aeaa2136c0e3b","name":"image@4.png","type":"image/png","lastModified":1668710425157.454,"size":231356}] 44:{"id":"de6962024d45c055","slug":"bringing-the-typescript-language-server-to-observable","title":"Bringing the TypeScript Language Server to Observable","thumbnail":"5cca673c6f9970391675c9f43574e291480a5379a0910e379b1a382640ab4460","access_level":"public","create_time":"$D2022-11-17T18:40:25.157Z","update_time":"$D2022-12-15T18:49:50.524Z","view_time":null,"first_public_time":"$D2022-11-17T18:45:09.183Z","has_unpublished_edits":null,"fork":true,"stars":30,"starred":false,"owner":{"type":"team","id":"f35c755083683fe5","login":"observablehq","name":"Observable","avatar_url":"https://avatars-next.observableusercontent.com/424c6c1f7794371c9915a160519bdfb34cf34e50069fcd6def38a1a04d4e9702","tier":"enterprise_2024","bio":"The end-to-end solution for building and hosting better data apps, dashboards, and reports."},"version":669,"publish_version":null,"role":null,"authored":false,"authors":[{"type":"individual","id":"83af954252b77055","login":"duaneatat","name":"Duane Millar Barlow","avatar_url":"https://avatars-next.observableusercontent.com/fe811bf60dd25fe5a1a2c15f5477887534931530c69d3837041e9d1df5ea53bf","tier":null,"bio":"Former Engineer @ObservableHQ"}],"members":[{"type":"individual","id":"4530d0072aa49b47","login":"erinn","name":"Erinn Wong","avatar_url":"https://avatars-next.observableusercontent.com/9119ac38e4f1c92d50b28822c47306212f06e085b7d1416e851a1c397194e2d4","tier":null,"role":"editor"},{"type":"individual","id":"074c414ad1d825f5","login":"mbostock","name":"Mike Bostock","avatar_url":"https://avatars-next.observableusercontent.com/7dbba99ced40bd5ab8013c99b1a11da61231bce321ba1148a9d16ad0f121550a","tier":null,"role":"editor"},{"type":"team","id":"f35c755083683fe5","login":"observablehq","name":"Observable","avatar_url":"https://avatars-next.observableusercontent.com/424c6c1f7794371c9915a160519bdfb34cf34e50069fcd6def38a1a04d4e9702","tier":"enterprise_2024","role":"viewer"}],"comments":[{"id":"058215ed2236d84c","reply_to_id":null,"content":"I'm excited about this roadmap. Great work!","create_time":"$D2022-11-21T19:51:16.304Z","update_time":null,"resolved":true,"user":{"type":"individual","id":"284cdf205719c86e","login":"zachperiscopic","name":"Zach Bogart","avatar_url":"https://avatars-next.observableusercontent.com/6f18b0401ce7dbd258bca1afb27a7a9d850d10197a42ad23e35e242ca095a4e9","tier":null}},{"id":"0ae950df6622f771","reply_to_id":"058215ed2236d84c","content":"Thank you! 🙏","create_time":"$D2022-11-28T14:07:17.276Z","update_time":null,"resolved":true,"user":{"type":"individual","id":"83af954252b77055","login":"duaneatat","name":"Duane Millar Barlow","avatar_url":"https://avatars-next.observableusercontent.com/fe811bf60dd25fe5a1a2c15f5477887534931530c69d3837041e9d1df5ea53bf","tier":null}},{"id":"1d086a024cd9879d","reply_to_id":null,"content":"CodeMirror to as","create_time":"$D2022-11-30T16:34:10.703Z","update_time":null,"resolved":true,"user":{"type":"individual","id":"f11356ce54f25c8b","login":"bmershon","name":"Brooks Mershon","avatar_url":"https://avatars-next.observableusercontent.com/5331359238b7666c1cb986b48f8e69f0c357feba767a709324063cd52818c420","tier":null}},{"id":"086020ca9da418bf","reply_to_id":"1d086a024cd9879d","content":"🙏","create_time":"$D2022-11-30T17:04:05.741Z","update_time":null,"resolved":true,"user":{"type":"individual","id":"83af954252b77055","login":"duaneatat","name":"Duane Millar Barlow","avatar_url":"https://avatars-next.observableusercontent.com/fe811bf60dd25fe5a1a2c15f5477887534931530c69d3837041e9d1df5ea53bf","tier":null}}],"custom_thumbnail":true,"trashed":false,"lapsed":null,"subscribed":null,"forks":8,"collection":{"id":"01e1972879c83ae3","slug":"observable-blog","title":"Observable Blog","owner":{"id":"f35c755083683fe5","login":"observablehq","name":"Observable"}},"type":"notebook","body":{"titling":"auto","title":"Bringing the TypeScript Language Server to Observable","cells":[{"id":135,"value":"# Bringing the TypeScript Language Server to Observable\n## Assisting editing with contextual inline documentation","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":137,"value":"FileAttachment(\"Editor_Hints_Blog.png\").image()","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":299,"value":"The editor hints found in popular code editors such as VSCode (_e.g._, autocomplete and embedded documentation) have become indispensable for developers. So, we set out to implement similar functionality within Observable. \n\nWe learned that the architecture that powers VSCode is modular and that the “brains” of VSCode can be used outside of VSCode, even in a browser. After a few twists and turns, we were able to implement editor hints within Observable by integrating with the TypeScript Language Server. \n\nThis is how we did it.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":164,"value":"## An integration hidden in plain sight\n\nCode editors often use the [TypeScript Language Server](https://github.com/typescript-language-server/typescript-language-server) (`tsserver`) to provide editor hints for TypeScript as well as JavaScript. For JavaScript, completions are inferred either from JavaScript source found in the project or from any d.ts files that have been loaded into the project (_e.g._, all of the node or browser APIs). \n\n`tsserver` also consumes any JSDoc annotations it finds in order to display signature help descriptions, as well as any JSDoc _type_ annotations to provide autocompletions, _etc._ \n\nHere is an example from the TypeScript Playground:","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":149,"value":"

Signature help as well as autocompletions via JSDoc. Try it in the TypeScript Playground.

","pinned":false,"hidden":false,"mode":"html","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":204,"value":"The question we had when starting this project was whether we could get these editor hints into Observable, which runs in the browser and uses [CodeMirror](https://codemirror.net/) to as an editor. VSCode is powered by Microsoft’s open-source editor called [Monaco](https://microsoft.github.io/monaco-editor/), so it wasn’t clear how we could integrate with CodeMirror, if at all. Luckily, the Monaco editor is implemented in a modular way, with a clear separation between the editor and the language services.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":206,"value":"The Monaco editor doesn’t do any of the heavy lifting for the editor hints, but is more of the presentation layer that relies on the various language services (`tsserver` being one of them) to get the editor hint information. In theory this means we could either host a TS Language Server that the browser can query, or we could try to run `tsserver` in the browser to remove the round trip over the internet.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":167,"value":"We quickly discovered that `tsserver` has a dependency on the file system in order to read from and write to the various files in a TypeScript (or JavaScript) project, which meant there wouldn’t be a way to run `tsserver` in the browser. It wasn’t until we happened upon this [incredibly helpful CodeMirror forum thread](https://discuss.codemirror.net/t/codemirror-6-and-typescript-lsp/3398/3) that the path forward was clear. The answer was hidden in plain sight: do what the TypeScript Playground does and use [`@typescript/vfs`](https://www.npmjs.com/package/@typescript/vfs) rather than `tsserver`.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":170,"value":"## A little help from Sid\n\nUntil we found the above [CodeMirror forum thread](https://discuss.codemirror.net/t/codemirror-6-and-typescript-lsp/3398/3) and especially the responses by [Sid](https://discuss.codemirror.net/u/madebysid/summary), it hadn’t occurred to us that the [TypeScript Playground](https://www.typescriptlang.org/play) is actually already doing the thing we’re trying to do: run `tsserver` in the browser. We assumed (without ever actually checking) that it must be communicating over the internet with a hosted `tsserver` somewhere. \n\nSid invested a lot of time in that thread outlining how he got the TypeScript language service running in the browser and integrated with CodeMirror. [`@typescript/vfs`](https://www.npmjs.com/package/@typescript/vfs) was developed by Microsoft in order to enable implementation of the TypeScript Playground by removing `tsserver`’s dependency on the file system. (VFS here stands for Virtual File System.)","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":214,"value":"Here we express our gratitude for Sid and Microsoft for paving the way. All that was left for us was to connect everything together. Let's do it now!","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":327,"value":"## Try it yourself\n\nFirst, we import `typescript` and `@typescript/vfs`.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":330,"value":"vfs = import(\"https://cdn.jsdelivr.net/npm/@typescript/vfs@1.4.0/+esm\")","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":332,"value":"ts = (await import(\"https://cdn.jsdelivr.net/npm/typescript@4.8.4/+esm\")).default","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":334,"value":"Then we initialize a \"Virtual TypeScript Environment\". \n\nThis uses the `createDefaultMapFromCDN` function which will load all of the browser `lib.*.d.ts` files, which is how we have types and documentation for browser APIs like `document.querySelector()`.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":336,"value":"tsEnv = {\n storage;\n const {createSystem, createVirtualTypeScriptEnvironment, createDefaultMapFromCDN} = vfs;\n const fsMap = await createDefaultMapFromCDN({target: ts.ScriptTarget.ES2021}, ts.version, true, ts);\n const system = createSystem(fsMap);\n const tsEnv = createVirtualTypeScriptEnvironment(system, [], ts, {allowJs: true});\n tsEnv.createFile(\"/index.js\", \" \"); // This is where our code will go. Note: can’t be empty 😅\n return tsEnv;\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":339,"value":"As long as we keep the virtual TypeScript environment in sync with our editor, we will be able to leverage all of the smarts that the language server provides. \n\nOur editor in this notebook will be an html textarea (with a little extra to emit changes to the cursor offset as well). We will also query the language service for any auto completions we can show.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":360,"value":"completions = {\n tsEnv.updateFile(\"/index.js\", editor1.code || \" \");\n return tsEnv.languageService.getCompletionsAtPosition(\"/index.js\", editor1.offset, {});\n}","pinned":true,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":347,"value":"viewof editor1 = InputWithSelection(\"const foo = {a: 1, b: 2};\\nfoo.\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":357,"value":"Completions at position ${editor1.offset}: ${completions ? completions.entries.slice(0, 5).map(({name}) => name).join(\", \") : \"no completions\"}","pinned":false,"hidden":false,"mode":"html","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"completions2","database":"$undefined"},{"id":375,"value":"We can also get signature help items.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"completions3","database":"$undefined"},{"id":379,"value":"help = {\n tsEnv.updateFile(\"/index.js\", editor2.code || \" \");\n return tsEnv.languageService.getSignatureHelpItems(\"/index.js\", editor2.offset, {});\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":385,"value":"viewof editor2 = InputWithSelection(\"document.getElementById(\")","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":389,"value":"signature = displayHelpItems(help, editor2.offset);","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":176,"value":"We represent each cell in a notebook as a separate file in the VFS, and keep the TypeScript virtual environment in sync with changes made in the CodeMirror cell editors. \n\nThen, we can query the language service for signature help and autocompletions at any position in the CodeMirror editor. What remains is simply the UI work around integrating these autocompletions and signature help items with CodeMirror. \n\nFortunately, CodeMirror has very robust frameworks for both [autocompletions](https://codemirror.net/examples/autocompletion/) as well as [tooltips](https://codemirror.net/examples/tooltip/).","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":220,"value":"Next, we moved the virtual TypeScript environment to a WebWorker. That way, we could then take advantage of [Webpack 5’s automatic code-splitting for WebWorkers](https://webpack.js.org/guides/web-workers/) to ensure that the download of the virtual TypeScript environment and the download of the Observable application would be done separately. \n\nThis also alleviated concerns about performance because [WebWorkers are run in a separate thread](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Using_web_workers), so any heavy lifting that the TypeScript language service is doing will not block the main thread and the UI will still be responsive.","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":224,"value":"\nNow, when we use native browser APIs in a cell, we get the autocompletions and signature help:\n","pinned":false,"hidden":false,"mode":"md","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"","database":"$undefined"},{"id":143,"value":"

${signaturePrefix}${signatureParameters}${signatureSuffix}

${ts.displayPartsToString(item.documentation)}

\n Signature help at position ${offset}:

\n      ${\n        !help\n          ? \"no help items\"\n          : displayHelpItem(help.items[help.selectedItemIndex])\n      }\n

`;\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":666,"value":"storage = {\n Object.defineProperty(window, \"localStorage\", {value: localStorage});\n return localStorage;\n}","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"},{"id":665,"value":"import {localStorage} from \"@mbostock/safe-local-storage\"","pinned":false,"hidden":false,"mode":"ojs","author":"$undefined","summary":"$undefined","tool":"$undefined","providerMetadata":"$undefined","attachments":"$undefined","output":"$undefined","database":"$undefined"}],"files":"$W46","stdlib":"1"}} 45:"$44:body"