# TanStack Notebook

> Author and share one-file client-side TypeScript and JSX modules at https://tanstack.com/notebook.

## Module 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/react-charts`: TanStack Charts React bindings.
- `@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.

## 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

A notebook URL has this form:

`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. To read a shared notebook, reverse those steps. URL fragments are not sent to the HTTP server, so agents must decode `#code` from the supplied URL locally.

The editor debounces source changes into the current URL. `?view=code` only controls whether the code panel is visible.

## 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.
- Keep data and code in the single module when possible. Shared URLs carry the entire source in the fragment.
- Use console output for diagnostics that should remain available without opening browser developer tools.