# Developing NiiVue

> Set up the niivue/mono monorepo, run the example pages and checks, and work on this documentation site.

NiiVue lives in the [niivue/mono](https://github.com/niivue/mono) monorepo
with its React bindings, extensions, demo apps and this site. The tools are
Bun (package manager and runtime), Nx (task runner with caching), Vite and
Biome (lint and format). Use `bun` and `bunx`, not `npm` or `npx`.

## Setup

The sample images are stored with Git LFS, so pull them after cloning:

```bash
git clone https://github.com/niivue/mono.git
cd mono
git lfs install
git lfs pull
bun install
```

## The example pages

The pages in `packages/niivue/examples` are the main way to work on the
library. They import `../src/index.ts` directly, so an edit to the source
reloads the page at once:

```bash
cd packages/niivue
bun run dev
```

This serves the examples at `http://localhost:5273/examples/index.html`,
with the sample volumes and meshes under `/volumes/` and `/meshes/`. From
the repository root, `bunx nx dev niivue` starts the same pages through Nx
(it uses the Vite config's port, so check the URL it prints).

To add an example, write the `.html` page (and a `.js` beside it if the
script is long), then add a link to it in `examples/index.html`. That link
is also what puts the page in this site's [Gallery](https://niivue.com/docs/gallery/).

## Tests and checks

The `niivue` package uses the Bun test runner, with tests next to the
source as `*.test.ts`:

```bash
bunx nx test niivue
cd packages/niivue && bun test   # or run Bun directly
```

Before you open a pull request, run the checks CI runs. From the root:

```bash
bunx nx affected -t format
bunx nx affected -t lint
bunx nx affected -t typecheck
bunx nx affected -t test
bunx nx affected -t build
bun run check-boundaries
```

`nx affected` runs only the projects your branch changed. On `main`, name
the project instead, as in `bunx nx run niivue:lint`. CI also spell-checks
`packages/niivue` with codespell. The repository's
[AGENTS.md](https://github.com/niivue/mono/blob/main/AGENTS.md) and
[CONTRIBUTING.md](https://github.com/niivue/mono/blob/main/CONTRIBUTING.md)
cover code style, commit messages and the rest of the workflow.

## About this site

The site is an [Astro](https://astro.build/) app using the
[Starlight](https://starlight.astro.build/) docs theme, in `apps/docs` (the
Nx project `docs-site`). Its pages come from the packages: each package
keeps its docs in its own `docs` folder, and the site collects them. The
NiiVue guides are in `packages/niivue/docs/guide`. Link between pages with
root-relative URLs such as `/guide/meshes/` or `/gallery/sync/`; the build
adds the site's base path.

### Package docs

Every package except `dev-images` has a group under Packages in the
sidebar. The `niivue` group points to the guides above; every other
package's pages are built from `packages/<folder>/docs`:

- `docs/index.mdx` is required. It becomes `/packages/<folder>/`; another
  page, `docs/hosts.mdx` say, becomes `/packages/<folder>/hosts/`.
- Each page needs a `title` and a `description` in its frontmatter; the
  index's title is the package name. `sidebar: { order: N }` sets the order
  of the other pages.
- Each package is a collapsed sidebar group, named in `PACKAGES` in
  `apps/docs/src/sidebar.ts`: its index first, as Overview, then its other
  pages. A new package must be added there, or the build fails.
- Files starting with `_` are skipped. Notes that are not for the site,
  such as design docs and TODO lists, go in the package's `notes` folder.

Write the docs the way you would explain the package to a colleague who
has never used it. Start with what it does and how to install it, show a
small example that works, then add a section for each thing people
commonly do with it. Give sections names like "Loading a slide" rather
than the name of a function. Keep code examples short, and make sure
everything you write matches the code.

Each live demo is a small module in `apps/docs/src/demos`. It receives a
canvas, a helper for the control bar, and an `asset()` function that
resolves sample file paths, and it returns the viewer it made.
`src/components/Demo.astro` runs it in the browser. The page does not show
the module's code; the Gallery has the full code of every example. A guide
embeds a demo by its file name:

```mdx
import Demo from '@site/components/Demo.astro'

<Demo name="meshes" />
```

The Gallery is generated at build time by `apps/docs/src/lib/gallery.ts`,
through the `gallery` content collection in `src/content.config.ts`.
It reads the sections and links of `packages/niivue/examples/index.html` for
the order, grouping and titles. It then builds the repository knowledge
graph (`bun run graph:build`, described in
[KNOWLEDGE_GRAPH.md](https://github.com/niivue/mono/blob/main/KNOWLEDGE_GRAPH.md)),
which records the scripts each HTML page loads, and shows the page's inline
script plus those files, with the library imports rewritten to
`@niivue/niivue`. A new example appears in the Gallery once it is linked
from `examples/index.html`; there is nothing else to register.

The images at the top of the home page are stills that NiiVue draws itself.
`bunx nx home-stills docs-site` draws them again on your computer's GPU and
saves them to `apps/docs/public/img/home`; the scenes are in
`apps/docs/scripts/home-stills.scenes.js`.

For agents, every page is also served as Markdown at its URL plus
`index.md` (`/guide/meshes/index.md`), which the Copy page button copies.
`/llms.txt` lists those files and `/llms-full.txt` joins them: the guides
in the sidebar order set in `src/sidebar.ts`, then each package's pages.
`src/lib/markdown.ts` drops the imports and the live demos, and writes each
`<Tabs>` panel under its label; any other component would reach the
Markdown as written, so keep pages to Markdown plus `<Demo>` and `<Tabs>`.
A new NiiVue guide needs a `description` in its frontmatter (llms.txt shows
it) and an entry in `src/sidebar.ts`.

## Running the site

```bash
bunx nx dev docs-site     # dev server with live reload
bunx nx build docs-site   # static build in apps/docs/dist
```

Both build the workspace libraries first. Demos and Gallery pages load
their images and example pages from the published examples site,
`https://niivue.com/`. To try examples or sample files that are
not published yet, start the example server and point the site at it with
`DOCS_EXAMPLES_BASE`:

```bash
cd packages/niivue && bun run dev        # in one terminal
DOCS_EXAMPLES_BASE=http://localhost:5273/ bunx nx dev docs-site
```

`DOCS_BASE_URL` sets the path the site is served from (`/` by default). The
GitHub Pages build sets it to `/docs/`.
