# TanStack Notebook

> Author, run, edit, and share browser-only JavaScript, TypeScript, JSX, and TSX projects at https://tanstack.com/notebook.

## One-file compatibility mode

Existing `#code=` notebook links use this contract:

- Write one client-side TSX ECMAScript module. esbuild removes TypeScript types and transforms JSX; it does not type-check.
- Use static imports from the aliases below or full HTTPS ESM URLs. Remote modules and fetch requests must allow CORS.
- Export a default DOM Node, value, or function. A default function receives the output element and may render into it or return a value.

### Starter TSX module

```tsx
import { useState } from 'react'
import { createRoot } from 'react-dom/client'

function App() {
  const [count, setCount] = useState<number>(0)

  return (
    <button onClick={() => setCount((value) => value + 1)}>
      Count: {count}
    </button>
  )
}

export default function render(output: HTMLElement) {
  createRoot(output).render(<App />)
}
```

## Import aliases

- `react`: React 19.2.3.
- `react-dom/client`: React DOM root API.
- `@tanstack/charts`: TanStack Charts core.
- `@tanstack/charts/react`: TanStack Charts React bindings.
- `@tanstack/charts/octane`: TanStack Charts Octane bindings.
- `octane`: Octane 0.1.13 runtime.
- `@tanstack/charts-data/`: TanStack Charts demo data; append a module path.
- `@tanstack/highlight`: TanStack Highlight.
- `@tanstack/markdown`: TanStack Markdown.
- `@tanstack/pacer`: TanStack Pacer.
- `@tanstack/react-pacer`: TanStack Pacer React bindings.
- `@tanstack/react-query`: TanStack Query.
- `@tanstack/react-router`: TanStack Router.
- `@tanstack/react-table`: TanStack Table.
- `d3-array`: D3 array utilities.
- `d3-geo`: D3 geographic projections.
- `d3-scale`: D3 scales.
- `d3-shape`: D3 shape generators.

Full HTTPS ESM URLs are also supported.

## Browser environment

- The module runs in a fresh sandboxed iframe with browser APIs, DOM, Canvas, SVG, WebGL, fetch, timers, and ResizeObserver.
- Node.js APIs, filesystem access, process, server secrets, and parent-page DOM access are unavailable.
- Each run replaces the iframe, so listeners, timers, React roots, and other runtime state are discarded automatically.
- console.log, info, warn, error, and debug are mirrored to the optional Console panel.

## Multi-file workspace contract

- A workspace is JSON with version 1, an absolute entry path, a files object keyed by canonical absolute paths, an optional environment, and an optional imports object.
- The entry module executes in the browser. esbuild-wasm transforms TypeScript and JSX; octane/compiler transforms .tsrx files first. Neither path type-checks source.
- Relative imports resolve inside files. CSS and JSON imports are bundled. Browser-safe image and font imports become data URLs.
- Bare dependencies in /package.json resolve through esm.sh. Explicit workspace imports override both package.json and the built-in aliases.
- Add /index.html only when the example needs a custom document. The runtime injects its import map, compiled CSS, module, console bridge, and theme bridge.

```json
{
  "version": 1,
  "entry": "/src/main.tsx",
  "files": {
    "/src/main.tsx": "import { App } from './App'\n// mount App",
    "/src/App.tsx": "export function App() { return <h1>Hello</h1> }"
  },
  "imports": {
    "react": "https://esm.sh/react@19.2.3"
  }
}
```

## Live documentation fences

- A runnable documentation example is a consecutive group of fenced code blocks with the same group identifier.
- Every fence must include an explicit canonical absolute file path. Exactly one fence has the entry flag, and that fence carries the group's only env declaration.
- Supported environments are charts, charts-react, and charts-octane. Their hidden bootstrap mounts the entry module's default export.
- Add the collapsed flag to support files that should remain under a disclosure until the reader opens them.
- The static highlighted fences are rendered on the server. The editor and esbuild runtime load only after the reader selects Run.

````md
```tsx group=counter env=charts-react file=/src/App.tsx entry
export default function App() { return <button>Count</button> }
```

```ts group=counter file=/src/data.ts collapsed
// imported source
```
````

## Theme

- The iframe root has either a light or dark class and follows the TanStack site theme after every run.
- Use --notebook-background and --notebook-foreground for theme-aware colors. Use --notebook-error for errors.

## Sharing protocol

The original one-file notebook URL remains supported:

`https://tanstack.com/notebook?title=<title>&description=<description>#code=<source>`

To produce `<source>`, UTF-8 encode the TSX module, gzip the bytes, encode them as base64url, and omit `=` padding.

Small multi-file projects use `https://tanstack.com/notebook#project=<project>`. The decoded JSON and the large-project POST body are exactly `{ "version": 1, "title": string, "description": string, "workspace": <workspace> }`. Encode and decode it with the same UTF-8, gzip, and unpadded base64url process.

URL fragments are not sent to the HTTP server. Agents given a `#code` or `#project` URL must decode the fragment locally.

Large projects use `https://tanstack.com/notebook/p/<sha256>`. Read their canonical JSON without executing it at `GET https://tanstack.com/api/notebook/projects/<sha256>`. Reads are public and unlisted. Writes are immutable, authenticated, same-origin, and rate-limited through `POST https://tanstack.com/api/notebook/projects`.

Git remains canonical for documentation and catalog examples. Shared URLs are immutable forks and one-off projects.

## Tips

- Render inside the provided output element. Do not replace document.body.
- Make the result responsive to its container. ResizeObserver is available for charts, canvas, and WebGL scenes.
- Use one file for small modules. Use a workspace when separate components, styles, data, assets, or a custom document make the example clearer.
- Use console output for diagnostics that should remain available without opening browser developer tools.