Weave.js can render a room on the server, with no browser, no UI, and no live connection. You pass the room data in, the room renders on a native canvas, and you export the result, typically as a PNG or JPEG. Use it to generate previews, thumbnails, and downloads of a room.
A server-side instance uses the Standalone store to load the room data, and the Konva base renderer to build the canvas.
room data (base64 Yjs)
|
v
WeaveStoreStandalone --> Weave instance --> exportNodesServerSide()
(Konva on a native |
canvas backend) v
image tiles --> sharp --> PNG / JPEG
Steps
-
Install the dependencies.
Pick one native canvas backend,
canvasorskia-canvas. Both are optional peer dependencies of the SDK, so install the one you use with the version that@inditextech/weave-sdkrequires. See SDK setup.npm install canvas sharp yjs konva \ @inditextech/weave-types @inditextech/weave-sdk \ @inditextech/weave-renderer-konva-base @inditextech/weave-store-standalonenpm install skia-canvas sharp yjs konva \ @inditextech/weave-types @inditextech/weave-sdk \ @inditextech/weave-renderer-konva-base @inditextech/weave-store-standalonesharp composites the image tiles in the last step.
-
Import from the
/serverentry points.Every package has a
/serverentry point for Node.js. Use it on the backend instead of the default entry point.import { Weave, WeaveStageNode, WeaveLayerNode, WeaveGroupNode, WeaveRectangleNode, WeaveImageNode, WeaveVideoNode, WeaveTextNode, setupCanvasBackend, (1) } from '@inditextech/weave-sdk/server'; import { WeaveKonvaBaseRenderer } from '@inditextech/weave-renderer-konva-base/server'; import { WeaveStoreStandalone } from '@inditextech/weave-store-standalone/server';1 Use setupSkiaBackendif you installedskia-canvas. -
Register the fonts and select the backend.
Fonts are registered with the native canvas library, not with Weave.js. Register every font family your rooms use before you create the instance, otherwise the text renders with a fallback font. Then call the backend setup function once per process, or once per worker thread.
import path from 'node:path'; import { registerFont } from 'canvas'; registerFont(path.resolve(process.cwd(), 'fonts/inter-regular.ttf'), { family: 'Inter', weight: '400', style: 'normal', }); await setupCanvasBackend();import path from 'node:path'; import { FontLibrary } from 'skia-canvas'; FontLibrary.use('Inter', [ path.resolve(process.cwd(), 'fonts/inter-regular.ttf'), path.resolve(process.cwd(), 'fonts/inter-bold.ttf'), ]); await setupSkiaBackend();If the native package is missing, the setup function throws an error that names the package to install.
-
Create the instance.
Create a
WeaveStoreStandalonewith the room data, aWeaveKonvaBaseRenderer, and a Weave instance. Register every node type the room contains. A node type without a registered handler is skipped with a console warning. A server-side instance needs no actions and no plugins.const store = new WeaveStoreStandalone( { roomData }, (1) { getUser: () => ({ id: 'server', name: 'Server', email: 'server@example.com' }), } ); const weave = new Weave( { store, renderer: new WeaveKonvaBaseRenderer(), nodes: [ new WeaveStageNode(), new WeaveLayerNode(), new WeaveGroupNode(), new WeaveRectangleNode(), new WeaveTextNode(), new WeaveImageNode({ config: { urlTransformer: toInternalUrl }, (2) }), new WeaveVideoNode({ config: { urlTransformer: toInternalUrl }, }), ], actions: [], plugins: [], fonts: [], }, { container: undefined, width: 800, height: 600 } (3) );1 The base64 string the room is stored as. If omitted, the store loads the default initial state. 2 The server resolves URLs on its own, so a URL that is relative to the browser origin does not work. Use urlTransformerto rewrite image and video URLs to an address the backend can reach.3 No container on the server, so you set the stage size. -
Wait until the room is ready.
start()begins loading the room, but images and video placeholders keep loading after the room is in the state. Resolve when theonRoomLoadedevent has fired andasyncElementsLoaded()returnstrue. Register the listeners before you callstart().const ready = new Promise<void>((resolve) => { let roomLoaded = false; const check = () => { if (roomLoaded && weave.asyncElementsLoaded()) { resolve(); } }; weave.addEventListener('onRoomLoaded', (status: boolean) => { if (status) { roomLoaded = true; } check(); }); weave.addEventListener('onAsyncElementChange', check); }); await weave.start(); await ready; -
Export the room.
Call
exportNodesServerSidewith the IDs of the nodes to export. An empty list exports everything in the main layer. You get back the final image size and a list of image tiles, which the SDK renders in segments to avoid running out of memory in the canvas library. Composite them with sharp.import sharp from 'sharp'; const { composites, width, height } = await weave.exportNodesServerSide( [], (1) (nodes) => nodes, (2) { format: 'image/png', padding: 20, pixelRatio: 1, backgroundColor: '#FFFFFF' } ); await weave.destroy(); (3) const image = await sharp({ create: { width, height, channels: 4, background: { r: 0, g: 0, b: 0, alpha: 0 } }, }) .composite(composites) .png() .toBuffer();1 The IDs of the nodes to export. 2 Select which nodes define the bounds of the image. Return the nodes unchanged to use the exported nodes themselves. 3 Always destroy the instance when you finish, see Instance lifecycle. To export a region of the stage instead of a list of nodes, use
exportAreaServerSide. -
Run the render in a worker thread.
Rendering and compositing are CPU-bound. Run them in a worker thread so they do not block the main thread, and limit the number of concurrent workers. The backend generated by
create-weave-backend-appincludes an example of this: a worker that renders the room and exports the image.
Verify
Write the buffer to disk and open it.
import { writeFile } from 'node:fs/promises';
await writeFile('room.png', image);
The image is width by height pixels, which is the size of the exported nodes plus the
padding, multiplied by pixelRatio.
Instance lifecycle
Call weave.destroy() as soon as you finish exporting. It disconnects the store, destroys the
stage, and cancels any render that is still scheduled, so a destroyed instance never
renders afterward.
Weave.js groups store updates into a single scheduled render. In a browser the render runs on
the next animation frame. Node.js has no requestAnimationFrame, so on the server the same
render runs on a zero-delay timer. The store also handles state changes that nodes make
while the room renders, for example a node that writes its own state.
What changes on the server
An instance is on the server when window is not defined, and weave.isServerSide() returns
true. Everything that exists to support a user is skipped:
-
Event handlers, keyboard shortcuts, cursors, and the minimap are not set up.
-
Text editing keyboard handling is not set up.
-
The stage does not resize to a container.
-
A video node renders its placeholder image only. It does not load or play the video.
-
Images load through the Konva image element and the
urlTransformeryou configure.
Troubleshooting
| Symptom | Cause and fix |
|---|---|
|
The native package is not installed. Install it with the version that
|
Text uses the wrong font |
The font is not registered with the native library, or it is registered after the
instance is created. Register all fonts first, with the same |
An image or video placeholder is missing |
The server cannot reach the URL. Check the |
|
Caused by a bug in the store, fixed with
issue 1294. Upgrade
|
The promise from the ready step never resolves |
The listeners were registered after |
Next steps
-
Standalone store — the store that loads the room.
-
Weave export methods — all options of
exportNodesServerSideandexportAreaServerSide. -
SDK setup — native backend packages.
-
Set up the backend — the generated backend.