Skip to content

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.

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.

WayReachesLanguageLifetime
Script in the modelthe node it sits onJavaScript, sandboxedtravels with the GLB
Project codethe document whose scriptRef names itTypeScriptunloaded when you switch the document
Extensionevery project of the installationTypeScript with importsloaded 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.

Your repository and a delivery The customer repository holds the realvirtual core, which a delivery replaces in full, and two folders that are yours, projects and extensions, which a delivery never changes. The extensions are built into the viewer together with the core. Your repository realvirtual core viewer, components, plugin API replaced in full by every delivery extensions/ index.ts plugins and components projects/ project.json, *.glb your twins Your viewer core and extensions built together opens every project of the installation
A delivery replaces the core. The folders projects/ and extensions/ stay as you left them.
  1. Create an extensions/ folder next to projects/ in your repository. In a checkout of the open-source viewer, use ./extensions.
  2. 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.
  3. Start the viewer as usual. The example button appears in the view group of the toolbar, and Add Component offers the example component.
  4. 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 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()];

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 PluginContext for 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.

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.

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.

  • Repository delivery. A delivery replaces everything outside projects/ and extensions/. It never reads, writes or reports your extensions/ 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.

We expect the plugin API to change little, but there is no compatibility guarantee and no version check. Build on these entry points:

  • RVViewerPlugin and PluginContext for plugins. ctx.signals is the narrow signal facade, not the full store.
  • registerComponentSchema for component types.
  • SignalStore for 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.

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.