Part 1 documented how sugarlite sunk its data layer from the Supabase Swift SDK down into the KMP shared/ module. But we left one thing deliberately untouched — ViewModels stayed on iOS using @Observable. We said we’d “keep them put” for now.

Well, we broke that promise.

As Android development accelerated, 21 of our 23 ViewModels needed to work on both platforms. Maintaining one set of Swift ViewModels for iOS and another set of Kotlin ViewModels for Android was clearly unsustainable — why write the same business logic (fetch today’s blood sugar, build a timeline, calculate glycemic response) twice?

This post picks up where Part 1 left off: how we migrated ViewModels to KMP, and everything that came with it — local storage unification, platform abstractions, subscription management, and Swift-Kotlin interop at scale.

📱 Sinking ViewModels: Breaking Our “Keep Them Put” Promise

Part 1’s migration principle #4 said: “ViewModels stay put — keep @Observable to preserve the SwiftUI reactive experience.” That was the right call at the time. Kotlin/Native compiles StateFlow into an Objective-C type — what exactly would the Swift side consume? You couldn’t ask the iOS team to hand-write a Combine bridge for every ViewModel.

The game-changer was SKIE (0.10.13). This Kotlin compiler plugin from TouchLab automatically maps Kotlin types to idiomatic Swift:

• suspend functions → Swift async throws
• StateFlow<T> / Flow<T> → Swift AsyncSequence (backed by generated SkieSwiftAsyncSequence)
• Enums and sealed classes → Swift enum

With SKIE, consuming a KMP ViewModel from SwiftUI feels almost as natural as a native @Observable.

The KMP ViewModel Pattern

After migrating 23 ViewModels, a unified pattern emerged:

// 1. Single UiState data class that holds all UI state
data class HomeUiState(
    val selectedDate: Instant = Clock.System.now(),
    val bloodSugarRecords: List<BloodSugarRecord> = emptyList(),
    val timelineEvents: List<TimelineEvent> = emptyList(),
    val isLoading: Boolean = false,
    val errorMessage: String? = null,
)

// 2. ViewModel extends KMP ViewModel
class HomeViewModel : ViewModel() {

    // 3. Private mutable backing flow + public read-only flow
    private val _uiState = MutableStateFlow(HomeUiState())
    val uiState: StateFlow<HomeUiState> = _uiState.asStateFlow()

    // 4. viewModelScope for structured concurrency
    fun loadData() {
        viewModelScope.launch {
            _uiState.update { it.copy(isLoading = true) }
            try {
                val uid = getCurrentUserId()
                val records = getDailyBloodSugarRecords(dateMillis, uid)
                _uiState.update {
                    it.copy(isLoading = false, bloodSugarRecords = records.map { r -> r.toModel() })
                }
            } catch (e: Exception) {
                _uiState.update { it.copy(isLoading = false, errorMessage = e.message) }
            }
        }
    }

    // 5. Always mutate state with update { it.copy(...) }
    fun clearError() {
        _uiState.update { it.copy(errorMessage = null) }
    }
}

Key design decisions:

1. One ViewModel, one uiState: StateFlow. No multiple independent flows — that would force the iOS side to manage multiple subscriptions.
2. State is a single data class. On Android, collectAsStateWithLifecycle() destructures it directly. On iOS, SKIE converts it to an AsyncSequence — one for await gets all state in a single receive.
3. All mutations use _uiState.update { it.copy(...) }. Never _uiState.value = ... — update is atomic and avoids race conditions.
4. Dependencies are top-level use-case functions, not Koin. ViewModel instantiation is just HomeViewModel() — zero DI overhead.

iOS Consumption via SKIE

Here’s how OnboardingViewModel bridges to SwiftUI:

// OnboardingStateHolder.swift
import Shared

@MainActor
final class OnboardingStateHolder: ObservableObject {
    @Published var state: HomeUiState = .init()
    private let viewModel = Shared.OnboardingViewModel()
    private var collectionTask: Task<Void, Never>?

    func startObserving() {
        collectionTask = Task { [weak self] in
            // SKIE converts StateFlow to AsyncSequence
            for await state in self?.viewModel.uiState ?? AsyncStream<HomeUiState>.empty {
                guard let self else { return }
                self.state = state // drives SwiftUI updates
            }
        }

        viewModel.loadData()
    }

    deinit {
        collectionTask?.cancel()  // clean up subscription
    }
}

Three steps: for await state in viewModel.uiState → assign to @Published → SwiftUI re-renders. No third-party bridging libraries.

We also wrote a small Swift extension for single-value reads:

extension SkieSwiftFlowProtocol {
    func first() async throws -> Element {
        for try await element in self {
            return element
        }
        throw NSError(domain: "SkieSwiftFlow", code: -1,
            userInfo: [NSLocalizedDescriptionKey: "Flow completed without emitting a value"])
    }
}

With this, a one-shot check becomes let state = try await viewModel.uiState.first() — no loop needed.

Android Consumption

On Android, it’s even simpler with Compose:

@Composable
fun HomeScreen() {
    val viewModel = remember { HomeViewModel() }
    val uiState by viewModel.uiState.collectAsStateWithLifecycle()

    HomeContent(
        records = uiState.bloodSugarRecords,
        isLoading = uiState.isLoading,
        onRefresh = { viewModel.loadData() }
    )
}

One line: collectAsStateWithLifecycle(). Done.

Before/After: The Migration Payoff

Before (iOS @Observable ViewModel, ~300 lines of Swift):

@Observable
final class HomeViewModel {
    var bloodSugarRecords: [BloodSugarRecord] = []
    var isLoading = false
    var errorMessage: String?

    func loadData() async {
        isLoading = true
        do {
            let dtos = try await repository.fetchDailyRecords(date: selectedDate)
            bloodSugarRecords = dtos.map { BloodSugarRecord(from: $0) }
            isLoading = false
        } catch {
            errorMessage = error.localizedDescription
            isLoading = false
        }
    }
}

After (KMP ViewModel, ~370 lines of Kotlin, shared by Android + iOS):

The KMP ViewModel is as shown above. The iOS side shrank from 300+ lines of business logic to a ~50-line StateHolder bridge with @Published property mapping. Android went from zero to fully functional, consuming the same uiState flow.

Key wins:

• Business logic written once. Blood sugar deduplication, timeline aggregation, and unit conversion no longer need Swift + Kotlin dual maintenance.
• The iOS StateHolder is razor-thin — pure data forwarding with zero business logic. It acts like a “remote control” for native SwiftUI views.
• New features go into KMP first, available on both platforms immediately.

💾 Room KMP: From SwiftData to a Cross-Platform Local Database

Part 1 solved remote storage by sinking the data layer. But local persistence was still split: iOS used SwiftData, Android used Room. These frameworks have entirely different schemas, query syntax, and migration mechanisms. Maintaining two local storage stacks was almost as painful as maintaining two network layers.

Why Room KMP

SwiftData is Apple-only. Room KMP reached production maturity with Room 2.8’s official KMP support in late 2024. Our decision was clear: unify local storage in shared/ as well.

AppDatabase Core Setup

@Database(
    entities = [
        BloodSugarRecordEntity::class,
        FoodRecordEntity::class,
        ExerciseRecordEntity::class,
        UserProfileEntity::class,
        // ... 14 entities total
    ],
    version = 12
)
@TypeConverters(InstantConverter::class)
@ConstructedBy(AppDatabaseConstructor::class)
abstract class AppDatabase : RoomDatabase() {
    abstract fun bloodSugarDao(): BloodSugarDao
    abstract fun foodRecordDao(): FoodRecordDao
    abstract fun exerciseRecordDao(): ExerciseRecordDao
    // ... 13 DAOs total
}

Every entity has built-in offline-sync fields:

@Entity(tableName = "blood_sugar_records")
data class BloodSugarRecordEntity(
    @PrimaryKey val id: String,
    val uid: String,
    val value: Double,
    val isDirty: Boolean = false,       // has unsynced changes?
    val deleted: Boolean = false,        // soft delete marker
    val syncVersion: Long = 0,           // optimistic lock version
    val sourceDeviceId: String = "",     // which device created this
    @ColumnInfo(name = "created_at") val createdAt: Long,
    // ...
)

The sync strategy is straightforward: on upload, query isDirty = 1 records and push to Supabase. On download, pull remote deltas by uid and merge locally with Upsert.

DatabaseFactory: The expect/actual Pattern

Room needs to know the physical database file path. On iOS it’s in the NSDocumentDirectory sandbox; on Android it’s in the app’s database directory. We abstracted this with an expect interface:

// commonMain — interface definition
interface DatabaseFactory {
    fun createBuilder(): RoomDatabase.Builder<AppDatabase>
}

fun getRoomDatabase(factory: DatabaseFactory): AppDatabase {
    return factory.createBuilder()
        .setDriver(BundledSQLiteDriver())
        .setQueryCoroutineContext(Dispatchers.IO)
        .addMigrations(MIGRATION_3_4, MIGRATION_4_5, /* ... 9 migrations total */)
        .fallbackToDestructiveMigration(true)
        .build()
}

// iosMain — NSFileManager for documents directory
class IOSDatabaseFactory : DatabaseFactory {
    override fun createBuilder(): RoomDatabase.Builder<AppDatabase> {
        val dbPath = documentDirectory() + "/sugarlite.db"
        return Room.databaseBuilder<AppDatabase>(name = dbPath)
    }

    @OptIn(ExperimentalForeignApi::class)
    private fun documentDirectory(): String {
        val url = NSFileManager.defaultManager.URLForDirectory(
            directory = NSDocumentDirectory,
            inDomain = NSUserDomainMask,
            appropriateForURL = null, create = false, error = null
        )
        return requireNotNull(url?.path)
    }
}

// androidMain — Context.getDatabasePath
class AndroidDatabaseFactory(private val context: Context) : DatabaseFactory {
    override fun createBuilder(): RoomDatabase.Builder<AppDatabase> {
        val dbFile = context.getDatabasePath("sugarlite.db")
        return Room.databaseBuilder<AppDatabase>(
            context = context.applicationContext,
            name = dbFile.absolutePath
        )
    }
}

Both platforms use the same database filename (sugarlite.db), with the DatabaseFactory implementation injected via Koin per platform.

One-Time SwiftData → Room Migration

Users who installed the app before Room KMP still had legacy SwiftData stores on their devices. We built a SwiftDataMigrationManager to handle this one-time migration:

// SwiftDataMigrationManager.swift
@MainActor
final class SwiftDataMigrationManager {
    func migrateIfNeeded(context: ModelContext) async {
        let dao = Shared.CloudSourceProviderKt.getMigrationMetadataDao()
        // Already migrated?
        if let meta = try? await dao.getByKey(key: "swift_data_imported"),
           meta.swiftDataImported { return }

        // Read old data from SwiftData → write to Room KMP
        await performMigration(context: context)
    }

    private func performMigration(context: ModelContext) async {
        let descriptor = FetchDescriptor<UserProfile>()
        let oldProfiles = try? context.fetch(descriptor)
        for profile in oldProfiles ?? [] {
            let dto = profile.toDto()
            try? await Shared.CloudSourceProviderKt.getUserProfileLocalSource().upsert(dto: dto)
        }
        // ... same for BloodSugarRecord, FoodRecord, ExerciseRecord

        // Mark migration complete
        try? await Shared.CloudSourceProviderKt.getMigrationMetadataDao()
            .upsert(MigrationMetadataEntity(swiftDataImported: true))
    }
}

The migration runs once at app launch, then never again. Legacy SwiftData model code stays in the project (read-only), but all new data goes through Room KMP.

Database Schema Migrations

The Room database evolved from version 3 to 12 across 9 incremental migrations. Here are some notable ones:

The table-rebuild pattern is a common Room migration technique:

val MIGRATION_5_6 = object : Migration(5, 6) {
    override fun migrate(db: SupportSQLiteDatabase) {
        db.execSQL("""
            CREATE TABLE food_glycemic_responses_new (... new schema, without food_name)
        """)
        db.execSQL("INSERT INTO food_glycemic_responses_new SELECT ... FROM food_glycemic_responses")
        db.execSQL("DROP TABLE food_glycemic_responses")
        db.execSQL("ALTER TABLE food_glycemic_responses_new RENAME TO food_glycemic_responses")
        // Rebuild indices
        db.execSQL("CREATE INDEX index_food_glycemic_responses_uid ON food_glycemic_responses(uid)")
    }
}

Gotcha: RTrees and ZIP Format

During prototyping, an CREATE INDEX IF NOT EXISTS index_xyztree ... in a migration script would fail on certain SQLite builds. R*Tree indices can only be created locally — copying them across schemas requires creating a virtual table first, inserting rows one at a time, then rebuilding the associated indices. We ultimately dodged this by dropping the no-longer-needed index in migration v10→v11 rather than trying to port it over.

🔧 expect/actual: Elegant Platform Abstractions

After migrating ViewModels and Room, over 85% of the code lives in shared/. What about the remaining platform-specific bits?

Kotlin’s expect/actual mechanism lets you declare interfaces in commonMain and provide platform implementations in androidMain/iosMain. sugarlite has exactly 5 expect/actual declarations, each intentionally lightweight:

1. Platform Info

// commonMain
expect object PlatformInfo {
    val platform: String       // "ios" / "android"
    val osVersion: String      // "17.5" / "14"
    val deviceModel: String    // "iPhone15,2" / "Pixel 8"
    val appVersion: String     // "1.2.3"
}

// iosMain
actual object PlatformInfo {
    actual val platform: String = "ios"
    actual val osVersion: String get() = UIDevice.currentDevice.systemVersion
    actual val deviceModel: String get() = UIDevice.currentDevice.model
    actual val appVersion: String get() =
        NSBundle.mainBundle.objectForInfoDictionaryKey("CFBundleShortVersionString") as? String ?: "unknown"
}

// androidMain
actual object PlatformInfo {
    actual val platform: String = "android"
    actual val osVersion: String get() = Build.VERSION.RELEASE
    actual val deviceModel: String get() = Build.MODEL
    actual var appVersion: String = "unknown"

    fun init(context: Context) {
        val pkgInfo = context.packageManager.getPackageInfo(context.packageName, 0)
        appVersion = pkgInfo.versionName ?: "unknown"
    }
}

Used for: app launch logging, attaching device context to feedback submissions, and the User-Agent header in Supabase requests.

2. Device Language

// commonMain
expect fun getDeviceLanguageCode(): String

// iosMain
actual fun getDeviceLanguageCode(): String = NSLocale.currentLocale.languageCode ?: "en"

// androidMain
actual fun getDeviceLanguageCode(): String = java.util.Locale.getDefault().language

Used for: Supabase Edge Function Accept-Language headers and default language selection on first launch.

3. UUID Generation

// commonMain
expect fun generateUUID(): String

// iosMain
actual fun generateUUID(): String = platform.Foundation.NSUUID().UUIDString()

// androidMain
actual fun generateUUID(): String = java.util.UUID.randomUUID().toString()

Used for: generating unique IDs for records created offline (before syncing to Supabase).

4. DI Platform Module

// commonMain
expect val platformModule: Module

This is the “heaviest” expect/actual — it wires platform-specific implementations into Koin:

// iosMain
actual val platformModule: Module = module {
    single<DatabaseFactory> { IOSDatabaseFactory() }
    single<HealthDataSyncRepository> { HealthDataSyncRepositoryIos() }
    single<SettingsRepository> { SettingsRepositoryIos() }
}

// androidMain
actual val platformModule: Module = module {
    single<DatabaseFactory> { AndroidDatabaseFactory(androidContext()) }
    single<HealthDataSyncRepository> { HealthDataSyncRepositoryAndroid(androidContext()) }
    single<SettingsRepository> { SettingsRepositoryAndroid(androidContext()) }
}

// KoinHelper.kt — iOS-side Koin bootstrap
fun doInitKoin() {
    initKermitForIos()
    startKoin {
        modules(sharedModule, platformModule)  // platformModule from expect/actual
    }
}

The SwiftUI entry point calls KoinHelperKt.doInitKoin() — that’s all the initialization iOS needs.

5. Room Constructor (Code-Generated)

// commonMain — actual is generated by Room KSP
@Suppress("NO_ACTUAL_FOR_EXPECT")
expect object AppDatabaseConstructor : RoomDatabaseConstructor<AppDatabase>

This one is generated at compile time — no handwritten actual needed.

expect/actual Design Principles

5 declarations, fewer than 200 lines of actual code total. We follow two rules:

1. Abstract data-source differences, not behavioral differences. iOS HealthKit and Android Health Connect may sound similar, but their APIs are fundamentally different shapes. Trying to paper over the gap with an expect interface would produce awkward signatures. HealthDataSyncRepositoryIos is currently a stub (all methods return empty) — it’ll be swapped for a real implementation when HealthKit integration is prioritized.
2. Keep granularity small. expect fun getDeviceLanguageCode(): String is much easier to maintain than expect class LocaleManager. Each expect does exactly one thing; each platform implementation has zero extra dependencies and is trivial to test.

🔌 SKIE & CloudSourceProvider: Kotlin-Swift Interop Best Practices

For Swift code to call into the KMP shared module, Kotlin/Native compiles it into an Objective-C-compatible framework. But the default Kotlin→ObjC mapping is rough: suspend functions become completion-handler callbacks, Flow is invisible, and StateFlow becomes Kotlinx_coroutines_coreStateFlow.

SKIE fixes all of this. Configuration is minimal:

// shared/build.gradle.kts
plugins {
    alias(libs.plugins.skie)  // 0.10.13, zero config needed
}

kotlin {
    iosTarget.binaries.framework {
        baseName = "Shared"
        isStatic = true
        export(libs.androidx.lifecycle.viewmodel)  // export for iOS visibility
    }
}

No custom skie {} block required. SKIE enables Feature_CoroutinesInterop by default, automatically converting:

• suspend fun → Swift async throws
• Flow<T> / StateFlow<T> → Swift AsyncSequence
• All types get Swift-readable names

The CloudSourceProvider Pattern

With SKIE handling the function signature bridging, we designed a centralized entry point — CloudSourceProvider.kt — that uses KoinComponent to pull instances from the DI container and exposes them as top-level functions to Swift:

// commonMain, exposed to Swift via SKIE
internal object KoinProvider : KoinComponent {
    fun provideBloodSugarLocalSource(): BloodSugarLocalSource = get()
    fun provideMembershipRepository(): MembershipRepository = get()
    // ...
}

// Ongoing subscriptions: return Flow → SKIE → Swift AsyncSequence
fun getBloodSugarRecordsByUid(uid: String): Flow<List<BloodSugarRecordDto>> =
    KoinProvider.provideBloodSugarLocalSource().getByUidFlow(uid.lowercase())

fun observeMembershipState(): Flow<MembershipState> =
    KoinProvider.provideMembershipRepository().membershipState

// Write operations: suspend → SKIE → Swift async throws
@Throws(HttpRequestException::class, RestException::class, IOException::class)
suspend fun saveBloodSugarRecord(dto: BloodSugarRecordDto): BloodSugarRecordDto =
    KoinProvider.provideBloodSugarRepository().save(dto)

// Single-record lookups: plain suspend
suspend fun getBloodSugarRecordById(id: String): BloodSugarRecordDto? =
    KoinProvider.provideBloodSugarLocalSource().getById(id)

A few lessons from production:

• Ongoing subscriptions use Flow: getBloodSugarRecordsByUid() returns Flow — the iOS side uses for await to react to database changes in real time.
• One-shot operations use suspend: saveBloodSugarRecord() — Swift side calls try await directly.
• @Throws matters: Without it, Kotlin exceptions surface as generic NSError on the Swift side. With it, Swift can catch by specific exception type.

The Swift Call-Site Experience

import Shared

// Ongoing subscription — SKIE converts Flow to AsyncSequence
let flow = Shared.CloudSourceProviderKt.getBloodSugarRecordsByUid(uid: userId)
for await records in flow {
    self.records = records
}

// One-shot write
try await Shared.CloudSourceProviderKt.saveBloodSugarRecord(dto: newRecord)

// Subscribe to membership state
let stateFlow = Shared.CloudSourceProviderKt.observeMembershipState()
for await state in stateFlow {
    self.membershipState = state
}

No callbacks, no delegates, no completion handlers. This is the value of SKIE — Kotlin code that feels almost as native in Swift as Swift code does.

⚠️ Kotlin-Swift Exception Handling: Making Errors Flow Across Languages

A smooth calling path is one thing, but exception handling is an easy trap to fall into. Kotlin and Swift have fundamentally different error models — Kotlin has no checked exceptions (everything is thrown at runtime), while Swift uses throws + do/catch with explicit error typing. What happens when a Kotlin exception crosses the Kotlin/Native boundary into Swift?

What Happens Without @Throws — More Than “Can’t Tell Them Apart”

Kotlin and Swift’s exception models are fundamentally different. Kotlin exceptions are all unchecked — you can’t see what a function might throw from its signature. Swift requires compile-time declaration via throws.

Let’s start with the wrong way. Suppose CloudSourceProvider has a suspend function without @Throws:

// ❌ No @Throws
suspend fun saveBloodSugarRecord(dto: BloodSugarRecordDto): BloodSugarRecordDto =
    KoinProvider.provideBloodSugarRepository().save(dto)

Many developers see throws in the compiled Swift signature and assume catch will handle it:

// The compiled Swift signature does show throws
func saveBloodSugarRecord(dto: BloodSugarRecordDto) async throws -> BloodSugarRecordDto

The reality is much more dangerous. Per the official KMP documentation, when a suspend function lacks @Throws:

• CancellationException → propagates as NSError (this is the sole exception)
• Any other exception (HttpRequestException, IOException, custom business exceptions…) → treated as unhandled, reaches Swift and causes program termination — i.e. a crash

The following code looks harmless, but if anything other than CancellationException is thrown, your app crashes outright:

do {
    let result = try await Shared.CloudSourceProviderKt.saveBloodSugarRecord(dto: record)
} catch {
    // ⚠️ This catch will NEVER see HttpRequestException!
    // The exception already crashed the program before reaching Swift
}

Regular (non-suspend) functions are even stricter: they propagate zero Kotlin exceptions at all. Any exception crossing the boundary is an instant crash.

So @Throws isn’t an “add better types to your errors” optimization — it’s a safety gate. Only the types (and their subclasses) listed in the @Throws annotation are safely converted to NSError. Exceptions not on the list still crash.

@Throws: A Safety Whitelist

The @Throws annotation tells the Kotlin/Native compiler: “Only forward the types (and their subclasses) listed here as safe NSError. Everything else still crashes.” That’s why every write function in CloudSourceProvider carries precise exception declarations:

// ✅ With @Throws — only these exception types propagate safely
@Throws(
    HttpRequestException::class,      // HTTP timeout, connection failure
    RestException::class,             // Supabase REST error (e.g. constraint violation)
    UnknownRestException::class,      // Unclassified HTTP error
    HttpRequestTimeoutException::class, // Ktor client timeout
    IOException::class,               // Network I/O error
    CancellationException::class,     // Coroutine cancellation
)
suspend fun saveBloodSugarRecord(dto: BloodSugarRecordDto): BloodSugarRecordDto =
    KoinProvider.provideBloodSugarRepository().save(dto)

With @Throws in place, the Swift side can catch by type — and only these types will ever reach the catch block:

do {
    let result = try await Shared.CloudSourceProviderKt.saveBloodSugarRecord(dto: record)
} catch let error as Shared.HttpRequestException {
    // Network timeout — tell the user "saved locally, will sync later"
    toast("Network unavailable — saved offline")
    // Room KMP data is still there; next sync will push it up
} catch let error as Shared.RestException {
    // Supabase backend error — log silently, degrade
    AppLogger.error("Backend rejected: \(error)")
} catch {
    // ⚠️ If we ever reach here, it's an exception type NOT in the @Throws list
    // — which means the program likely already crashed
    // So make sure your @Throws list is complete
}

The key win: network timeouts don’t alarm the user; backend errors are logged silently. Two scenarios, two different UX paths.

CancellationException Must Be Re-Thrown

A subtle but critical detail: CancellationException in Kotlin is not a normal exception — it’s the cancellation signal for structured concurrency. Any try/catch in Kotlin code that may run inside a coroutine must re-throw it:

suspend fun initializeSupabaseAuth() {
    try {
        val loaded = sharedSupabaseClient.auth.loadFromStorage()
        // ...
    } catch (e: IllegalStateException) {
        AppLogger.i("AuthInit") { "No saved session locally" }
    } catch (e: Exception) {
        if (e is CancellationException) throw e  // ← MUST re-throw!
        AppLogger.e("AuthInit", e) { "Failed to initialize Supabase Auth" }
    }
}

Swallowing CancellationException prevents the coroutine scope from cancelling properly, which can cause resource leaks — imagine a ViewModel that’s already been destroyed, but its coroutine is still running a Room query.

When NOT to Use @Throws

Not every function needs @Throws. Query functions (returning Flow or plain suspend) can sometimes skip it — but only if exceptions are caught on the Kotlin side first:

1. Exceptions inside Flow propagate through the Flow itself — SKIE wraps them into AsyncSequence iteration, and the Swift side catches them in for try await. Crucially, a Flow exception terminates the stream but does not crash the program.
2. One-shot suspend lookups (like getBloodSugarRecordById) are risky without @Throws. While “not found” → null doesn’t need exceptions, a Room database error (e.g. corruption) would crash the app. The safe pattern is to wrap in try/catch on the Kotlin side and convert to null:

// Exceptions caught on the Kotlin side — safe to omit @Throws
suspend fun getBloodSugarRecordById(id: String): BloodSugarRecordDto? =
    try {
        KoinProvider.provideBloodSugarLocalSource().getById(id)
    } catch (e: Exception) {
        AppLogger.e("Lookup failed", e)
        null
    }

Only omit @Throws when you’re certain all exceptions are handled before crossing the language boundary.

Practical Takeaways

1. Every function exposed across the language boundary needs @Throws with a complete type list. This isn’t a code style preference — it’s “crash vs. not crash.” A single unlisted exception type is a time bomb.
2. Be precise AND complete with your @Throws types. Don’t write @Throws(Exception::class) — that’s just as unhelpful as no @Throws at all. Separate HttpRequestException, RestException, and IOException. At the same time, make sure every exception type that could actually be thrown is in the list.
3. Never swallow CancellationException. Add if (e is CancellationException) throw e in every generic Kotlin-side catch block. Even when it’s declared in the @Throws list, swallowing it still prevents proper coroutine cancellation.
4. If you want to skip @Throws on a query function, absorb all exceptions on the Kotlin side first. Convert them to null, a default value, or a sealed result type — make sure nothing propagates across the boundary unhandled.

💰 RevenueCat KMP: Unified Subscription Management

Subscriptions are the core of our revenue. Before the migration, iOS used the RevenueCat iOS SDK; Android hadn’t been implemented yet. If each platform maintained its own, behavioral consistency was at risk — the “does this free user see this feature?” check had to be identical logic on both platforms.

RevenueCat provides an official revenuecat/purchases-kmp SDK (we’re on 3.1.0) with an API very close to the native SDKs. We implemented the full MembershipRepository in commonMain:

class MembershipRepositoryImpl(
    private val userProfileRepository: UserProfileRepository
) : MembershipRepository {

    private val _membershipState = MutableStateFlow(MembershipState.FREE)
    override val membershipState: StateFlow<MembershipState> = _membershipState.asStateFlow()

    // PurchasesDelegate: receives real-time RevenueCat updates
    private val delegate = object : PurchasesDelegate {
        override fun onCustomerInfoUpdated(customerInfo: CustomerInfo) {
            val state = customerInfo.toMembershipState()
            emitAndPersist(state)  // update local state + sync to Supabase
        }
    }

    override fun configure(apiKey: String, appUserId: String?, debugMode: Boolean) {
        Purchases.configure(apiKey = apiKey) { this.appUserId = appUserId }
        Purchases.sharedInstance.delegate = delegate
    }

    override suspend fun purchase(packageIdentifier: String): Result<MembershipState> {
        return runCatching {
            val offerings = Purchases.sharedInstance.awaitOfferings()
            val pkg = offerings.current!!.availablePackages
                .find { it.identifier == packageIdentifier }!!
            val result = Purchases.sharedInstance.awaitPurchase(pkg)
            result.customerInfo.toMembershipState()
        }
    }

    // CustomerInfo → MembershipState mapping
    private fun CustomerInfo.toMembershipState(): MembershipState {
        val entitlement = entitlements["SugarLite Pro"]
        return if (entitlement?.isActive == true) {
            val expirationDate = entitlement.expirationDateMillis?.let {
                Instant.fromEpochMilliseconds(it)
            }
            val tier = if (expirationDate == null) MembershipTier.LIFETIME
                       else MembershipTier.PREMIUM
            MembershipState(tier = tier, expirationDate = expirationDate, isActive = true)
        } else {
            MembershipState.FREE
        }
    }
}

Key design:

• Single source of truth: _membershipState is the canonical membership state. RevenueCat real-time updates flow through PurchasesDelegate.onCustomerInfoUpdated, which automatically updates this state.
• Persisted to Supabase: Every state change is also written to user_profiles.membership_type, ensuring the backend stays in sync.
• Unified across platforms: The configure() method takes an apiKey parameter. iOS and Android each pass their own API key; the rest of the logic is 100% shared.

On the iOS side, initialization is a single line:

Shared.CloudSourceProviderKt.configureRevenueCat(
    apiKey: Constants.revenueCatApiKey,
    appUserId: uid,
    debugMode: isDebug
)

📋 Migration Strategy: What We Learned (Continued)

Building on Part 1’s five principles, here’s what the subsequent migration taught us:

1. ViewModels CAN be migrated — with SKIE. The StateFlow → AsyncSequence conversion is smooth enough that dual-maintaining ViewModels is no longer necessary. The iOS side still needs a thin StateHolder for @Published bridging, but that’s typically under 50 lines per ViewModel — trivially cheap.
2. Choose KMP-first for local storage. Room KMP is production-ready: 14 entities, 13 DAOs, and 12 schema versions all work reliably. New local storage requirements should go straight into Room KMP — don’t reach for platform-specific solutions (SwiftData, SharedPreferences, etc.).
3. Don’t over-abstract with expect/actual. Our 5 declarations cover UUIDs, device language, platform info, DB paths, and DI wiring — and that’s enough. HealthDataSyncRepositoryIos is intentionally a stub because trying to force HealthKit and Health Connect into the same interface would make the code harder to read, not easier.
4. RevenueCat KMP is worth adopting. The official KMP SDK covers the core flow (login, purchase, restore, offerings), and PurchasesDelegate’s real-time push mechanism works well. A few advanced features (like Paywalls) can be supplemented at the platform layer when needed.
5. SKIE makes the bridging layer virtually disappear. CloudSourceProvider just pulls instances from Koin and exposes function signatures — zero glue code. suspend automatically becomes async, Flow automatically becomes AsyncSequence. New team members seeing import Shared + try await find it surprisingly natural.

This article is based on the real migration of SugarLite. If you’re interested in KMP cross-platform development, download the app and give it a try.

📚 References

• Part 1: sugarlite’s KMP Incremental Migration
• Room KMP Official Documentation
• SKIE — Swift Kotlin Interface Enhancer
• RevenueCat KMP SDK
• Kotlin expect/actual Documentation

This post is based on the real migration process of the sugarlite project.

SugarLite started as a pure iOS app built with SwiftUI + MVVM + Supabase Swift SDK. When the Android version became a priority, copying the business logic over to Kotlin would have doubled the maintenance burden — network layer, data models, and business rules all needed dual-platform upkeep. That’s why we chose Kotlin Multiplatform: the shared/ module carries all cross-platform business logic, while the iOS side only keeps SwiftUI and system framework calls (HealthKit, SwiftData, WidgetKit).

This post walks through the entire migration — from architectural refactoring to CI/CD adaptation, the pitfalls we hit, and what we learned along the way.

🏗️ Pre-Migration: MVVM Clean Architecture Refactoring

Before introducing KMP, we did an architectural refactor. The core goal was straightforward: decouple ViewModels from any external frameworks so that swapping out the underlying layer for Kotlin wouldn’t ripple upward.

The resulting dependency flow:

View → ViewModel → Protocol ← Repository → External Frameworks

Layer responsibilities:

The value of this refactoring became crystal clear later on: when we swapped the Supabase client from Swift SDK to the KMP shared module, the ViewModel layer required zero changes — it only depends on interfaces like FoodReferenceRepositoryProtocol, not on whether the implementation is Swift or Kotlin.

📦 Introducing the KMP Project Baseline

After the architecture cleanup, we introduced KMP. The project root structure became:

├── iosApp/                    # Original iOS project moved here
│   ├── BloodSugarApp/         # SwiftUI source
│   ├── BloodSugarApp.xcodeproj
│   └── ci_scripts/            # Xcode Cloud build scripts
├── composeApp/                # Compose Multiplatform (Android entry point)
├── shared/                    # KMP shared module
│   ├── src/commonMain/kotlin/ # Cross-platform business logic
│   ├── src/androidMain/kotlin/
│   └── src/iosMain/kotlin/
├── gradle/
├── build.gradle.kts
└── settings.gradle.kts

Key configuration in shared/build.gradle.kts:

kotlin {
    android { ... }

    listOf(iosX64(), iosArm64(), iosSimulatorArm64()).forEach { iosTarget ->
        iosTarget.binaries.framework {
            baseName = "Shared"
            isStatic = true
        }
    }

    sourceSets {
        commonMain.dependencies {
            implementation(libs.kotlinx.serialization.json)
            implementation(libs.kotlinx.coroutines.core)
            implementation(libs.kotlinx.datetime)
            api(libs.supabase.auth)
            api(libs.supabase.postgrest)
            api(libs.supabase.storage)
            api(libs.ktor.client.core)
            implementation(libs.koin.core)
        }
        androidMain.dependencies {
            implementation(libs.ktor.client.cio)
        }
        iosMain.dependencies {
            implementation(libs.ktor.client.darwin)
        }
    }
}

Two design decisions worth noting:

1. isStatic = true: A static framework avoids dynamic library signing issues in Xcode Cloud builds.
2. api(libs.supabase.*): Supabase libraries are exposed as API dependencies. The iOS side could theoretically use them directly, but we hide the details behind a wrapper layer.

🔄 Sinking the Data Layer: Supabase Swift SDK → KMP Shared

This is the most critical step — moving all Supabase calls scattered across iOS repositories down into shared/src/commonMain/kotlin/.

DTO Layer

Created @Serializable Kotlin DTOs for all 13 tables, using snake_case for field mapping:

@Serializable
data class FoodReferenceDto(
    val id: String,
    val name: String,
    val name_en: String? = null,
    val category: String,
    val gi_value: Int? = null,
    val calories: Double? = null,
    // ...
)

CloudSource Wrappers

Each domain entity gets a CloudSource that encapsulates CRUD operations:

class FoodReferenceCloudSource(private val client: SupabaseClient) {
    suspend fun fetchAll(): List<FoodReferenceDto> {
        return client.from("food_reference").select().decodeList()
    }

    suspend fun fetchPage(
        page: Int, pageSize: Int,
        searchText: String?, category: String?
    ): List<FoodReferenceDto> {
        // Build PostgREST query...
    }
}

Koin DI Module

All CloudSources are registered in the sharedModule:

val sharedModule = module {
    single { SupabaseClientProvider.client }
    single { FoodReferenceCloudSource(get()) }
    single { BloodSugarCloudSource(get()) }
    // ...
}

🔌 Incremental Adoption on iOS

KMP migration doesn’t have to happen all at once. Our strategy was: “new features go straight into KMP; old code gets replaced gradually.” Here’s how we migrated FoodReferenceRepository:

Bridging Layer

First, expose Koin container instances to Swift. In iosMain:

fun doInitKoin() {
    startKoin { modules(sharedModule) }
}

In commonMain, expose accessor functions:

private object KoinProvider : KoinComponent {
    fun provideFoodReferenceCloudSource(): FoodReferenceCloudSource = get()
}

fun getFoodReferenceCloudSource(): FoodReferenceCloudSource =
    KoinProvider.provideFoodReferenceCloudSource()

Kotlin top-level functions compile to Swift global functions, so the iOS side can directly call CloudSourceProviderKt.getFoodReferenceCloudSource().

App Launch Initialization

In the SwiftUI entry point’s init():

init() {
    KoinHelperKt.doInitKoin()
    AppLogger.database.info("KMP Koin initialized")
}

Repository Transformation

Before (Swift Supabase SDK):

import Supabase

final class FoodReferenceRepository {
    private var supabaseClient: SupabaseClient

    func fetchAll() async throws -> [FoodReferenceDTO] {
        let dtos: [FoodReferenceDTO] = try await supabaseClient
            .from("food_reference")
            .select()
            .execute()
            .value
        return dtos
    }
}

After (KMP CloudSource):

import Shared

final class FoodReferenceRepository {
    private let cloudSource: FoodReferenceCloudSource

    init() {
        self.cloudSource = CloudSourceProviderKt.getFoodReferenceCloudSource()
    }

    func fetchAll() async throws -> [FoodReferenceDTO] {
        let kmpDtos = try await cloudSource.fetchAll()
        return kmpDtos.map { FoodReferenceDTO(fromKmp: $0) }
    }
}

Only three things changed: import Supabase → import Shared, raw PostgREST queries → wrapped cloudSource.fetchAll(), and a new fromKmp DTO conversion helper.

This pattern can be replicated for every repository. The team can migrate one at a time, in priority order.

⚙️ Xcode Cloud CI/CD Adaptation

The biggest challenge after introducing KMP was CI/CD. Xcode Cloud build environments don’t include Java or Gradle by default, yet our iOS builds now depend on the Shared.framework compiled by Kotlin/Native.

ci_pre_xcodebuild.sh: Environment Setup

We handle Java and Gradle installation in Xcode Cloud’s ci_pre_xcodebuild.sh phase:

#!/bin/sh
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
cd "$ROOT_DIR"

export GRADLE_USER_HOME="$ROOT_DIR/.gradle"
export HOMEBREW_NO_AUTO_UPDATE=1

resolve_java_home() {
  if [ -n "${JAVA_HOME:-}" ] && [ -x "$JAVA_HOME/bin/java" ]; then
    echo "$JAVA_HOME"
    return 0
  fi

  for version in 21 17 11; do
    if JAVA_CANDIDATE=$(/usr/libexec/java_home -v "$version" 2>/dev/null); then
      if [ -x "$JAVA_CANDIDATE/bin/java" ]; then
        echo "$JAVA_CANDIDATE"
        return 0
      fi
    fi
  done

  if command -v brew >/dev/null 2>&1; then
    for formula in openjdk@17 openjdk; do
      if brew list --versions "$formula" >/dev/null 2>&1; then
        JAVA_CANDIDATE="$(brew --prefix "$formula")/libexec/openjdk.jdk/Contents/Home"
        if [ -x "$JAVA_CANDIDATE/bin/java" ]; then
          echo "$JAVA_CANDIDATE"
          return 0
        fi
      fi
    done
  fi

  return 1
}

ensure_java() {
  if JAVA_CANDIDATE="$(resolve_java_home)"; then
    export JAVA_HOME="$JAVA_CANDIDATE"
  else
    echo "[Xcode Cloud] Java not found. Installing openjdk@17 via Homebrew..."
    brew install openjdk@17
    export JAVA_HOME="$(brew --prefix openjdk@17)/libexec/openjdk.jdk/Contents/Home"
  fi
  export PATH="$JAVA_HOME/bin:$PATH"
}

ensure_java
echo "[Xcode Cloud] JAVA_HOME=$JAVA_HOME"
java -version
./gradlew --version

Build Phase Script: Compiling the Kotlin Framework

A Run Script Phase added in Xcode’s Build Phases:

#!/bin/sh
set -euo pipefail

ROOT_DIR="$(cd "$(dirname "$0")/../.." && pwd)"
cd "$ROOT_DIR"

# Xcode Preview optimization: skip Gradle build
if [ "${OVERRIDE_KOTLIN_BUILD_IDE_SUPPORTED:-}" = "YES" ]; then
  echo "Skipping Gradle build due to OVERRIDE_KOTLIN_BUILD_IDE_SUPPORTED=YES"
  exit 0
fi

# Resolve JAVA_HOME (same logic as ci_pre_xcodebuild.sh)
# ...

export PATH="$JAVA_HOME/bin:$PATH"
./gradlew :shared:embedAndSignAppleFrameworkForXcode

This script runs on every Xcode build, invoking the Gradle task to compile Kotlin/Native and embed the framework. For local development, we skip it during Xcode Previews via the OVERRIDE_KOTLIN_BUILD_IDE_SUPPORTED environment variable to avoid slowing things down.

Gotchas

Sentry Script vs. Widget Extension Build Dependency Cycle: A cryptic build failure turned out to be an implicit dependency between Sentry’s “Upload Debug Symbols” script and the Widget Extension’s Embed phase. The fix was simple — just drag the Sentry script to run after the Embed phase.

Unstable Java Runtime Resolution: Java installation paths vary across Xcode Cloud macOS images. Our final resolve_java_home() uses a multi-level fallback: system JAVA_HOME → /usr/libexec/java_home → Homebrew → brew list. This redundant lookup strategy ensures Java is found on any image version.

📋 Migration Strategy: What We Learned

Looking back, we followed a few principles:

1. DTOs/Models first: Data models have the fewest platform dependencies — sink them first.
2. Repository Protocols next: Interfaces define contracts; implementations can stay on iOS for now.
3. UseCases/Services after that: Pure computation logic is a natural fit for cross-platform.
4. ViewModels stay put: Keep @Observable on iOS to preserve the SwiftUI reactive experience.
5. New features go straight into KMP. For existing code, evaluate whether it can move to shared/ when it gets touched. Don’t migrate for migration’s sake — avoid the “big bang” rewrite.

This article is based on the real migration of SugarLite. If you’re interested in KMP cross-platform development, download the app and give it a try.

📚 References

• Kotlin Multiplatform Official Docs
• Supabase Kotlin Client
• Xcode Cloud Custom Build Scripts

This post is based on the real migration process of the SugarLite project.

I’ve previously covered the basics of CC Switch. Today, let’s take a closer look at the Claude Desktop panel — added in recent versions specifically for connecting the official Claude Desktop client to third-party providers.

In CC Switch, “Claude” and “Claude Desktop” are two separate panels. They map to Claude Code (the CLI) and Claude Desktop (the desktop client), respectively. Claude Desktop uses its own 3P profile config rather than ~/.claude/settings.json. The two panels are distinguished by a small badge on the icon.

What it does

The Claude Desktop panel keeps things straightforward:

• Connect Claude Desktop to Anthropic-compatible third-party providers
• Set up model mappings for non-Claude models like DeepSeek, Kimi, DouBao, OpenAI, and Gemini
• Reuse Copilot / Codex OAuth-based providers
• Switch between Claude Desktop’s official mode and third-party providers with a single click

macOS and Windows are supported. Linux can’t yet write Claude Desktop 3P configs. You’ll need to restart Claude Desktop after switching — it doesn’t hot-reload the way Claude Code does.

One thing to note: Claude Desktop’s 3P profile does not go through CC Switch’s MCP / Skills sync — those are managed independently on the desktop side.

Getting started

1. Switch to the Claude Desktop panel

Select Claude Desktop from the app switcher on the left.

If you don’t see it, check Settings → General → App Visibility to make sure it isn’t hidden.

2. Import or add a provider

One-click import from Claude Code (recommended)

Most users start by configuring providers in Claude Code, then want to bring the same set over to Claude Desktop. If the panel is empty the first time you open it, just click Import existing providers from Claude Code.

This pulls your Claude Code providers straight into the Claude Desktop panel — no need to re-enter endpoint URLs, API keys, or default models. The import logic works roughly like this:

• Providers with an existing matching ID are skipped
• Providers with direct-connectable, model-name-safe configs are imported in direct mode
• Providers that need model translation are imported in model-mapping mode
• ANTHROPIC_DEFAULT_SONNET_MODEL, ANTHROPIC_DEFAULT_OPUS_MODEL, and ANTHROPIC_DEFAULT_HAIKU_MODEL are automatically converted to Desktop’s Sonnet / Opus / Haiku mappings
• Legacy [1M] suffixes become supports1m flags in the Desktop profile
• Providers whose model mappings can’t be determined are skipped

After importing, check each provider’s model mapping against your actual upstream models. Non-Claude models like Kimi, DeepSeek, GLM, and DouBao typically need model-mapping mode.

Add manually

If there’s nothing to import, or you want a different provider just for Claude Desktop, click the + button in the top-right corner.

Three options:

• Preset provider: Pick from built-in presets, only fill in your API key
• Custom provider: Manually enter the name, endpoint, API key, and model settings
• Claude Desktop Official: Revert to Claude Desktop’s official login mode

For standard Anthropic Messages API-compatible providers, the flow is simple: choose a preset or custom → enter API key → confirm the endpoint → turn off “Requires model mapping” → add.

3. Switch and restart Claude Desktop

Click Enable on the provider card, then fully quit and restart Claude Desktop.

Claude Desktop doesn’t hot-reload. Closing the chat window isn’t enough — exit from the tray or make sure the process is completely stopped.

Two working modes

Direct mode

Use this when your provider offers a native Anthropic Messages API. CC Switch points Claude Desktop’s 3P profile directly to the provider’s endpoint:

{
  "inferenceProvider": "gateway",
  "inferenceGatewayBaseUrl": "https://api.example.com",
  "inferenceGatewayAuthScheme": "bearer",
  "inferenceGatewayApiKey": "your API key"
}

Requirements: the provider exposes a native Anthropic Messages API, uses claude-* or anthropic/claude-* model IDs, and doesn’t need format translation. In direct mode, you don’t need to keep CC Switch’s local routing running.

“Manually specify Claude Desktop model list” is an advanced option. Most native Claude providers don’t need it — Claude Desktop reads /v1/models automatically. Only fill it in if the provider’s /v1/models is unavailable or returns model names Claude Desktop doesn’t recognize.

Model-mapping mode

Use this when your provider doesn’t offer Claude-series models (deepseek, kimi, etc.) or its API format needs translation by CC Switch.

With “Requires model mapping” enabled, Claude Desktop connects to CC Switch’s local gateway:

http://127.0.0.1:15721/claude-desktop

CC Switch acts as middleware: it exposes safe claude-* model routes to Claude Desktop, maps the selected model role to the actual upstream model, translates between Anthropic / OpenAI / Gemini formats as needed, and authenticates using the credentials stored in CC Switch.

Supported formats:

In model-mapping mode, Claude Desktop only sees claude-* routing model names. The real upstream model names stay inside CC Switch’s provider config and never appear in the Claude Desktop profile.

Configuring model mappings

The key idea: Claude Desktop now rejects non-claude-* model names, so you need CC Switch to do a round of role mapping.

For example, using Kimi in Claude Desktop:

Using DeepSeek:

Suggested roles:

If your provider only has one model, just configuring Sonnet is enough. Model-mapping mode requires at least one valid mapping.

Local routing

Model-mapping mode depends on CC Switch’s local routing for request translation. The toggle is hidden by default — you’ll need to enable it manually.

Go to Settings → Routing → Local Routing, and turn on Show local routing toggle on main page.

Back in the Claude Desktop panel, you’ll see the local routing toggle in the top-right corner.

Status meanings:

Only providers with “Requires model mapping” enabled need local routing. Direct providers don’t.

If another app is using proxy takeover, turning off local routing may be blocked. Go to the routing service area in Settings, disable the takeover for that app, then stop local routing.

Reverting to official Claude Desktop

To switch back to official login:

1. Select Claude Desktop Official
2. Click Enable
3. Restart Claude Desktop

CC Switch restores Claude Desktop’s official 1P mode and cleans up the 3P profile. Official mode needs no API key or local routing.

When importing from Claude Code, a Claude Desktop Official entry is automatically added so you can switch back anytime.

Config file locations

CC Switch writes to Claude Desktop’s 3P config directories:

macOS:

~/Library/Application Support/Claude/claude_desktop_config.json
~/Library/Application Support/Claude-3p/claude_desktop_config.json
~/Library/Application Support/Claude-3p/configLibrary/_meta.json
~/Library/Application Support/Claude-3p/configLibrary/00000000-0000-4000-8000-000000157210.json

Windows:

%LOCALAPPDATA%\Claude\claude_desktop_config.json
%LOCALAPPDATA%\Claude-3p\claude_desktop_config.json
%LOCALAPPDATA%\Claude-3p\configLibrary\_meta.json
%LOCALAPPDATA%\Claude-3p\configLibrary\00000000-0000-4000-8000-000000157210.json

Config files are maintained by CC Switch — editing them manually isn’t recommended. If things get out of sync, re-enabling the current provider usually fixes it.

FAQ

I switched but Claude Desktop hasn’t changed?

Fully quit and restart Claude Desktop. It only reads the 3P profile on startup — no hot reload.

Requests fail with a model-mapping provider?

Checklist: Is CC Switch running → Is Claude Desktop local routing on → Are the API key and endpoint correct → Did you fill in the actual request model in the mapping → Did you restart Claude Desktop after switching.

Why am I getting errors in direct mode?

Direct mode requires the provider to offer a native Anthropic Messages API and accept the model names Claude Desktop uses. If your provider uses OpenAI, Gemini, or non-Claude model IDs, turn on “Requires model mapping.”

My custom brand name doesn’t show in the model picker?

Edit the provider, fill in the “Menu display name” in the model mapping, then re-enable the provider and restart Claude Desktop.

Can I close CC Switch?

In direct mode, yes — once Claude Desktop loads the config after restart, you don’t need local routing running. In model-mapping mode, no — CC Switch must stay running with the local routing toggle on.

Will my real upstream model names be written to Claude Desktop?

Not in model-mapping mode. The Claude Desktop profile only contains safe claude-* routes and display names. The actual upstream model names stay in CC Switch’s provider config, and the mapping happens at the local gateway.

Summary

The Claude Desktop panel in CC Switch essentially brings the provider management that was previously CLI-only to the desktop side. If you’ve already set up a bunch of providers in CC Switch, the one-click import from Claude Code is the fastest path.

Direct mode is hassle-free; model-mapping mode is flexible. If you mainly use Claude-series models, direct mode is all you need. If you want to use Kimi, DeepSeek, or other non-Claude models inside Claude Desktop, model-mapping mode with local routing gets it done.

In the world of AI programming tools, Claude Code is undoubtedly one of the most powerful choices today. However, with major cloud service providers launching their own LLM APIs, how to conveniently switch between different providers has become a practical need. Today, I’ll introduce two tools: cc switch and cc desktop switch, which help you quickly switch Claude Code model providers.

Project Links:

• cc switch: farion1231/cc-switch (54.9k ⭐)
• cc desktop switch: lonr-6/cc-desktop-switch

What is cc switch

cc switch is a cross-platform desktop application specifically designed for managing provider configurations for five major AI programming CLI tools: Claude Code, Codex, Gemini CLI, OpenCode, and OpenClaw.

Core Features

1. Unified Management: One app manages provider configurations for five CLI tools simultaneously
2. 50+ Provider Presets: Built-in presets for AWS Bedrock, NVIDIA NIM, and numerous community relay services - copy your API key and import with one click
3. One-click Switching: Switch providers from main interface or system tray
4. Unified MCP & Skills Management: One panel to manage MCP servers and Skills across four apps with bidirectional sync
5. Proxy & Failover: Local proxy supports format conversion, auto-failover, circuit breaker, provider health monitoring
6. Usage & Cost Tracking: Dashboard shows spending, requests, and token trend charts
7. Session Manager: Browse, search, and restore conversation history across all apps
8. Cloud Sync: Sync configurations via Dropbox, OneDrive, iCloud, NAS, or WebDAV servers
9. Cross-Platform: Native desktop app for Windows, macOS, and Linux, built with Tauri 2

Supported Apps

• Claude Code: Anthropic’s AI programming assistant
• Codex: OpenAI’s programming CLI tool
• Gemini CLI: Google’s AI CLI tool
• OpenCode: Open-source AI programming tool
• OpenClaw: Emerging AI programming tool

Installing cc switch

macOS Users

# Install via Homebrew (Recommended)
brew tap farion1231/ccswitch
brew install --cask cc-switch

# Update
brew upgrade --cask cc-switch

Or download CC-Switch-v{version}-macOS.dmg from the Releases page.

Windows Users

Download from Releases:

• CC-Switch-v{version}-Windows.msi installer
• CC-Switch-v{version}-Windows-Portable.zip portable version

Linux Users

# Arch Linux
paru -S cc-switch-bin

# Or download deb/rpm/AppImage from Releases

What is cc desktop switch

cc desktop switch is a lightweight configuration tool specifically for the Claude Desktop official desktop client. Unlike cc switch which targets CLI users, cc desktop switch focuses on the desktop version of Claude Desktop.

Core Features

1. Multiple API Providers: DeepSeek, Kimi, Zhipu GLM, Alibaba Cloud Bailian, SiliconFlow, and more
2. One-click Config Write: Write selected provider config directly to Claude Desktop’s local configuration
3. Direct Connection Mode: Anthropic-compatible interfaces use direct connection by default; Claude Desktop can continue working after closing the app
4. Experimental Compatibility Mode: Retains local forwarding support for OpenAI/new-api/reverse-proxy interfaces
5. Basic Connectivity Testing: Tests basic connectivity to provider API addresses
6. Bilingual Interface: Supports Chinese/English interface and light/dark mode

Basic Usage

cc switch Usage

1. Add Provider: Click “Add Provider” → Choose a preset or create custom configuration
2. Switch Provider:
   • Main UI: Select provider → Click “Enable”
   • System Tray: Click provider name directly (instant effect)
3. Takes Effect: Restart your terminal or the corresponding CLI tool (Claude Code does not require restart)
4. Back to Official: Add “Official Login” preset, restart CLI tool, then follow its login/OAuth flow

cc desktop switch Usage

1. Launch CC Desktop Switch
2. Operate in the popup desktop window
3. Select a quick preset, fill in your API key, adjust model mapping if needed
4. Click “Apply to Claude Desktop”
5. Fully restart Claude Desktop to test

Note: Simply closing the chat window is usually not enough. Please exit Claude from the system tray, or confirm no Claude processes remain in the task manager.

Practical Usage Experience

I’ve been using cc switch for a while, and the overall experience is quite good. Here are my thoughts:

Advantages

1. Convenient switching: More intuitive than manually editing config files
2. Multi-app support: Supports Claude Code, Codex, Gemini CLI, and more simultaneously
3. Cost monitoring: Clearly shows usage of each provider
4. Tray operation: Minimizes to tray without consuming too many resources
5. Rich presets: Built-in 50+ provider presets, no manual configuration needed

Conclusion

cc switch and cc desktop switch provide convenient provider management solutions for Claude Code users. Their focus is slightly different:

• cc switch: For CLI users, unified management of Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw
• cc desktop switch: For Claude Desktop desktop client users, more lightweight, focused on desktop client

Whether you need to test different model effects or find the most cost-effective provider, these tools can meet your needs. If you’re using Claude Code, give these tools a try - I’m sure they’ll give you a great experience.

If you’re interested in AI programming tools, you can also check out my previous articles: Neovim Beginner’s Guide Series, which contains a lot of content about editor configuration and AI integration.

Before using Neovim, I spent a lot of time configuring my own Neovim setup—whether it was plugins, key mappings, or the UI, I put a lot of effort into it.
However, maintaining a personal configuration is honestly quite time-consuming, especially with plugin updates, version upgrades, and other maintenance tasks.

LazyVim is a Neovim distribution that comes with a large number of pre-configured plugins.
It is essentially ready to use out of the box, making it convenient and efficient. The extensive default configurations reduce the onboarding time.
The only downside is that the key mappings might not match what you’re used to, requiring some modifications or adaptation.

Installation

Installing LazyVim is actually quite simple. First, open the official starter template: LazyVim/starter.
Click Use this template in the top right corner to fork the template into your own repository.
Next, back up your existing local Neovim configuration and clone your forked repository.

In short, you just need one command to back up your existing setup and another to clone the new repository.
For more details, refer to the official installation guide.

Once installed, launching Neovim will give you a fully configured environment with numerous built-in features—essentially ready to use out of the box.

After setting up LazyVim, make sure your system has fzf installed.

Configuration Overview

In the LazyVim project, configurations are divided into two main parts: base configuration (config) and plugins (plugins).

Config

The config directory mainly contains fundamental settings. This folder is divided into four files:

• options.lua for basic settings
• keymaps.lua for key mappings
• autocmds.lua for automation commands
• lazy.lua for LazyVim initialization

Plugins

LazyVim comes with many pre-installed plugins, some of which are enabled by default, while others need to be manually activated.
If you want to override existing plugin configurations or install new ones, you can add your configurations in this folder and then reference them in the main init.lua file.

Key Mappings

LazyVim includes many pre-configured plugins with default key mappings. The default Leader key is Space.
You can customize the key mappings to match your preferences, or simply press the Leader key to view all available key mappings.

I find the default key mappings to be quite reasonable, and after using them a few times, they become easy to remember.
Other than modifying the blink candidate selection keys, I haven’t made any additional changes.
You can also find the default key mappings in the official keymaps documentation.

LazyExtras

LazyVim includes several pre-enabled plugins by default. However, there are additional optional plugins that can be enabled as needed.
You can use the :LazyExtras command to browse these additional plugins. If you find something useful, you can enable it by pressing x.

Note that after enabling some plugins, you may need to restart Neovim for the changes to take effect.

CAP Theory

One of the most important theories in distributed systems is the CAP theory. This theory was proposed by computer scientist Eric Allen Brewer from the University of California, Berkeley, in 2000. It was later proven by researchers from MIT in 2002, turning the hypothesis into a theorem.

The CAP theorem proposes three aspects for distributed systems:

• Consistency: The data among multiple replicas remains consistent.
• Availability: Each request can receive a normal, error-free response, but there’s no guarantee that the data is the most recent.
• Partition Tolerance: Even if a node in the system fails, the system can still provide consistency and availability of services externally.

For instance, consider a current system with two databases, DB0 and DB1.

Consistency (C)

Consistency means that when data changes (i.e., after a write operation), the data retrieved (i.e., read operation) is the same regardless of who accesses it or where it’s accessed from.

For example, when user 1 modifies data in DB0 through a write operation, the data retrieved by either user 1 or user 2, from either DB0 or DB1, should be exactly the same. This is what’s referred to as consistency.

In other words, if data in DB0 is modified, mechanisms should inform DB1 of the modification to ensure that the data remains consistent across different databases.

Availability (A)

When a user sends a relevant request, both DB0 and DB1 will return the corresponding data, but it’s not necessary to ensure that the data is consistent.

Partition Tolerance (P)

If DB0 and DB1 encounter issues, such as network problems or other hardware issues, leading to a failure in communication between them, DB0 and DB1 become two partitions. Despite this communication failure, DB0 and DB1 can still provide services externally.

However, such situations are unavoidable in practical systems, making partition tolerance a necessary condition.

CP or AP

Since the CAP theorem’s three rules cannot be simultaneously satisfied, three scenarios arise, as depicted in the figure above: meeting any two rules results in CA, CP, and AP architectures. However, partition tolerance is mandatory, leaving us with CP and AP relationships.

Common CP software includes Zookeeper, which sacrifices availability for consistency. Zookeeper ensures consistent results can be obtained at any time, but it doesn’t guarantee that every service request can be fulfilled.

In AP architecture, data consistency isn’t as critical, allowing different services to return different data.

Limitations of CAP

The CAP theory isn’t perfect and faces many challenges. For example, to maintain data consistency between DB0 and DB1, communication is required, which takes time. This can lead to situations where data is out of sync at certain times, such as in master-slave machines with significant master-slave delays, resulting in inconsistent data retrieval by users.

The CAP theory isn’t entirely a matter of choosing three out of two (or one of two), for instance, if the probability of partition tolerance occurrence is very low, sacrificing A and C isn’t necessary.

BASE Theory

The BASE theory is considered an extension of the CAP theory, providing a balance between consistency and availability. In CAP, consistency refers to data remaining consistent at all times, known as strong consistency. As mentioned earlier, ensuring consistent data at all times is challenging. The BASE theory supplements this problem. Since achieving strong consistency is difficult, ensuring eventual consistency based on the system’s own business characteristics is also acceptable.

The BASE theory was proposed by eBay engineer Dan Pritchett.

BASE stands for “Basically Available, Soft State, and Eventually Consistent.”

Basically Available

Basically available means that the system can still be used even in the event of a failure, although there may be some problems compared to normal systems, such as response time and sacrificing some functionalities.

Soft State

Soft state refers to the system allowing for intermediate states in data, such as the intermediate states during database master-slave synchronization.

Eventually Consistent

Eventually consistent emphasizes that after going through the aforementioned soft states, the data eventually achieves consistency.

The BASE theory proposes sacrificing strong consistency of systems to ensure availability, allowing the system’s data to be inconsistent for a period but requiring eventual consistency.

References

Understanding CAP Theory of Distributed Systems in One Article

Distributed Architecture: CAP Theory/AP Architecture/CP Architecture

Neovim Beginner’s Guide (Part Three): LSP Configuration (Part One) discussed what LSP is, how to configure it, and how to start it. Now, let’s proceed with other configurations related to LSP. This chapter mainly covers the following aspects: code highlighting, code formatting, and UI beautification related to LSP.

⚠️ Error Warning Prompt

After setting up LSP, when we write code and encounter errors, corresponding reminders will appear. As shown in the following image:

Currently, the errors are represented by letters, for example, warnings are shown as W, which is not very visually appealing. For this, Vim provides relevant interfaces that can be configured using interfaces, neovim-diagnostic.

Continue to create a ui.lua directory under the LSP folder.

-- lsp/ui.lua
-- Icon for error warnings
vim.diagnostic.config({
        virtual_text = true,
        signs = true,
 -- Update prompts even in insert mode, setting to true may affect performance
 update_in_insert = true,
})
local signs = { Error = "󰅙", Info = "󰋼", Hint = "󰌵", Warn = "" }
for type, icon in pairs(signs) do
 local hl = "DiagnosticSign" .. type
 vim.fn.sign_define(hl, { text = icon, texthl = hl, numhl = hl })
end

Where vim.diagnostic.config is used to configure the prompt text, virtual_text is for error message prompts.

🔅 Code Highlighting

In the current setup, code highlighting is not perfect and requires a plugin to achieve it. tree-sitter is a high-performance code highlighting rendering tool written in Rust, which many editors use for highlighting, such as Zed. Based on tree-sitter, we can make the highlighting in Neovim more perfect.

This image is from nvim-treesitter. The left side shows the code highlighting without treesitter enabled, and the right side shows the effect after enabling it, which is quite noticeable.

After installing tree-sitter, you can install specific language highlights using TSInstall, for example, to install Rust highlighting, you can directly use the TSInstall rust command, or use TSUpdate rust to update. The overall installation and configuration are relatively simple, so I won’t explain it further here.

📃 Formatting

Code formatting is a very important and frequently used feature. There are many ways to format code in Neovim. Here, we mainly introduce null-ls. Unfortunately, null-ls has been archived, but fortunately, its fork project none-ls has been revived and is still compatible with null-ls configuration. If you were previously using null-ls, you only need to change the dependency address from jose-elias-alvarez/null-ls.nvim to nvimtools/none-ls.nvim.

After installing none-ls, you can install relevant formatters using Mason, for example, to install the lua formatter. Open the installation interface with the :Mason command.

Select stylua for installation. After installation, you can configure it. Create a new file named nonels.lua under lua/lsp.

-- lsp/nonels.lua
-- Even if none-ls is used, we still get null-ls here
local status, null_ls = pcall(require, "null-ls")
if not status then
	vim.notify("Null-ls not found")
	return
end

local formatters = null.builtins.format

null_ls.setup({
    sources = {
        -- Stylua
        formatters.stylua,
        -- Other formatter methods
    },
})

This allows us to perform relevant formatting when writing code. As mentioned in the previous article, key bindings are also provided. Use <Leader>= for formatting.

🎨 Autocomplete Beautification

As mentioned earlier, we achieved autocomplete through the cmp plugin, which can supplement code from different sources.

When using some IDEs or editors, icons are displayed in the completion options to identify the types of completions, such as variables, class names, methods, or interfaces.

Autocomplete style with RustRover.

Autocomplete style in VS Code.

Through configuration, we can achieve similar autocomplete styles in Neovim.

The current autocomplete effect is as follows, with the completion fields on the left and the completion types identified by text on the right.

There is a plugin called lspkind, which, when installed, combined with our cmp, achieves the above styles.

Create a file kind.lua under lsp to configure kind, which can be found in lspkind.

-- lsp/kind.lua
local lspkind = require("lspkind")
lspkind.init({
	mode = "symbol_text",
	preset = "codicons",
	symbol_map = {
		Text = "󰉿",
		Method = "󰆧",
		Function = "󰊕",
		Constructor = "",
		Field = "󰜢",
		Variable = "󰀫",
		Class = "󰠱",
		Interface = "",
		Module = "",
		Property = "󰜢",
		Unit = "󰑭",
		Value = "󰎠",
		Enum = "",
		Keyword = "󰌋",
		Snippet = "",
		Color = "󰏘",
		File = "󰈙",
		Reference = "󰈇",
		Folder = "󰉋",
		EnumMember = "",
		Constant = "󰏿",
		Struct = "󰙅",
		Event = "",
		Operator = "󰆕",
		TypeParameter = ""
	},
})

You can configure icons for each category here, and after configuration, apply them in cmp. The main purpose is to modify the style of prompts. Here, we mainly refer to a style on Github. Configuration is done in the formatting section.

-- cmp.lua
cmp.setup({
    -- Omitted other code
    formatting = {
        completion = { border = { "╭", "─", "╮", "│", "╯", "─", "╰", "│" }, scrollbar = "║" },
        documentation = {
            border = { "╭", "─", "╮", "│", "╯", "─", "╰", "│" },
            scrollbar = "║",
        },
        format = lspkind.cmp_format({
            mode = "symbol",
            maxwidth = 20,
            ellipsis_char = "...",
            before = function(entry, vim_item)
                -- Get the full snippet (and only keep first line)
                local word = entry:get_insert_text()
                if entry.completion_item.insertTextFormat == types.lsp.InsertTextFormat.Snippet then
                    word = vim.lsp.util.parse_snippet(word)
                end
                word = str.oneline(word)
                if entry.completion_item.insertTextFormat == types.lsp.InsertTextFormat.Snippet
                    and string.sub(vim_item.abbr, -1, -1) == "~" then
                    word = word .. "~"
                end
                vim_item.abbr = word
                return vim_item
            end,
        }),
    }
    -- Omitted other code
})

The style after completion will be similar to VS Code as shown in the image below:

lspsage

lspsage greatly enhances the experience of Neovim’s LSP. Most of lspsaga’s functions aim to enhance and beautify the original LSP. You can refer to the specific documentation on nvimdev.

lspsaga’s main features include:

• Finder: A UI for advanced LSP symbol search
• Diagnostic: Navigate between diagnostics and display them in a beautiful floating window
• Peek Definition / Type Definition: View definition/type definition
• Hover: More visually appealing hover operations
• Rename: LSP rename and asynchronous project search and replace
• Call hierarchy: Incoming/outgoing calls
• Code Action: Beautiful code operation UI with real-time preview
• LightBulb: Similar to VSCode’s light bulb, indicating possible code actions
• Breadcrumb: IDE symbol outline similar to WinBar
• Outline: IDE symbol outline similar to IDE
• Implementation: Easily view the number of implementations and quickly jump to them
• Float Terminal: A simple floating terminal
• Miscellaneous: Options for all modules

The above information is from the official documentation.

Finder

The Finder feature provides a UI similar to VS Code for viewing variables/functions, allowing you to see where a variable/function is defined and called.

-- keybindings.lua
-- Other code
pluginKeys.mapLSP = function(mapbuf) {
    -- Other code
    mapbuf("n", "gf", ":Lspsaga lsp_finder<CR>", opt) -- Added
    -- Other code
}

This way, pressing gf in normal mode will bring up the Finder window shown above.

Code Action

Code Action is a very important feature that provides suggestions or code improvements based on the context of the code. For example, in the provided code snippet, Code Action suggests converting the concatenation to a literal.

Code Action is not provided by lspsaga, but lspsaga provides a beautiful interface for it. Wherever Code Action is available, there will be a yellow light bulb 💡 prompt.

Below is how to bind the shortcut:

-- keybindings.lua
pluginKeys.lspKeybinding = function(mapbuf)
 -- Omitted other code
 -- code action
 -- mapbuf("n", "<leader>ca", ":lua vim.lsp.buf.code_action()<CR>", opt) -- Original
 mapbuf("n", "<leader>ca", ":Lspsaga code_action<CR>", opt) -- Replace with this
end

Float Terminal

lspsaga provides a floating terminal window where you can execute any command in the terminal. You can bind a shortcut in keybindings, or use the default shortcut t to open and close the terminal.

lspsaga provides many other features, each of which is helpful. Here, we’ve covered the common functionalities and configurations of LSP. You can install and configure the ones you need.

Here’s my configuration youngxhui/nvim for reference.

Conclusion

Using Vim/Neovim does have a learning curve, especially if you’re used to arrow keys for navigation. However, once you’re completely comfortable with h, j, k, and l for cursor movement, you’re not far from mastering Vim/Neovim.

After getting accustomed to Vim’s style, you might try to adopt Vim shortcuts in your other editors/IDEs. Once you’re familiar with Vim shortcuts, you’ll truly feel your fingers dancing on the keyboard.

Whether it’s Neovim or related plugins, updates are frequent. Perhaps by the time you read this article, many of the configurations mentioned may have become obsolete, or the related plugins may have been discontinued. This article is just a starting point, and I believe you’ll find the Neovim configuration that suits you best.

I believe people who like Vim/Neovim are curious and enjoy tinkering. It’s this curiosity that drives us forward step by step.

With these thoughts, I conclude here, and in the next article, we’ll discuss DAP.

🧩 What is LSP

For an editor, to accomplish tasks like auto-completion, finding relevant definitions, etc., extensive development is required. Different editors require separate development efforts for different languages. The Language Server Protocol (LSP) streamlines this process. LSP, short for Language Server Protocol, defines the protocol used between editors and language services. As long as the relevant language supports LSP, editors can implement features like auto-completion by meeting specific requirements, ensuring a consistent user experience across different editors.

Currently, many editors support LSP, including the renowned VS Code. Vim 8 and Neovim also support LSP starting from versions after a certain point. For a list of supported editors/IDEs, you can refer to the official LSP website, and for supported languages, check here.

Neovim already supports LSP, and you can find detailed instructions on how to configure an LSP in the relevant documentation. However, the configuration process is relatively cumbersome, so the official team provides another library, nvim-lspconfig, to streamline this process. Let’s configure Neovim’s LSP using this plugin.

nvim-lspconfig

Similar to installing other plugins, we only need to add relevant configurations in the plugins_config.lua file. I won’t delve into that here. Once installed, configuring it enables LSP, it’s that simple. For example, to support Rust’s LSP, only simple configuration is needed:

lspconfig.rust_analyzer.setup {
  settings = {
    ['rust-analyzer'] = {},
  },
}

However, Neovim only serves as the LSP client, meaning there needs to be an LSP server. The rust_analyzer configured above is Rust’s language server, requiring us to install the server. The server for rust_analyzer can be found at rust-lang/rust-analyzer. You need to download and install the server so that you can enjoy the benefits of LSP when writing Rust code.

But there are a few inconveniences with this approach, or rather, considerations:

1. For users of multiple languages, manually installing multiple LSP servers is required. Currently, there isn’t a unified download/installation address for LSP servers, necessitating manual search.
2. Every time the server updates, a reinstallation is necessary.
3. When switching devices, it’s not plug-and-play; you need to repeat the aforementioned process.

Faced with these inconveniences, you might have thought of various solutions, such as scripting a one-click installation and update of commonly used LSP servers. Just as you’re thinking, let me introduce you to our second hero today, williamboman/mason.nvim.

🗃️ mason.nvim

Mason is a plugin that conveniently manages LSP servers, DAP servers, linters, and formatting tools. Once installed, the aforementioned problems cease to exist.

To better integrate Mason with nvim-lspconfig, you also need to install another plugin, williamboman/mason-lspconfig.nvim.

Installation steps are similar and won’t be reiterated here; we’ll focus on the configuration. Here, to distinguish it from other plugins, we create a new folder named -lsp in the lua directory to exclusively store LSP configurations.

Configuring Mason

First, let’s load our plugins. Create a mason.lua file in the lsp folder and add the following configuration:

-- mason.lua
local mason_status, mason = pcall(require, "mason")
if not mason_status then
 vim.notify("Could not find mason")
 return
end

local nlsp_status, nvim_lsp = pcall(require, "lspconfig")
if not nlsp_status then
 vim.notify("Could not find lspconfig")
 return
end

local mlsp_status, mason_lspconfig = pcall(require, "mason-lspconfig")
if not mlsp_status then
 vim.notify("Could not find mason-lspconfig")
 return
end

mason.setup()
mason_lspconfig.setup({})

📤 Installing LSP Servers

After configuring, restart nvim. Now you can manage LSP servers using Mason by simply typing :Mason. You’ll see the following interface:

You can see how to use it through the help on the interface. By selecting different numerical options, e.g., 2 for LSP and 3 for DSP, etc., you can navigate to different server projects. Since we’re focusing on LSP today, you can directly press 2 to access the LSP interface and install an LSP. Use j and k to navigate. The first server to install is the Lua language server: lua-language-server. This server provides language services for Lua, meaning we’ll have LSP support when configuring Neovim or writing Lua code. Press i to install.

After a short while, installation completes. Next is the configuration to let Neovim know that our LSP is installed and should be started when appropriate.

-- mason.lua
nvim_lsp.lua_ls.setup({
 on_init = function(client)
  local path = client.workspace_folders[1].name
  if not vim.loop.fs_stat(path .. "/.luarc.json") and not vim.loop.fs_stat(path .. "/.luarc.jsonc") then
   client.config.settings = vim.tbl_deep_extend("force", client.config.settings, {
    Lua = {
     runtime = {
      version = "LuaJIT",
     },
     workspace = {
      checkThirdParty = false,
      library = {
       vim.env.VIMRUNTIME,
      },
     },
    },
   })

   client.notify("workspace/didChangeConfiguration", { settings = client.config.settings })
  end
  return true
 end,
})

With this configuration, Lua’s LSP is successfully set up. When writing Lua scripts, errors will be indicated. Of course, this is just the basic functionality of LSP. Advanced features like code navigation, auto-completion, etc., require further configuration.

Most LSP configurations can be found in [server_configurations.md](https://github.com/neovim/nvim-lspconfig/blob/master/doc/server_configurations.md

). The lua_ls is no exception; the above configuration was directly copied from the document 😄.

Currently, the LSP configuration supports features like code navigation, code action, etc. For example, to view documentation for the current variable or function, you can use the command :lua vim.lsp.buf.hover().

Other relevant commands include: