{"id":13454213,"url":"https://github.com/githubnext/vitale","last_synced_at":"2025-09-09T23:38:44.080Z","repository":{"id":243098340,"uuid":"779042541","full_name":"githubnext/vitale","owner":"githubnext","description":"TypeScript notebook for developers","archived":false,"fork":false,"pushed_at":"2024-12-14T22:28:05.000Z","size":543,"stargazers_count":234,"open_issues_count":25,"forks_count":8,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-24T05:03:10.371Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://githubnext.com/projects/vitale/","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/githubnext.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2024-03-28T23:19:54.000Z","updated_at":"2025-05-12T18:41:48.000Z","dependencies_parsed_at":"2024-06-06T18:44:14.402Z","dependency_job_id":"2122d1cb-0a00-4b1a-8757-ad8d3f01dbe9","html_url":"https://github.com/githubnext/vitale","commit_stats":null,"previous_names":["githubnext/vitale"],"tags_count":14,"template":false,"template_full_name":null,"purl":"pkg:github/githubnext/vitale","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/githubnext%2Fvitale","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/githubnext%2Fvitale/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/githubnext%2Fvitale/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/githubnext%2Fvitale/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/githubnext","download_url":"https://codeload.github.com/githubnext/vitale/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/githubnext%2Fvitale/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":274383848,"owners_count":25275186,"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","status":"online","status_checked_at":"2025-09-09T02:00:10.223Z","response_time":80,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2024-07-31T08:00:51.893Z","updated_at":"2025-09-09T23:38:44.025Z","avatar_url":"https://github.com/githubnext.png","language":"TypeScript","funding_links":[],"categories":["others","TypeScript"],"sub_categories":[],"readme":"![hero](./assets/hero.png)\n\n# Vitale\n\n`vitale` is a VS Code notebook implementation for Node.js + TypeScript. It\nsupports\n\n- automatic re-execution of dependent cells\n- splitting cell outputs into a separate pane\n- rendering React components\n\nIt uses `vite` for compilation and hot-reloading, so you can process code with\nstandard `vite` plugins.\n\n## Installation\n\n1.  Install the `.vsix` from the latest release:\n\n    - go to https://github.com/githubnext/vitale/releases\n    - look for the latest release (at the top)\n    - download the `vitale-vscode-[version].vsix` file\n    - run `code --install-extension vitale-vscode-[version].vsix` (or run\n      `Extensions: Install from VSIX...` from the command palette)\n\n2.  Install the `@githubnext/vitale` package in your project:\n\n    - `pnpm add -D @githubnext/vitale` (or equivalent in `npm` or `yarn` etc.)\n\n      The details of the RPC protocol between extension and server change frequently,\n      so you should use matching versions.\n\n3.  (Optional) Install the `@githubnext/typescript` package in your project:\n\n    - `pnpm add -D typescript@npm:@githubnext/typescript`\n\n      This is a patched version of of TypeScript 5.4.5 which hacks in support\n      for the pathnames that VS Code uses for notebook cells. (With stock\n      TypeScript, `tsserver` can't find the `tsconfig.json` and can't find\n      referenced project files, so you lose typings and get a lot of spurious\n      squiggle. More at https://github.com/microsoft/vscode/issues/213740)\n\n## Getting started\n\nFor background on the VS Code notebook UI see [Jupyter Notebooks in VS\nCode](https://code.visualstudio.com/docs/datascience/jupyter-notebooks) (but\nignore the stuff about Jupyter specifically).\n\nTo make a `vitale` notebook, create a new file with a `.vnb` extension.\n\nA cell can contain a single expression, or a sequence of statements where the\nlast statement is an expression. (Note that an object literal in statement\nposition must be wrapped in parentheses to avoid being parsed as a block.)\n\nThe output of a cell is the value of the expression; if there's no trailing\nexpression or the value of the expression is undefined there's no output. If the\nvalue of the expression is a promise, it will be `await`ed automatically; if the\nvalue of the expression is an iterator or async iterator, it will be iterated\nand the cell output replaced with each value as it arrives.\n\nOrdinarily cells are executed server-side in a Node environment, but see below\nabout client-side rendering.\n\n## Defining and referencing variables\n\nVariables defined at the top level in a cell are available to other cells (once\nthe defining cell has been executed). If you want a variable to be private to a\ncell (e.g. to avoid colliding with another definition), define it inside a block.\n\nRe-executing a cell that defines variables used in other cells will cause the\ndependent cells to be re-executed automatically. If you don't want this behavior\nfor some reason (e.g. you have a long-running cell) you can use the\n![pause](./assets/CodiconDebugPause.svg) /\n![play](./assets/CodiconDebugStart.svg) buttons in the cell status bar to pause\nand restart execution; or if you want to turn it off globally you can uncheck\nthe \"Vitale: Rerun Cells When Dirty\" setting.\n\n## Importing modules\n\nYou can import installed modules as usual, e.g.\n\n```ts\nimport { Octokit } from \"@octokit/core\";\n```\n\nImports are visible in other cells once the importing cell has been executed.\n\nYou can also import project files with a path relative to the notebook file,\ne.g.\n\n```ts\nimport { foo } from \"./bar.ts\";\n```\n\nand changes to the imported file will cause dependent cells to re-execute as\nabove.\n\n## Output panes\n\nCell output is displayed below the cell. You can open the output in a separate\npane by clicking the ![preview](./assets/CodiconOpenPreview.svg) button in the\ncell toolbar. Output in a separate pane is updated when the cell is re-executed\nor when dependencies change.\n\n## Rendering different MIME types\n\n`vitale` inspects the output value and tries to pick an appropriate MIME type to\nrender it. For most Javascript objects this is `application/json`, which is\nrendered by VS Code with syntax highlighting. For complex objects you can render\nan expandable view (using\n[react-json-view](https://github.com/uiwjs/react-json-view)) by returning the\n`application/x-json-view` MIME type. `HTMLElement` and `SVGElement` objects are\nrendered as `text/html` and `image/svg+xml` respectively (see below for an\nexample).\n\nTo set the MIME type of the output explicitly, return an object of type `{ data:\nstring, mime: string }` (currently there's no way to return binary data). VS\nCode has several built-in renderers (see [Rich\nOutput](https://code.visualstudio.com/api/extension-guides/notebook#rich-output))\nand you can install others as extensions.\n\nThere are helper functions in `@githubnext/vitale` to construct these\nMIME-tagged outputs:\n\n```ts\nfunction text(data: string);\nfunction stream(data: string); // application/x.notebook.stream\nfunction textHtml(data: string); // text/x-html\nfunction textJson(data: string); // text/x-json\nfunction textMarkdown(data: string); // text/x-markdown\nfunction markdown(data: string);\nfunction html(html: string | { outerHTML: string });\nfunction svg(html: string | { outerHTML: string });\nfunction json(obj: object);\nfunction jsonView(obj: object);\n```\n\nThis package is auto-imported under the name `Vitale` in notebook cells, so you can write e.g.\n\n```ts\nVitale.jsonView({ foo: \"bar\" });\n```\n\nbut you may want to import it explicitly to get types for auto-complete.\n\nYou can construct `HTMLElement` and `SVGElement` values using `jsdom` or a\nsimilar library; for example, to render an SVG from [Observable\nPlot](https://observablehq.com/plot/):\n\n```ts\nimport * as Plot from \"@observablehq/plot\";\nimport { JSDOM } from \"jsdom\";\nconst { document } = new JSDOM().window;\n\nconst xs = Array.from({ length: 20 }, (_, i) =\u003e i);\nconst xys = xs.map((x) =\u003e [x, Math.sin(x / Math.PI)]);\n\nPlot.plot({\n  inset: 10,\n  marks: [Plot.line(xys)],\n  document,\n});\n```\n\n## Rendering React components\n\nTo render a React component, write it as the last expression in a cell, like\n\n```tsx\nconst Component = () =\u003e \u003cdiv\u003eHello, world!\u003c/div\u003e;\n\n\u003cComponent /\u003e;\n```\n\nYou can also import a component from another cell or from a project file, and\nediting an imported component will trigger a hot reload of the rendered output.\n(This uses Vite's hot-reloading mechanism, so it can't be paused as with\nserver-side re-execution.)\n\n## Client-side rendering without React\n\nTo render a cell client-side, add `\"use client\"` at the top of the cell. A\nvariable `__vitale_cell_output_root_id__` is defined to be the ID of a DOM\nelement for the cell's output.\n\n```ts\n\"use client\";\n\ndocument.getElementById(__vitale_cell_output_root_id__).innerText =\n  \"Hello, world!\";\n```\n\nIt should be possible to render non-React frameworks this way but I haven't\ntried it.\n\n## Logging\n\nStandard output and error streams are captured when running cells and sent to a\nper-cell output channel. Press the ![output](./assets/CodiconOutput.svg) button\nin the cell toolbar to view the channel.\n\n## Environment variables\n\n`vitale` inherits the environment variable setup from Vite, see [Env Variables\nand Modes](https://vitejs.dev/guide/env-and-mode.html).\n\nSince code in cells is transformed by Vite, you need to prefix variables with\n`VITE_` in order for them to be visible.\n\n## VS Code API\n\nYou can call some of the VS Code API from cells using functions in `@githubnext/vitale`:\n\n```ts\ngetSession(\n  providerId: string,\n  scopes: readonly string[],\n  options: vscode.AuthenticationGetSessionOptions\n): Promise\u003cvscode.AuthenticationSession\u003e;\n\nshowInformationMessage\u003cstring\u003e(\n  message: string,\n  options: vscode.MessageOptions,\n  ...items: string[]\n): Promise\u003cstring | undefined\u003e;\nshowWarningMessage\u003cstring\u003e(\n  message: string,\n  options: vscode.MessageOptions,\n  ...items: string[]\n): Promise\u003cstring | undefined\u003e;\nshowErrorMessage\u003cstring\u003e(\n  message: string,\n  options: vscode.MessageOptions,\n  ...items: string[]\n): Promise\u003cstring | undefined\u003e;\n```\n\n## Development\n\nTo develop Vitale:\n\n- `git clone https://github.com/githubnext/vitale.git`\n- `cd vitale; pnpm install`\n- open the project in VS Code, press `F5` to run\n\nThe server needs to be installed in whatever project you're testing with. You\ncan install the published server as above, or to link to the development\nversion:\n\n- `cd packages/server; pnpm link --dir $YOURPROJECT`\n\nThe linked development server is automatically rebuilt but not hot-reloaded; you\ncan get the latest changes by restarting the server (run `Vitale: Restart\nKernel` from the command palette).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithubnext%2Fvitale","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithubnext%2Fvitale","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithubnext%2Fvitale/lists"}