Skip to content

Developing NiiVue

View as Markdown

NiiVue lives in the 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:

Terminal window
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:

Terminal window
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.

Tests and checks

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

Terminal window
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:

Terminal window
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 and CONTRIBUTING.md cover code style, commit messages and the rest of the workflow.

About this site

The site is an Astro app using the Starlight 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:

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), 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

Terminal window
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:

Terminal window
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/.