SDK V2 to V3

Breaking Change Notice: Version 3.0.0 introduces a new import structure. All imports must be updated to use the unified @roomle/web-sdk entry point.

Overview

Version 3.0.0 simplifies the import structure of the Roomle Web SDK. Previously, types and classes were distributed across multiple deep import paths. This made it difficult to discover exports and required knowledge of the internal package structure.

What Changed:

• Before (v2.x): Multiple entry points with deep path imports

• After (v3.0.0): Single unified entry point via @roomle/web-sdk

Why This Change:

• Simpler, more discoverable API surface

• Better IDE autocomplete and TypeScript IntelliSense

• Improved tree-shaking with modern package.json exports field

• Consistent with modern npm package best practices

Industry Standard Pattern

This unified import approach is the standard pattern used by major frameworks and libraries:

// Playwright
import { test, expect, chromium } from '@playwright/test';

// Vue
import { ref, computed, onMounted } from 'vue';

// React
import { useState, useEffect, useMemo } from 'react';

// Zod
import { z } from 'zod';

// Drizzle ORM
import { pgTable, serial, text } from 'drizzle-orm/pg-core';

// Vitest
import { describe, it, expect } from 'vitest';

Benefits of this pattern:

• Discoverability: IDE autocomplete shows all available exports in one place

• Maintenance: Library authors can reorganize internals without breaking imports

• Consistency: Users learn one import pattern instead of many

• Performance: Bundlers can better optimize with unified entry points

No Runtime Changes

This is a build and distribution change only. There are no runtime behavior changes:

• All classes work exactly the same way

• No API method signatures changed

• No breaking changes to functionality

• Existing v2.x code will work exactly the same after updating imports

API Changes

getParametersOfComponent is now async

The method getParametersOfComponent in RoomleConfigurator has been changed to be asynchronous. It now returns a Promise.

Before (v2.x):

const params = configurator.getParametersOfComponent(id);

After (v3.0.0):

const params = await configurator.getParametersOfComponent(id);

---

Quick Migration (3 Steps)

Step 1: Find All SDK Imports

Search your codebase for imports from @roomle/web-sdk:

# Using grep
grep -r "from '@roomle/web-sdk" src/

# Using ripgrep (faster)
rg "from '@roomle/web-sdk" src/

Step 2: Update Import Statements

Replace all deep path imports with the unified import:

Before (v2.x):

import RoomleSdk from '@roomle/web-sdk';
import { type RoomleConfigurator } from '@roomle/web-sdk/configurator-core/src/roomle-configurator';
import { type RoomlePlanner } from "@roomle/web-sdk/planner-core/src/roomle-planner";
import type { GlbViewer } from '@roomle/web-sdk/glb-viewer-core/src/glb-viewer';
import type { UiPlanObject } from '@roomle/web-sdk/typings/kernel';

After (v3.0.0):

import {
  RoomleSdk,
  type RoomleConfigurator,
  type RoomlePlanner,
  type GlbViewer,
  type UiPlanObject,
} from '@roomle/web-sdk';

Step 3: Verify & Test

# Run TypeScript type checking
npm run typecheck  # or tsc --noEmit

# Run your tests
npm test

# Build your project
npm run build

---

Common Migration Patterns

Pattern 1: Mixed Runtime & Type Imports

Before (v2.x):

import { RoomleConfigurator } from '@roomle/web-sdk/configurator-core/src/roomle-configurator';
import type { UiPlanObject } from '@roomle/web-sdk/typings/kernel';
import type { RapiId } from '@roomle/web-sdk/typings/rapi-types';

After (v3.0.0):

import {
  RoomleConfigurator,
  type UiPlanObject,
  type RapiId
} from '@roomle/web-sdk';

Pattern 2: Multiple Type-Only Imports

Before (v2.x):

import type { PlanInteractionHandler } from '@roomle/web-sdk/typings/planner';
import type { WallDefinition } from '@roomle/web-sdk/planner-core/src/roomle-planner';
import type { RapiMaterial } from '@roomle/web-sdk/typings/rapi-types';

After (v3.0.0):

import type {
  PlanInteractionHandler,
  WallDefinition,
  RapiMaterial
} from '@roomle/web-sdk';

Pattern 3: Callback Registration

Before (v2.x):

import { ConfiguratorUiCallbacks } from '@roomle/web-sdk/configurator-core/src/services/configurator-ui-callback';
import type { KernelComponent } from '@roomle/web-sdk/typings/kernel';

After (v3.0.0):

import {
  ConfiguratorUiCallbacks,
  type KernelComponent
} from '@roomle/web-sdk';

Pattern 4: View Model Usage

Before (v2.x):

import { type PlanElementViewModel } from '@roomle/web-sdk/common-core/src/view-model/plan-element-view-model';
import type { WallDimensionTransferable } from '@roomle/web-sdk/planner-core/src/view-model/wall-plan-element-view-model';

After (v3.0.0):

import type {
  PlanElementViewModel,
  WallDimensionTransferable
} from '@roomle/web-sdk';

Pattern 5: HOMAG Intelligence Integration

Before (v2.x):

import { createExtObjId } from '@roomle/web-sdk/common-core/src/roomle-sdk';
import { RoomDesignerApi } from '@roomle/web-sdk/homag-intelligence/src/api';
import type { HiApiOptions } from '@roomle/web-sdk/homag-intelligence/src/hi-api-types';

After (v3.0.0):

import {
  createExtObjId,
  RoomDesignerApi,
  type HiApiOptions
} from '@roomle/web-sdk';

---

Troubleshooting

Issue: "Module not found" or "Cannot find module"

Symptom:

Error: Cannot find module '@roomle/web-sdk/configurator-core/src/roomle-configurator'

Solution: Update the import to use the unified entry point:

import { RoomleConfigurator } from '@roomle/web-sdk';

Issue: TypeScript cannot find type definitions

Symptom:

Could not find a declaration file for module '@roomle/web-sdk'

Solution:

1. Ensure you're on v3.0.0 or later: npm list @roomle/web-sdk

2. Delete node_modules and reinstall: rm -rf node_modules && npm install

3. Restart your TypeScript server in your IDE

Issue: Named export not found

Symptom:

Error: 'RoomleSdk' is not exported from '@roomle/web-sdk'

Solution: Ensure you're importing as a named export, not a default export:

// ❌ Wrong (v2.x style)
import RoomleSdk from '@roomle/web-sdk';

// ✅ Correct (v3.0.0)
import { RoomleSdk } from '@roomle/web-sdk';

Issue: Cannot find specific type or class

Symptom: You get an error that a type or class doesn't exist after migrating.

Solution:

1. Check the Complete Import Path Reference section below

2. Ensure the export name is correct (some may have changed slightly)

3. If you can't find it, check the packages/web-sdk/index.ts file for all available exports

Issue: Build fails with "exports is not defined"

Symptom: Your bundler fails with errors about exports or package.json resolution.

Solution: Ensure your bundler supports the package.json exports field:

• Vite: Supported by default

• Webpack 5: Supported by default

• Webpack 4: May require configuration updates or upgrade to Webpack 5

• Rollup: Install @rollup/plugin-node-resolve v13+

Issue: IDE autocomplete not working

Symptom: Your IDE doesn't show available exports when typing import { } from '@roomle/web-sdk'

Solution:

1. Restart your TypeScript language server

   • VS Code: Cmd/Ctrl + Shift + P → "TypeScript: Restart TS Server"

   • WebStorm: File → Invalidate Caches / Restart

2. Ensure node_modules/@roomle/web-sdk/lib/roomle-sdk.d.ts exists

3. Check your tsconfig.json includes the right paths

---

Bundler Configuration

Vite

If you're using Vite, exclude the SDK from optimization (this was required in v2.x and still applies):

// vite.config.js
export default defineConfig({
  plugins: [vue()],
  optimizeDeps: {
    exclude: ['@roomle/web-sdk']
  },
});

Webpack

No special configuration needed for v3.0.0, but ensure you're using Webpack 5 for best compatibility with package.json exports field.

Ember with Embroider

// ember-cli-build.js
skipBabel: [
  {
    package: '@roomle/web-sdk',
  },
],

---

Technical Details

What Changed Under the Hood

Build System:

• Switched from Rollup to Vite with vite-plugin-dts

• Types are now bundled into a single lib/roomle-sdk.d.ts file (376KB)

• Modern package.json exports field for proper module resolution

Package Structure:

{
  "exports": {
    ".": {
      "types": "./lib/roomle-sdk.d.ts",
      "import": "./lib/roomle-sdk.js",
      "default": "./lib/roomle-sdk.js"
    },
    "./package.json": "./package.json"
  },
  "typesVersions": {
    "*": {
      ".": ["lib/roomle-sdk.d.ts"]
    }
  },
  "type": "module"
}

Benefits:

• Simpler Developer Experience: One import path instead of 10+

• Better Tree-Shaking: Modern bundlers can optimize unused exports

• Improved Type Resolution: TypeScript resolves types faster with bundled definitions

• Future-Proof: Follows current npm and Node.js ESM best practices

---

FAQ

Q: Do I need to update my code beyond import statements?

A: No. Only import statements need to change. All APIs, method signatures, and runtime behavior remain identical.

Q: Can I migrate incrementally?

A: No. Version 3.0.0 removes the old deep path exports entirely. You must update all imports when upgrading to v3.0.0.

Q: Will my build size change?

A: Build size should remain similar or slightly improve due to better tree-shaking with the new exports field.

Q: Do I need to update my bundler configuration?

A: Most likely not. The Vite exclusion rule from v2.x still applies (see Bundler Configuration section). Modern bundlers (Webpack 5, Vite, Rollup) support the exports field by default.

Q: What if I'm using custom types augmentation?

A: Custom type augmentation for Window or global types continues to work. The bundled types preserve all global type declarations.

Q: Is there a way to keep using the old import paths?

A: No. The old structure is removed in v3.0.0. We recommend updating all imports as part of the upgrade process.

Q: What version should I use if I can't migrate yet?

A: Stay on the latest v2.x version until you're ready to migrate. We recommend planning the migration as the new structure significantly improves developer experience.

---

Getting Help

If you encounter issues during migration:

1. Check the Troubleshooting section above

2. Review the Complete Import Path Reference for the correct import path

3. Report issues via our Servicedesk

For API documentation, see: https://docs.roomle.com/rubens/rubens-sdk/rubens-sdk-reference/classes

---

Appendix - Complete Import Path Reference

Core Classes

v2.x Import	v3.0.0 Import
import RoomleSdk from '@roomle/web-sdk'	import { RoomleSdk } from '@roomle/web-sdk'
from '@roomle/web-sdk/configurator-core/src/roomle-configurator'	from '@roomle/web-sdk'
from '@roomle/web-sdk/configurator-core/src/configurator'	from '@roomle/web-sdk'
from '@roomle/web-sdk/planner-core/src/roomle-planner'	from '@roomle/web-sdk'
from '@roomle/web-sdk/planner-core/src/planner'	from '@roomle/web-sdk'
from '@roomle/web-sdk/glb-viewer-core/src/roomle-glb-viewer'	from '@roomle/web-sdk'
from '@roomle/web-sdk/glb-viewer-core/src/glb-viewer'	from '@roomle/web-sdk'

Available exports:

• RoomleSdk

• RoomleConfigurator, Configurator

• RoomlePlanner, Planner

• RoomleGLBViewer, GlbViewer

Type Imports (Kernel Types)

v2.x Import	v3.0.0 Import
from '@roomle/web-sdk/typings/kernel'	from '@roomle/web-sdk'

Available kernel type exports:

• KernelParameter, KernelParameterGroup, UiKernelParameter

• UiPlanObject, KernelPlanObject

• UiPossibleChild, UiPossibleChildTag

• KernelPartList, KernelPart, KernelPartListPrice, KernelPartListParameter

• KernelComponent

• KernelVector3, KernelValue

• RuntimeId

• CORE_PERMISSION_TO_DELETE (constant)

Type Imports (RAPI Types)

v2.x Import	v3.0.0 Import
from '@roomle/web-sdk/typings/rapi-types'	from '@roomle/web-sdk'

Available RAPI type exports:

• RapiItem, RapiElement, RapiComponent

• RapiConfiguration, RapiConfigurationEnhanced

• RapiConfiguratorSettings

• RapiPlan, RapiPlanSnapshotGetData, RapiPlanSnapshotId

• RapiMaterial, RapiMaterialGroup

• RapiTexture

• RapiAdditionalContent

• RapiTag, RapiTagForUi

• RapiId, RapiTenant

• HexColorString

• UserAction, AdditionalInfo

Type Imports (Planner Types)

v2.x Import	v3.0.0 Import
from '@roomle/web-sdk/typings/planner'	from '@roomle/web-sdk'

Available planner type exports:

• PlanObject, WallPlanObject

• PlanObjectPosition

• PlanInteractionHandler, PlanOverview

• KernelWall, KernelWallMaterial

• KernelObject

• KernelAttic, KernelFloor, KernelFloorMaterial

• CancelSelectionReasons

• WallDefinition, ID_TYPE (from RoomlePlanner)

Utilities & Helpers

v2.x Import	v3.0.0 Import
from '@roomle/web-sdk/common-core/src/rapi-access'	from '@roomle/web-sdk'
from '@roomle/web-sdk/common-core/src/main'	from '@roomle/web-sdk'
from '@roomle/web-sdk/common-core/src/roomle-sdk'	from '@roomle/web-sdk'

Available utility exports:

• RapiAccess

• Main, GlobalAPI (type)

• GlobalCallback

• IdbManager, SavedIdbData (type)

• RoomleLightSource

• Helper functions: isExternalObject, createExtObj, createExtObjId, removeExtObjIdPrefix, isExtObjId

• isSafari (browser detection)

UI Callbacks

v2.x Import	v3.0.0 Import
from '@roomle/web-sdk/configurator-core/src/services/configurator-ui-callback'	from '@roomle/web-sdk'
from '@roomle/web-sdk/planner-core/src/roomle-planner-ui-callback'	from '@roomle/web-sdk'

Available callback exports:

• ConfiguratorUiCallbacks

• RoomlePlannerUiCallback, SelectionPayload (type)

• PLAN_ELEMENT_CHANGE_TYPES (constant)

View Models

v2.x Import	v3.0.0 Import
from '@roomle/web-sdk/common-core/src/view-model/*'	from '@roomle/web-sdk'
from '@roomle/web-sdk/planner-core/src/view-model/*'	from '@roomle/web-sdk'

Available view model exports:

• PlanElementViewModel

• PlanObjectViewModel, ObjectMeasurementsTransferable (type), ObjectToWallDimensionTransferable (type), ObjectWallDimension (type)

• FloorPlanElementViewModel, FloorAreaDataTransferable (type)

• MeasurementLinePlanElementViewModel, MeasurementLineDimensionTransferable (type)

• StaticPlanObjectViewModel

• WallPlanElementViewModel, WallDimensionTransferable (type)

Common Types

v2.x Import	v3.0.0 Import
from '@roomle/web-sdk/common-core/src/common-interfaces'	from '@roomle/web-sdk'
from '@roomle/web-sdk/typings/helper'	from '@roomle/web-sdk'

Available common type exports:

• Position2, Position3

• Base64Image, CanvasOffset

• Nullable<T>, Values<T>

• FeatureFlags, InitDataDefinition, GlobalInitDataDefinition, PlannerInitData, CommonInitData

• RoomleEventedObject3DSubComponent, RoomleComponent

HOMAG Intelligence

v2.x Import	v3.0.0 Import
from '@roomle/web-sdk/homag-intelligence/src/*'	from '@roomle/web-sdk'

Available HOMAG Intelligence exports:

• RoomDesignerApi

• ExternalObjectAPI (type), LoadExternalObjectGroupResult (type)

• HiApiOptions (type)

• MasterData (type), PosGroup (type), PosSaveData (type)

External Objects

v2.x Import	v3.0.0 Import
from '@roomle/web-sdk/typings/external-objects'	from '@roomle/web-sdk'

Available external object type exports:

• ExternalItem, ExternalConfiguration

• RoomlePlannerWithExtObjs, RoomleConfiguratorType

• ExtObjId

---

This guide covers migration from v2.x to v3.0.0. For release notes, see the CHANGELOG.