Developing NiiVue
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:
git clone https://github.com/niivue/mono.gitcd monogit lfs installgit lfs pullbun installThe 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:
cd packages/niivuebun run devThis 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:
bunx nx test niivuecd packages/niivue && bun test # or run Bun directlyBefore you open a pull request, run the checks CI runs. From the root:
bunx nx affected -t formatbunx nx affected -t lintbunx nx affected -t typecheckbunx nx affected -t testbunx nx affected -t buildbun run check-boundariesnx 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.mdxis required. It becomes/packages/<folder>/; another page,docs/hosts.mdxsay, becomes/packages/<folder>/hosts/.- Each page needs a
titleand adescriptionin 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
PACKAGESinapps/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’snotesfolder.
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
bunx nx dev docs-site # dev server with live reloadbunx nx build docs-site # static build in apps/docs/distBoth 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:
cd packages/niivue && bun run dev # in one terminalDOCS_EXAMPLES_BASE=http://localhost:5273/ bunx nx dev docs-siteDOCS_BASE_URL sets the path the site is served from (/ by default). The
GitHub Pages build sets it to /docs/.