vitale

/ buttons in the cell status bar to pause and restart execution; or if you want to turn it off globally you can uncheck the "Vitale: Rerun Cells When Dirty" setting.

Importing modules

You can import installed modules as usual, e.g.

import { Octokit } from "@octokit/core";

Imports are visible in other cells once the importing cell has been executed.

You can also import project files with a path relative to the notebook file, e.g.

import { foo } from "./bar.ts";

and changes to the imported file will cause dependent cells to re-execute as above.

Output panes

Cell output is displayed below the cell. You can open the output in a separate pane by clicking the button in the cell toolbar. Output in a separate pane is updated when the cell is re-executed or when dependencies change.

Rendering different MIME types

vitale inspects the output value and tries to pick an appropriate MIME type to render it. For most Javascript objects this is application/json, which is rendered by VS Code with syntax highlighting. For complex objects you can render an expandable view (using react-json-view) by returning the application/x-json-view MIME type. HTMLElement and SVGElement objects are rendered as text/html and image/svg+xml respectively (see below for an example).

To set the MIME type of the output explicitly, return an object of type { data: string, mime: string } (currently there's no way to return binary data). VS Code has several built-in renderers (see Rich Output) and you can install others as extensions.

There are helper functions in @githubnext/vitale to construct these MIME-tagged outputs:

function text(data: string);
function stream(data: string); // application/x.notebook.stream
function textHtml(data: string); // text/x-html
function textJson(data: string); // text/x-json
function textMarkdown(data: string); // text/x-markdown
function markdown(data: string);
function html(html: string | { outerHTML: string });
function svg(html: string | { outerHTML: string });
function json(obj: object);
function jsonView(obj: object);

This package is auto-imported under the name Vitale in notebook cells, so you can write e.g.

Vitale.jsonView({ foo: "bar" });

but you may want to import it explicitly to get types for auto-complete.

You can construct HTMLElement and SVGElement values using jsdom or a similar library; for example, to render an SVG from Observable Plot:

import * as Plot from "@observablehq/plot";
import { JSDOM } from "jsdom";
const { document } = new JSDOM().window;

const xs = Array.from({ length: 20 }, (_, i) => i);
const xys = xs.map((x) => [x, Math.sin(x / Math.PI)]);

Plot.plot({
  inset: 10,
  marks: [Plot.line(xys)],
  document,
});

Rendering React components

To render a React component, write it as the last expression in a cell, like

const Component = () => <div>Hello, world!</div>;

<Component />;

You can also import a component from another cell or from a project file, and editing an imported component will trigger a hot reload of the rendered output. (This uses Vite's hot-reloading mechanism, so it can't be paused as with server-side re-execution.)

Client-side rendering without React

To render a cell client-side, add "use client" at the top of the cell. A variable __vitale_cell_output_root_id__ is defined to be the ID of a DOM element for the cell's output.

"use client";

document.getElementById(__vitale_cell_output_root_id__).innerText =
  "Hello, world!";

It should be possible to render non-React frameworks this way but I haven't tried it.

Logging

Standard output and error streams are captured when running cells and sent to a per-cell output channel. Press the button in the cell toolbar to view the channel.

Environment variables

vitale inherits the environment variable setup from Vite, see Env Variables and Modes.

Since code in cells is transformed by Vite, you need to prefix variables with VITE_ in order for them to be visible.

VS Code API

You can call some of the VS Code API from cells using functions in @githubnext/vitale:

getSession(
  providerId: string,
  scopes: readonly string[],
  options: vscode.AuthenticationGetSessionOptions
): Promise<vscode.AuthenticationSession>;

showInformationMessage<string>(
  message: string,
  options: vscode.MessageOptions,
  ...items: string[]
): Promise<string | undefined>;
showWarningMessage<string>(
  message: string,
  options: vscode.MessageOptions,
  ...items: string[]
): Promise<string | undefined>;
showErrorMessage<string>(
  message: string,
  options: vscode.MessageOptions,
  ...items: string[]
): Promise<string | undefined>;

Development

To develop Vitale:

• git clone https://github.com/githubnext/vitale.git
• cd vitale; pnpm install
• open the project in VS Code, press F5 to run

The server needs to be installed in whatever project you're testing with. You can install the published server as above, or to link to the development version:

• cd packages/server; pnpm link --dir $YOURPROJECT

The linked development server is automatically rebuilt but not hot-reloaded; you can get the latest changes by restarting the server (run Vitale: Restart Kernel from the command palette).