Customer extensions
An extension is your own TypeScript code that runs in every project of your installation. You keep it in an extensions/ folder next to projects/. Updates replace the realvirtual core and leave that folder alone. Extensions are meant for customers who work with the source, either in a commercial repository or in a checkout of the open-source viewer.
When to use an extension
Section titled “When to use an extension”The scripting overview describes three places for code. An extension is a fourth one, for code that belongs to your installation rather than to one model or one project.
| Way | Reaches | Language | Lifetime |
|---|---|---|---|
| Script in the model | the node it sits on | JavaScript, sandboxed | travels with the GLB |
| Project code | the document whose scriptRef names it | TypeScript | unloaded when you switch the document |
| Extension | every project of the installation | TypeScript with imports | loaded at startup, stays across project switches |
Use an extension for a panel, a toolbar button or a component type that all your projects should have, without copying it into each project folder.
projects/ and extensions/ stay as you left them.Set it up
Section titled “Set it up”- Create an
extensions/folder next toprojects/in your repository. In a checkout of the open-source viewer, use./extensions. - Copy the example extension from the viewer repository (
examples/customer-extension) into it. It contains an entry file, one plugin and one component. Keep its@rv/imports: they resolve to the viewer in either layout, and you need no separate dependency tree. - Start the viewer as usual. The example button appears in the view group of the toolbar, and Add Component offers the example component.
- Edit your files. Every change in
extensions/triggers a full reload of the dev server.
To use another location, set the environment variable RV_EXTENSIONS_DIR to a folder relative to the Vite root. The folder must contain an index.ts or index.tsx. Without an extensions/ folder, the viewer runs without extensions.
Keep extensions/ in your own Git repository or leave it untracked. We never write to it, and a pull of our repository never touches it.
The entry file
Section titled “The entry file”The entry registers components when it is imported and exports an array of plugin factories. One failing constructor therefore does not stop the next factory.
import type { RVExtensionPluginFactory } from '@rv/core/rv-extension-loader';import './example-component';import { ExamplePlugin } from './example-plugin';
export const plugins: readonly RVExtensionPluginFactory[] = [() => new ExamplePlugin()];A plugin
Section titled “A plugin”The example plugin adds one button to the view group of the toolbar. It reads the connection state through PluginContext, the only access a plugin needs to the viewer.
export class ExamplePlugin implements RVViewerPlugin { readonly id = 'example-extension'; private context: PluginContext | null = null;
readonly slots: UISlotEntry[] = [{ slot: 'button-group', group: 'view', order: 100, component: () => createElement('button', { type: 'button' }, 'Connection status'), }];
init(_viewer, context?: PluginContext): void { this.context = context ?? null; } dispose(): void { this.context = null; }}Rules to follow:
- Use only
PluginContextfor viewer access and do not import another plugin. - Do not scan models in
init. Do model-dependent work in the model and scene-ready hooks, so that later placements are covered too. - Release subscriptions, timers and UI in the matching teardown hook. Cleanup must tolerate repeated calls.
- Send actions that change the model through the command registry.
A component with an Inspector
Section titled “A component with an Inspector”The example component, ExampleExtensionComponent, is a live component type. Its schema gives it two properties and one signal slot, and the Inspector builds its fields from that schema.
const schema: ComponentSchema = { Length: { type: 'number', unit: 'mm', default: 100 }, IsActive: { type: 'boolean', default: true }, Enabled: { type: 'componentRef', signal: 'PLCOutputBool', default: null },};
registerComponentSchema(type, schema, { authorable: true });registerComponent({ type, schema, capabilities: { authorable: true }, create: (node) => new ExampleComponent(node),});Because the type has a factory, it is a real component that you can add to a node with Add Component, not only metadata. Register the schema when the entry is imported, so it exists before a model is prepared. Keep the schema keys identical to the exported property names.
A boolean signal slot needs no unit. A numeric slot that needs conversion must declare both signalUnit and scaleField.
When something fails
Section titled “When something fails”The viewer waits for your entry before it loads the first model. If an import, a factory or a registration fails, the Problems panel shows an extension-load-failed entry with the failing stage and name. A module that fails to load stops that entry. A failing factory leaves the following factories running.
This isolates load-time errors. It is not a sandbox, and it does not undo side effects from code that already ran.
Successful extension plugins behave like core plugins: they run in every project, independent of a document’s plugin list, and users can switch them off with the plugin toggle. Implement activation and teardown the same way.
Deliveries, updates and hosted links
Section titled “Deliveries, updates and hosted links”- Repository delivery. A delivery replaces everything outside
projects/andextensions/. It never reads, writes or reports yourextensions/folder. Commit your own work before you pull an update. - Hosted link. A hosted deployment can include your extensions on request. Only compiled code is published, without source maps. The source stays in your repository.
- Public demo. Demo and public builds never include customer extensions.
API stability
Section titled “API stability”We expect the plugin API to change little, but there is no compatibility guarantee and no version check. Build on these entry points:
RVViewerPluginandPluginContextfor plugins.ctx.signalsis the narrow signal facade, not the full store.registerComponentSchemafor component types.SignalStorefor signals.
Breaking changes are announced in the changelog under their own heading. After every update, run the typecheck of your workspace to find deviations. A successful Vite build is not a typecheck.
Licence
Section titled “Licence”The viewer core is AGPL. In a commercial delivery, your extensions follow the commercial licence terms of that delivery. In a checkout of the open-source viewer, the AGPL applies to your extension code when you distribute it. See Licensing the viewer and the licence files; this page is not legal advice.
See also
Section titled “See also”- Scripting for scripts in the model and project code
- Document references for how documents name their code
- Getting started as a commercial customer