xeokit-sdk-plugins

Plugins for xeokit-sdk, published together as one npm package installed next to the SDK:

npm install @xeokit/xeokit-sdk @xeokit/sdk-plugins

import {WalkModePlugin} from "@xeokit/sdk-plugins";

The package has no side effects, so bundlers drop the plugins an application doesn't import.

Plugin	Description
WalkModePlugin	First-person walking with gravity, collisions, doors and free flight

Development

npm install
npm run build      # builds every package in packages/, then bundles index.ts -> dist/index.js
npm run docs       # API docs of everything index.ts exports -> docs/
npm run docs:serve # rebuilds the docs on change and serves them at http://localhost:3000

API docs are generated by TypeDoc from the TSDoc comments (see typedoc.json). TypeDoc doesn't support TypeScript 7 yet, so npm run docs runs it through npx with TypeScript 6. A plugin's README.md is attached to its class page with @document ../README.md. typedoc/custom.css restyles the TypeDoc theme after the ESDoc docs of xeokit-sdk, which these docs sit next to on xeokit.io.

Adding a plugin

Each plugin is a private workspace package in packages/. It is never published on its own: index.ts re-exports it by package name and the build bundles all plugins into a single dist/index.js with esbuild, leaving @xeokit/xeokit-sdk external. The type declarations still re-export the plugins by package name, so the root package also lists them in bundleDependencies, which puts them inside the @xeokit/sdk-plugins tarball.

Naming convention:

What	Convention	Example
package	@xeokit/sdk-plugins-<name>	@xeokit/sdk-plugins-walk-mode
folder	packages/<name> (kebab-case, no -plugin suffix)	packages/walk-mode
entry point	src/index.ts	packages/walk-mode/src/index.ts

1. Run npm run new -- <name>. It creates packages/<name> with an empty <Name>Plugin (package and tsconfig copied from walk-mode), adds the package to dependencies and bundleDependencies, re-exports it from index.ts and runs npm install.
2. Add the plugin to the table above. Exported names must be unique across plugins (tsc fails on a clash), so prefix them with the plugin name.
3. Keep @xeokit/xeokit-sdk as a peer dependency, never a regular one, so the plugin uses the same SDK instance as the application (plugins must extend the app's Plugin class). Keep modules free of top-level side effects ("sideEffects": false).
4. Import everything from "@xeokit/xeokit-sdk", extend Plugin, unsubscribe from viewer events in destroy().
5. Add a usage example to xeokit/examples.

Publishing

Pushing a v* tag publishes the package from .github/workflows/publish.yml (the tag must be on main and match the package.json version):

npm version patch          # bumps the version, commits and tags v0.1.1
git push --follow-tags

The workflow authenticates with npm trusted publishing (OIDC, with provenance). Trusted publishing can only be configured for an existing package, so the first version is published with the NPM_TOKEN repository secret; then add xeokit/xeokit-sdk-plugins / publish.yml as a trusted publisher on npmjs.com and remove the secret.

After publishing, the workflow deploys the API docs to GitHub Pages. One-time setup in the repository settings: Pages > Source: GitHub Actions, and Environments > github-pages > add a deployment tag rule v* (by default the environment only allows the default branch, so a tag deploy is rejected).