needle-engine-support: the documentation workspace behind the Needle Engine

The repository builds documentation, not the engine

The most important thing to know about needle-engine-support is what it is not. It is not the Needle Engine. The engine ships as the npm package @needle-tools/engine, and the README in this repository is the engine's README, describing an engine that deploys 3D web experiences to the web, runs on VR headsets and mobile AR including native iOS WebXR, integrates with Unity and Blender, or works with three.js from pure code, and includes Rapier based physics plus multiplayer and XR support.

What this repository holds is the workspace that produces the documentation for that engine. The manifest names the package @needle-tools/engine-documentation, version 1.0.0, with an empty description field, and it declares npm workspaces over packages/*. The scripts are documentation scripts: dev and build for the VuePress site, a separate API docs builder, a deploy script, a translation script, a changelog builder, an examples builder, and two link checkers.

So if you arrive from the engine's README and clone this repository expecting the runtime, you will find a docs pipeline instead. The runtime comes from npm, not from here.

VuePress drives the site and a build script drives the API reference

The site is built with VuePress. The manifest wires the dev server to the documentation folder with `npm run docs:dev`, which maps onto `vuepress dev documentation`, and the production build is `npm run docs:build`, which maps onto `vuepress build documentation`.

    "start": "npm run docs:dev",
    "docs:dev": "vuepress dev documentation",
    "docs:build": "vuepress build documentation",

Running the first command serves the docs locally with hot reload, and the second produces a static build. The documentation folder at the repository root is the source of the site, and mkdocs is not involved, unlike many project docs sites.

The API reference is a separate pipeline with separate scripts. `docs:build-api` runs a node script named build_api_docs.mjs, and there is a dev variant that passes a --dev flag through. For previewing the API pages, `docs:dev-api` first builds the API docs in dev mode and then serves the api folder of the engine package with npx serve.

    "docs:build-api": "node tools/build_api_docs.mjs",
    "docs:dev-build-api": "node tools/build_api_docs.mjs -- --dev",
    "docs:dev-api": "npm run docs:dev-build-api && npx serve api/@needle-tools/engine",

The split matters when you are working on the docs. The prose site and the generated API pages have different toolchains, so a change to one does not necessarily affect the other, and a broken API page usually means the generator, not the markdown.

The changelog and examples are generated, not hand written

Two of the scripts in the manifest exist to assemble content from elsewhere. `docs:build-changelogs` runs tools/build_changelogs.mjs, and `docs:build-examples` runs tools/build_examples.mjs.

    "docs:build-changelogs": "node tools/build_changelogs.mjs",
    "docs:build-examples": "node tools/build_examples.mjs",

That tells you the changelog pages and the examples pages are derived artifacts. The pattern is the one you would expect from a monorepo that publishes several packages at once: the changelog for the engine is likely collected from the individual package changelogs, and the examples are probably pulled from the sample projects referenced in the documentation.

The repository layout backs this up. The top level contains packages/, tools/, documentation/, assets/, plans/ and a plans directory that is a common convention for storing design proposals as markdown, plus a HOWTO.md, a CLAUDE.md, a CODE_OF_CONDUCT.md, a workspace.code-workspace, and two Windows batch files, BUILD.bat and START_DEV.bat.

The two batch files are worth a note for a JavaScript project. They suggest part of the intended workflow is a Windows developer running a build and a dev start from the command prompt, and the workspace.code-workspace file is the Visual Studio Code form of the same thing.

Live edit is a custom VuePress plugin in this repo

One dependency is a local path rather than a registry package: @needle-tools/vuepress-plugin-live-edit, declared as file:packages/vuepress-plugin-live-edit. It is also a dev dependency, and there is a script that runs the node test runner over that plugin's test files.

    "test:live-edit": "node --test \"packages/vuepress-plugin-live-edit/test/**/*.test.mjs\""

So the repository contains a VuePress plugin that lets documentation pages be edited from the rendered site, and it has its own tests. The live edit plugin is exactly the kind of component that has to live in the same repository as the docs it modifies, since it is specific to this documentation setup rather than a general VuePress extension.

The rest of the documentation toolchain is more conventional. The dev dependencies list VuePress with a beta bundler, an external link icon plugin, a Google Analytics plugin, a markdown chart plugin, a markdown container plugin, shikijs twoslash for typed code samples, and a markdown tab plugin in the runtime dependencies. A Google Generative AI dependency sits in the dependencies block, which points to the translation script using a model for the docs:translate step, and basic-ftp and diff2html are there for the deploy and changelog comparison work respectively.

Link checking is a first class script, not a browser plugin

Two of the scripts check links, and the distinction between them is useful. `test:links` runs tools/build_check_links.mjs, and `test:links:local` runs tools/check_links_local.mjs. The first appears to validate the built site, and the second works on a local version, which is the faster loop while writing prose.

    "test:links": "node tools/build_check_links.mjs",
    "test:links:local": "node tools/check_links_local.mjs",

A documentation repository with a link checker is not unusual, but the fact that it is exposed as a package script with a local variant means broken links are caught in the same workflow as the rest of the docs, rather than being discovered by a reader.

The naming convention across the whole manifest is worth noting for anyone scripting against it. Everything documentation related is prefixed with docs:, everything checkable with test:, and there is no test target for the documentation content itself beyond links. There is also no build or test script for the engine runtime in this workspace, which again reflects what the repository is.

The engine version here lags the published releases

The dev dependencies pin @needle-tools/engine to 6.0.0-alpha.2 and @needle-tools/helper to a caret range on 0.11.0. The published releases attached to the repository are different: a 5.1.16 tag on 2026-10-15, a 6.0.0-alpha.7 tag on 2026-10-12, and a 5.1.15 tag on 2026-10-12. The most recent push was on 2026-10-15.

So the workspace documents an engine version slightly behind the newest alpha tag it publishes alongside, and the stable line is 5.1.16. That is normal for a docs workspace, where the pinned dependency is a known-good version, but it means the docs pages in this repository may describe 6.0.0-alpha.2 behaviour while the public engine is at 6.0.0-alpha.7.

The tags are also named release/5.1.16 and release/6.0.0-alpha.7 rather than plain version tags, which is the pattern of a repository that hosts several packages whose versions do not move in lockstep. The helper package, the live edit plugin and the documentation package are all versioned separately, and the release tags are cut for the package that matters to the public API.

Licence is the one thing the sources do not settle

The repository records its licence as unknown, and GitHub could not classify it. The package manifest, however, declares a licence of ISC. Those two facts sit in tension, and the practical rule is to look at the LICENSE file in the repository root before you copy anything from here.

This matters more for a documentation workspace than it would for a library, because documentation text, images and code samples all end up in whatever you publish. The assets folder and the documentation folder contain material that a reader might reuse, and the terms under which that is permitted are not stated in the README.

The engine itself, the @needle-tools/engine npm package that most people actually install, is a separate artefact with its own terms, and the documentation site is not a substitute for reading those. The README points to the getting started documentation, the samples site and the engine documentation as the places where the substance lives, along with a Discord server and a forum.

One more practical note: this is a commercial product with a free tier of documentation, so the boundary between what is open here and what is closed is a good question to ask before building a dependency on the docs pipeline.

Editorial conclusion

Adopt this repository if you want to work on the Needle Engine documentation, the API reference generation, the changelog builder or the link checker, since the npm scripts and the vuepress live-edit plugin are all here. Do not adopt it as the engine, because the runtime is the separate @needle-tools/engine npm package and this workspace only builds docs. Before you depend on anything in it, check the two licence facts that the sources disagree on: the package manifest declares ISC while the repository records no licence at all, and the dev dependency pins @needle-tools/engine to 6.0.0-alpha.2 while the releases include a 6.0.0-alpha.7 tag.

Frequently asked questions

Official sources

1. Issues
2. needle-tools/needle-engine-support on GitHub
3. Project website
4. README
5. Releases