{"id":26909875,"url":"https://github.com/stack-spot/vscode-async-webview","last_synced_at":"2025-08-24T19:45:07.850Z","repository":{"id":187555937,"uuid":"674248521","full_name":"stack-spot/vscode-async-webview","owner":"stack-spot","description":"A utility for making it easier to implement web views within VSCode extensions","archived":false,"fork":false,"pushed_at":"2024-07-18T12:38:07.000Z","size":4799,"stargazers_count":8,"open_issues_count":3,"forks_count":1,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-03-01T06:34:54.606Z","etag":null,"topics":["code","extension","genai","maintain","react","vscode","webview"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/stack-spot.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-08-03T13:33:55.000Z","updated_at":"2025-02-06T10:23:25.000Z","dependencies_parsed_at":"2024-03-19T20:02:32.477Z","dependency_job_id":null,"html_url":"https://github.com/stack-spot/vscode-async-webview","commit_stats":null,"previous_names":["stack-spot/vscode-async-webview"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stack-spot%2Fvscode-async-webview","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stack-spot%2Fvscode-async-webview/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stack-spot%2Fvscode-async-webview/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/stack-spot%2Fvscode-async-webview/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/stack-spot","download_url":"https://codeload.github.com/stack-spot/vscode-async-webview/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246647123,"owners_count":20811257,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["code","extension","genai","maintain","react","vscode","webview"],"created_at":"2025-04-01T13:29:51.472Z","updated_at":"2025-04-01T13:29:52.196Z","avatar_url":"https://github.com/stack-spot.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Introduction\nThis is a utility for making it easier to implement web views within VSCode extensions. In summary, this abstracts all the message traffic\nbetween the iframes into an easy to use asynchronous API. Furthermore, it simplifies the injection of a full web app into the extension\nwithout the need of writing HTML strings or specific VSCode code in the web app.\n\nThis document is aimed at users of this library. If you want to read the document for developers, please, read [this text](developer.md)\ninstead.\n\n# Motivation\nI've recently inherited a VSCode extension project that heavily relied on a webview. After a deep analysis of the code, I noticed:\n- The HTML injection part of the process was very complex and relied a lot in the function `asWebviewUri`, making it very hard to add\nnew resources to the project.\n- The communication between the webview and the extension was very complex, verbose, non-intuitive and prone to errors. Untyped states,\nmessages with strings mostly untyped, explicit calls to `postMessage` and manual registration of listeners really didn't help.\n\nI needed to elevate the extension to a production level of quality and make it something easy to maintain. I had no doubt I had to scrap\nthe current project and develop a framework to work on top of the API provided by VSCode. This is this framework.\n\nThis is a very new project and the extension we're building on top of it will probably be released next month. As soon as we have a stable\nrelease, I'll put a link to it in here.\n\nThe results, for now, have been very satisfactory. The actual code for our extension is super simple and focus on the logic of the\nextension, never on details of how to communicate two different applications.\n\n# Development stage\nThis is currently on Alpha. I'll be moving it to beta as soon as we release the first version of our extension and it's live on the VSCode\nstore.\n\nThis will have a stable release (1.0.0) when we have at least 80% of test coverage.\n\n# Disclaimer\nThis documentation assumes you're already familiar with the basics of the \n[vscode documentation for creating an extension](https://code.visualstudio.com/api).\n\n# Example\nWe're going to focus on a very simple example where the webview shows a VSCode notification and the VSCode notification interacts with the\nwebview state. See the video below.\n\nhttps://github.com/stack-spot/vscode-async-webview/assets/1119029/ca63df34-3d93-43a3-9055-de64e55fa416\n\n## Extension\n### `extension/src/extension.ts`:\n```ts\nimport * as vscode from 'vscode'\nimport { VSCodeWebview } from '@stack-spot/vscode-async-webview-backend'\nimport { Bridge } from './Bridge'\n\nexport function activate(context: vscode.ExtensionContext) {\n  const webview = new VSCodeWebview({\n    type: 'myExtension',\n    path: 'packages/webview',\n    title: 'My Extension',\n    bridgeFactory: (webview) =\u003e new Bridge(webview),\n    context,\n  })\n\n  let disposable = vscode.commands.registerCommand('myExtension.start', () =\u003e {\n    webview.show()\n  })\n\n  context.subscriptions.push(disposable)\n}\n```\n\n### `extension/src/Bridge.ts`:\nThis is the class that makes the bridge between the two applications.\n\n```ts\nimport { VSCodeWebviewBridge } from '@stack-spot/vscode-async-webview-backend'\nimport { ViewState } from './ViewState'\nimport { window } from 'vscode'\n\nexport class Bridge extends VSCodeWebviewBridge\u003cViewState\u003e {\n  async showMessage(message: string) {\n    const action = await window.showInformationMessage(message, 'reset counter', 'close')\n    if (action === 'reset counter') {\n      this.state.set('counter', 0)\n    }\n  }\n}\n```\n\n### `extension/src/ViewState.ts`:\nThis file declares the state shared between the two applications:\n\n```ts\nexport interface ViewState {\n  counter?: number,\n}\n```\n\n## Webview\nThis example has been created with React, but you can use anything as your frontend framework.\n\n### `webview/src/vscode.ts`:\nThis file makes the basic setup for using the lib.\n\n```ts\nimport { VSCodeWeb, VSCodeWebInterface } from '@stack-spot/vscode-async-webview-client'\nimport { createVSCodeHooks } from '@stack-spot/vscode-async-webview-react'\nimport type { Bridge } from 'extension/Bridge'\n\nexport const vscode: VSCodeWebInterface\u003cBridge\u003e = new VSCodeWeb\u003cBridge\u003e({})\nconst vsHooks = createVSCodeHooks(vscode)\nexport const useBridgeState = vsHooks.useState\n```\n\n### `webview/src/App.tsx`:\nMost of the code here is [Vite's](https://vitejs.dev/) boilerplate. Pay attention to whenever we use `vscode.bridge` and `useBridgeState`,\nthese are the two structures used in the frontend in order to communicate with the extension.\n\n```tsx\nimport reactLogo from './assets/react.svg'\nimport viteLogo from '/vite.svg'\nimport './App.css'\nimport { useBridgeState, vscode } from './vscode'\n\nfunction App() {\n  const [count = 0, setCount] = useBridgeState('counter')\n\n  return (\n    \u003c\u003e\n      \u003cdiv\u003e\n        \u003ca href=\"https://vitejs.dev\" target=\"_blank\"\u003e\n          \u003cimg src={viteLogo} className=\"logo\" alt=\"Vite logo\" /\u003e\n        \u003c/a\u003e\n        \u003ca href=\"https://react.dev\" target=\"_blank\"\u003e\n          \u003cimg src={reactLogo} className=\"logo react\" alt=\"React logo\" /\u003e\n        \u003c/a\u003e\n      \u003c/div\u003e\n      \u003ch1\u003eVite + React\u003c/h1\u003e\n      \u003cdiv className=\"card\"\u003e\n        \u003cbutton onClick={() =\u003e {\n          setCount(count + 1)\n          vscode.bridge.showMessage(`The counter is at: ${count + 1}.`)\n        }}\u003e\n          count is {count}\n        \u003c/button\u003e\n        \u003cp\u003e\n          Edit \u003ccode\u003esrc/App.tsx\u003c/code\u003e and save to test HMR\n        \u003c/p\u003e\n      \u003c/div\u003e\n      \u003cp className=\"read-the-docs\"\u003e\n        Click on the Vite and React logos to learn more\n      \u003c/p\u003e\n    \u003c/\u003e\n  )\n}\n\nexport default App\n```\n\n## Full example\nYou can find the full example in our [sample project](https://github.com/Tiagoperes/vscode-async-webview-sample).\n\n# Docs\n- [Getting started](https://github.com/stack-spot/vscode-async-webview/blob/main/docs/getting-started.md)\n- [Backend library](https://github.com/stack-spot/vscode-async-webview/blob/main/docs/backend.md)\n- [Client library](https://github.com/stack-spot/vscode-async-webview/blob/main/docs/client.md)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstack-spot%2Fvscode-async-webview","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fstack-spot%2Fvscode-async-webview","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fstack-spot%2Fvscode-async-webview/lists"}