Development and documentation
Run the library, edit these guides, and publish a static site with GitHub Pages.
Run the documentation locally
Use Node.js 24 or newer. From the repository root:
npm ci
npm run docs:devOpen http://localhost:3902. The docs app builds the local chart package before starting, so the playground runs the same code as the library. Restart the docs command after editing library TypeScript or the playground to rebuild and copy the embedded demo assets.
Edit pages
MDX content lives in apps/docs/content/docs. Set title and description in the frontmatter, then write Markdown and code fences. Folder meta.json files control sidebar order.
The main app is in apps/docs/app; shared integration components are in apps/docs/components. This is a Fumadocs site using the static export configuration.
Validate
npm run docs:check
npm run docs:build
npm run docs:previewThe production build generates static HTML, assets, and a search index in apps/docs/out. Its postbuild check validates local links and assets. The preview command serves the exact exported files at http://localhost:3902.
The repository uses npm workspaces with one root lockfile. The library lives in packages/chart, the docs in apps/docs, and the standalone playground in apps/playground. Each workspace declares its own dependencies; the library and docs have separate TypeScript configurations. Building the docs does not add framework dependencies to the published chart package.
GitHub Pages
The repository includes .github/workflows/docs.yml. Pull requests build and validate the static site. Pushes to main and manual runs on main also deploy it to GitHub Pages.
In the repository's Settings → Pages, use GitHub Actions as the build source. The project URL is https://bloxwap.github.io/chart/.
To test that exact subpath locally:
NEXT_PUBLIC_BASE_PATH=/chart npm run docs:build
npm run docs:previewThe preview server reads the exported base path, so this build opens at http://localhost:3902/chart/. Pages paths, assets, and static search must all work under /chart, not just at the origin root.
Library commands
| Command | Purpose |
|---|---|
npm run build | Generate icons, compile embedded WASM, and compile TypeScript |
npm test | Build and run library tests |
npm run coverage | Run the coverage threshold check |
npm run bench | Run calculation and rendering benchmarks |
npm run pack:chart | Build the library and create a tarball in packages/chart |
npm run demo | Start the standalone playground; requires Bun |
Release to npm
Publishing a GitHub release publishes @bloxwap/chart from CI (.github/workflows/publish_npm.yml). Only the publish job runs on GitHub-hosted ubuntu-24.04, as required by npm trusted publishing; the prerequisite security scan and all other jobs remain on the Mac minis. Node 24 and npm 11.6.1 build and test the package on that runner, with dependency caching disabled. Publishing requests npm provenance, including during token fallback.
Configure the GitHub npm-release environment with required reviewers before releasing; the workflow names this environment, but approval rules must be set in GitHub settings. The publish step keeps NPM_TOKEN as NODE_AUTH_TOKEN only as a transitional fallback, so releases work before npmjs.com setup. Configure the npm Trusted Publisher for organization bloxwap, repository chart, workflow filename publish_npm.yml, environment npm-release, allowing direct publishing. Once trusted publishing is verified, remove the fallback and delete this repository's token secret/access. See CI runner setup for details.
- In a pull request, bump
versioninpackages/chart/package.json(and theversionexport inpackages/chart/src/index.ts), then merge it. A test fails if the two disagree. - Create a GitHub release tagged
v<version>, for examplev0.0.2. The workflow fails if the tag and the package version disagree. - The workflow builds, runs the full test suite, and publishes. Versions with
-alpha,-beta, or-rcgo to that npm dist-tag, other prereleases toprerelease, and everything else tolatest.
See the repository for the source and MIT license.