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
Copy

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

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

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
Copy

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:

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
Copy

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