Overview

The 2.0 release represents a major consolidation of the KOS SDK ecosystem:

• 23 legacy packages → 5 consolidated SDKs
• Simplified imports – all exports from package root
• Better TypeScript support – enhanced type definitions
• Improved developer experience – cleaner API surface

Who Needs to Migrate?

Breaking Changes

Package Consolidation Map

The following packages have been consolidated:

kos-ui-sdk Consolidation

• @kosdev-code/kos-ui-core → @kosdev-code/kos-ui-sdk
• @kosdev-code/kos-core-model → @kosdev-code/kos-ui-sdk
• @kosdev-code/kos-ui-components → @kosdev-code/kos-ui-sdk

kos-dispense-sdk Consolidation

• @kosdev-code/kos-dispense-model → @kosdev-code/kos-dispense-sdk
• @kosdev-code/kos-dispense-ui → @kosdev-code/kos-dispense-sdk
• @kosdev-code/kos-dispense-components → @kosdev-code/kos-dispense-sdk

kos-freestyle-sdk Consolidation

• @kosdev-code/kos-freestyle-model → @kosdev-code/kos-freestyle-sdk

kos-cms-sdk Consolidation

• @kosdev-code/kos-cms-model → @kosdev-code/kos-cms-sdk
• @kosdev-code/kos-cms-ui → @kosdev-code/kos-cms-sdk

Import Path Changes

All deep imports have been removed. Everything now exports from the package root.

Before:

import { KosModel } from '@kosdev-code/kos-core-model';
import { kosComponent } from '@kosdev-code/kos-ui-components/decorators';
import { useTimer } from '@kosdev-code/kos-ui-sdk/ui/hooks';
import { KosContext } from '@kosdev-code/kos-ui-sdk/ui/contexts';
import { DispenseModel } from '@kosdev-code/kos-dispense-model/models';

After:

import { KosModel, kosComponent, useTimer, KosContext } from '@kosdev-code/kos-ui-sdk';
import { DispenseModel } from '@kosdev-code/kos-dispense-sdk';

Automated Migration

Prerequisites

• Node.js 16 or higher
• Nx workspace
• Git repository (commit all changes before migrating)

Step-by-Step Migration

1. Install Latest CLI

npm i -g @kosdev-code/kos-ui-cli@latest

2. Create Migration Descriptor

npx nx migrate @kosdev-code/kos-nx-plugin --from="@kosdev-code/kos-nx-plugin@1.5.0"

This creates a migrations.json file with all necessary updates.

3. Install Dependencies

npm install

4. Run Migrations

npx nx migrate --run-migrations

This will:

• Update all import statements automatically
• Modify tsconfig paths
• Update package.json dependencies
• Apply codemods to your source files

5. Clean Up

rm migrations.json

6. Update Project Metadata

Update .kos.json in your project root:

{
  "name": "my-ui",
  "type": "ddk.cui",
  "version": "2.0.0",  // Update version
  "kos": {
    "localization": {
      "defaultLocale": "en",
      "namespaces": {
        "my-ui": {}
      }
    },
    "softwareInfo": {
      "name": "My CUI",
      "group": "My Group"
    }
  }
}

7. Update DDK Artifacts (if applicable)

If your project uses DDK, update these versions:

kos.autostart.ddk:

kosdev-ddk-ui: 2.0.2
kosdev-ddk-i18n: 2.0.0

ddk.ncui. (plugins):*

kosdev-ddk-standard-plugin: 2.0.2

8. Verify Migration

# Clear caches
nx reset
# Build
nx run-many --target=build --all

Manual Migration

If automated migration isn’t suitable, follow these steps:

1. Update Dependencies

{
  "dependencies": {
    "@kosdev-code/kos-ui-sdk": "^2.0.34",
    "@kosdev-code/kos-dispense-sdk": "^2.0.34",
    "@kosdev-code/kos-freestyle-sdk": "^2.0.34",
    "@emotion/react": "^11.11.0",
    "@emotion/styled": "^11.11.0",
    "openapi-typescript": "^6.0.0"
  },
  "devDependencies": {
    "@kosdev-code/kos-nx-plugin": "^2.0.34",
    "@kosdev-code/kos-ui-cli": "^2.0.34"
  }
}

2. Update Import Statements

Use your IDE’s find and replace with regex:

3. Update TSConfig Paths

Remove old path mappings in tsconfig.base.json:

{
  "compilerOptions": {
    "paths": {
      // Remove these old mappings
      "@kosdev-code/kos-ui-core": ["..."],
      "@kosdev-code/kos-core-model": ["..."],
      // Keep only the consolidated SDK paths
      "@kosdev-code/kos-ui-sdk": ["node_modules/@kosdev-code/kos-ui-sdk"]
    }
  }
}

Troubleshooting

Common Issues

Module Not Found Errors

Problem: Cannot find module '@kosdev-code/kos-ui-sdk/core'

Solution: Remove the deep import path:

// Wrong
import { something } from '@kosdev-code/kos-ui-sdk/core';
// Correct
import { something } from '@kosdev-code/kos-ui-sdk';

Type Errors After Migration

Problem: TypeScript can’t find types that were previously available

Solution: Clear TypeScript cache and reinstall:

rm -rf node_modules
rm package-lock.json
npm install
nx reset

Build Cache Issues

Problem: Old build artifacts causing issues

Solution:

nx reset
rm -rf dist
nx run-many --target=build --all --skip-nx-cache

Circular Dependency Warnings

Problem: New import structure reveals circular dependencies

Solution: Review and refactor circular imports. The consolidated packages make circular dependencies more visible.

Getting Help

If you encounter issues not covered here:

1. Check the CHANGELOG for specific version notes
2. Search existing issues in the repository
3. Contact the SDK team with:
   • Your current version
   • Error messages
   • Migration steps attempted

Rollback Plan

If you need to rollback:

1. Git Rollback: git reset --hard [commit-before-migration]
2. Restore package.json: git checkout [previous-branch] -- package.json package-lock.json
3. Reinstall dependencies: rm -rf node_modules npm install
4. Clear caches: nx reset

Post-Migration Checklist

• [ ] All imports updated to use consolidated packages
• [ ] TypeScript compilation successful
• [ ] All tests passing
• [ ] Build successful
• [ ] .kos.json version updated to 2.0.0+
• [ ] DDK artifacts updated (if applicable)
• [ ] Kab process runs successfully
• [ ] Application runs without console errors
• [ ] Git commit created with migration changes

New Features Available After Migration

Once migrated to 2.x, you gain access to:

• Log Manager Model – Runtime log level management
• Browser Router – Automatic route management
• Canvas Rendering – Advanced visualization capabilities
• Future-Aware Models – Enhanced async operations
• Generic Pour Model – Simplified dispense operations
• Simplified API Types – Cleaner service definitions

See CHANGELOG.md for complete feature list.

Last updated for version 2.0.34