# 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:

```typescript
// 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):**

```typescript
const params = configurator.getParametersOfComponent(id);
```

**After (v3.0.0):**

```typescript
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`:

```bash
# 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):**

```typescript
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):**

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

### Step 3: Verify & Test

```bash
# 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):**

```typescript
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):**

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

### Pattern 2: Multiple Type-Only Imports

**Before (v2.x):**

```typescript
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):**

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

### Pattern 3: Callback Registration

**Before (v2.x):**

```typescript
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):**

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

### Pattern 4: View Model Usage

**Before (v2.x):**

```typescript
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):**

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

### Pattern 5: HOMAG Intelligence Integration

**Before (v2.x):**

```typescript
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):**

```typescript
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:

```typescript
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:

```typescript
// ❌ 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](https://github.com/roomle/roomle-documentation/blob/master/public/web/sdk/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):

```javascript
// 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

```javascript
// 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:**

```json
{
  "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](https://roomle.atlassian.net/servicedesk/customer/portals)

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*](/rubens/changelogs/changelog-1.md)*.*


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.roomle.com/rubens/migration-guides/migration-v2-to-v3.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.