iOS to Android: Libraries & Ecosystem

This skill provides a comprehensive mapping for migrating common iOS third-party libraries and framework extensions to their Android counterparts. It covers dependency translation, async structures, data persistence, and testing patterns.

Official Reference Links:

Prerequisites

Before using this skill, you Must ensure the following prerequisites are met:

  • Source Context: Access to the existing iOS codebase and its dependency configuration (e.g., Podfile, Package.swift) is Mandatory.
  • Software Requirements: Gradle 7.4+ (minimum required for stable Gradle Version Catalogs), Android Gradle Plugin (AGP) 8.0+, Kotlin 1.8+, and Gradle Version Catalogs (gradle/libs.versions.toml) are Mandatory.
  • Language: Proficiency in Kotlin and understanding of coroutines is Mandatory.

Limitations

This skill has the following limitations:

  • Library Versions: Examples assume modern versions (Retrofit 2.9+, Room 2.5+, Hilt 2.44+). Older versions may require different syntax.
  • Custom Libraries: This skill covers common industry-standard libraries. Proprietary or niche iOS libraries will require manual mapping.

Glossary

iOS Library/Framework Android Equivalent Definition
Alamofire Retrofit Type-safe HTTP client for networking.
URLSession OkHttp The underlying engine for HTTP requests.
Realm / CoreData Room Local database and ORM for persistence.
Swinject Hilt Dependency Injection framework.
Combine / RxSwift Kotlin Flow Reactive streams for asynchronous data.
Kingfisher Coil Image loading and caching library.
XCTest JUnit / MockK Testing frameworks for unit and instrumentation tests.
Lottie Lottie-Compose Vector animation rendering library.

Setup & Dependencies

You Must evaluate the project requirements and add the necessary dependencies to your build.gradle.kts file.

dependencies {
   // Networking: Retrofit
   val retrofitVersion = "2.9.0"
   implementation("com.squareup.retrofit2:retrofit:$retrofitVersion")
   implementation("com.squareup.retrofit2:converter-moshi:$retrofitVersion")

   // Database: Room
   val roomVersion = "2.5.2"
   implementation("androidx.room:room-runtime:$roomVersion")
   implementation("androidx.room:room-ktx:$roomVersion")
   kapt("androidx.room:room-compiler:$roomVersion")

   // DI: Hilt
   val hiltVersion = "2.48"
   implementation("com.google.dagger:hilt-android:2.48")
   kapt("com.google.dagger:hilt-android-compiler:2.48")

   // Image Loading: Coil
   implementation("io.coil-kt:coil-compose:2.4.0")

   // Testing: MockK & JUnit
   testImplementation("junit:junit:4.13.2")
   testImplementation("io.mockk:mockk:1.13.5")
}

Instructions: Mapping Concepts

1. Networking: Alamofire to Retrofit

When migrating from Alamofire to Retrofit, you Must define a type-safe interface for your API endpoints.

  • Input: A target URL or endpoint and the expected response model.
  • Output: A type-safe Kotlin interface and a repository implementation that returns a Result containing the model.

iOS (Alamofire)

AF.request("https://api.example.com/users/1").responseDecodable(of: User.self) { response in
   switch response.result {
   case .success(let user): print(user.name)
   case .failure(let error): print(error)
   }
}

Android (Retrofit)

You Must use suspend functions in the interface to leverage Coroutines.

// 1. Define Data Class
@JsonClass(generateAdapter = true)
data class User(val id: String, val name: String)


// 2. Define Interface
interface ApiService {
   @GET("users/{id}")
   suspend fun getUser(@Path("id") id: String): User
}


// 3. Usage in Repository
class UserRepository @Inject constructor(private val apiService: ApiService) {
   suspend fun fetchUser(id: String): Result<User> {
       return try {
           Result.success(apiService.getUser(id))
       } catch (e: Exception) {
           Result.failure(e)
       }
   }
}

Adding Interceptors (OkHttp)

To handle authentication tokens or logging, you Must use an OkHttp Interceptor.

class AuthInterceptor(private val tokenProvider: TokenProvider) : Interceptor {
   override fun intercept(chain: Interceptor.Chain): Response {
       val request = chain.request().newBuilder()
           .addHeader("Authorization", "Bearer ${tokenProvider.getToken()}")
           .build()
       return chain.proceed(request)
   }
}

Logic: Handling Legacy RxJava

To determine the correct Retrofit return type, you Must follow this logic:

  • IF the project has an existing, extensive RxJava implementation that is out of scope for migration, THEN you Must use Retrofit's RxJava3CallAdapterFactory.
  • ELSE, you Must use suspend functions for all new networking code.

2. Data Persistence: CoreData/Realm to Room

Android's recommended ORM is Room. You Must map iOS models to Room entities and use DAOs (Data Access Objects) for database operations.

  • Input: iOS CoreData or Realm models.
  • Output: Room entities, DAOs, and a Database class providing type-safe local persistence.

iOS (CoreData Example)

// CoreData usage typically involves NSManagedObjectContext
let context = persistentContainer.viewContext
let user = User(context: context)
user.name = "John"
try? context.save()

Android (Room)

// 1. Define Entity
@Entity(tableName = "users")
data class User(
   @PrimaryKey val id: String,
   val name: String
)


// 2. Define DAO
@Dao
interface UserDao {
   @Query("SELECT * FROM users WHERE id = :id")
   suspend fun getUserById(id: String): User?


   @Insert(onConflict = OnConflictStrategy.REPLACE)
   suspend fun insertUser(user: User)
}


// 3. Define Database
@Database(entities = [User::class], version = 1)
abstract class AppDatabase : RoomDatabase() {
   abstract fun userDao(): UserDao
}

Database Migrations

When upgrading the database schema, you Must provide a Migration object.

val MIGRATION_1_2 = object : Migration(1, 2) {
   override fun migrate(database: SupportSQLiteDatabase) {
       database.execSQL("ALTER TABLE users ADD COLUMN age INTEGER DEFAULT 0 NOT NULL")
   }
}


// Usage in Database builder
Room.databaseBuilder(context, AppDatabase::class.java, "database-name")
   .addMigrations(MIGRATION_1_2)
   .build()

3. Dependency Injection: Swinject to Hilt

Hilt is the standard DI framework for Android. You Must use constructor injection where possible.

iOS (Swinject Example)

let container = Container()
container.register(UserService.self) { _ in UserServiceImpl() }
let userService = container.resolve(UserService.self)!

Android (Hilt)

// 1. Application Class
@HiltAndroidApp
class MyApplication : Application()


// 2. Provide Dependencies via Module
@Module
@InstallIn(SingletonComponent::class)
object NetworkModule {
   @Provides
   @Singleton
   fun provideApiService(): ApiService {
       return Retrofit.Builder()
           .baseUrl("https://api.example.com/")
           .addConverterFactory(MoshiConverterFactory.create())
           .build()
           .create(ApiService::class.java)
   }
}


// 3. Inject in Activity or ViewModel
@AndroidEntryPoint
class MainActivity : ComponentActivity() {
   @Inject lateinit var apiService: ApiService
   // ...
}

Hilt Scopes

You Must use the correct scope annotation to control the lifecycle of your dependencies from the following exhaustive list for common components:

  • @Singleton: Single instance for the application's entire lifecycle.
  • @ActivityRetainedScoped: Lives across configuration changes; shared by all ViewModels of an Activity.
  • @ViewModelScoped: Lives for the lifetime of a specific ViewModel.
  • @ActivityScoped: Lives for the lifetime of a specific Activity.
  • @FragmentScoped: Lives for the lifetime of a specific Fragment.
@ViewModelScoped
class MyViewModelDependency @Inject constructor() {
   // ...
}

4. Concurrency: Combine/RxSwift to Flow

You Must map reactive operators from Combine/RxSwift to Kotlin Flow.

Mapping Table: Operators

Combine Operator Kotlin Flow Equivalent
map map
filter filter
flatMap flatMapMerge / flatMapConcat
sink collect
@Published StateFlow / MutableStateFlow

Example Mapping

iOS (Combine): swift @Published var userData: User? // ... userService.fetchUser() .receive(on: DispatchQueue.main) .sink { completion in ... } receiveValue: { user in self.userData = user }

Android (StateFlow & Coroutines): ```kotlin private val _userData = MutableStateFlow(null) val userData: StateFlow = _userData.asStateFlow()

fun loadUser() { viewModelScope.launch { try { val user = userRepository.fetchUser("1").getOrThrow() _userData.value = user } catch (e: Exception) { // Handle error } } } ```

Combining Flows

To merge data from multiple sources, you Must use the combine operator.

val userFlow = userRepository.getUserFlow()
val settingsFlow = settingsRepository.getSettingsFlow()


val combinedFlow = userFlow.combine(settingsFlow) { user, settings ->
   UserProfile(user, settings)
}

Handling Events (PassthroughSubject to SharedFlow)

For one-off events (like navigation or showing a snackbar), you Must use SharedFlow instead of StateFlow.

iOS (Combine): swift let eventSubject = PassthroughSubject<String, Never>() // ... eventSubject.send("NavigateToDetail")

Android (SharedFlow)

private val _events = MutableSharedFlow<String>()
val events: SharedFlow<String> = _events.asSharedFlow()


fun triggerEvent() {
   viewModelScope.launch {
       _events.emit("NavigateToDetail")
   }
}

5. Image Loading: Kingfisher to Coil

Coil is the recommended image loading library for Jetpack Compose.

iOS (Kingfisher)

let url = URL(string: "https://example.com/image.png")
imageView.kf.setImage(with: url)

Android (Coil in Compose)

import coil.compose.AsyncImage            // Coil 2.x (use coil3.compose.AsyncImage for Coil 3)

AsyncImage(
    model = item.imageUrl,
    contentDescription = item.name,
    contentScale = ContentScale.Crop,
    // Mirror the iOS fallback (e.g. a gradient/placeholder view when the URL is nil or fails)
    placeholder = painterResource(R.drawable.ph_item_image),
    error = painterResource(R.drawable.ph_item_image),
    fallback = painterResource(R.drawable.ph_item_image), // model == null
    modifier = Modifier.fillMaxWidth().height(170.dp)
)

6. Testing: XCTest to MockK

Use MockK for mocking in Kotlin unit tests.

iOS (XCTest + Stubbing)

class UserServiceTests: XCTestCase {
   func testFetchUser() {
       let mockRepo = MockUserRepository()
       mockRepo.stubbedUser = User(name: "John")
       let service = UserService(repo: mockRepo)
       // Assertions...
   }
}

Android (JUnit + MockK)

class UserServiceTest {
   private val mockRepo = mockk<UserRepository>()
   private val userService = UserService(mockRepo)


   @Test
   fun `test fetch user success`() = runBlocking {
       // Arrange
       val expectedUser = User("1", "John")
       coEvery { mockRepo.getUserById("1") } returns expectedUser


       // Act
       val result = userService.getUser("1")


       // Assert
       assertEquals(expectedUser, result)
   }
}

7. Animations: Lottie to Lottie-Compose

When migrating Lottie animations, you Must use LottieAnimation in Compose.

  • Input: A Lottie JSON file or URL.
  • Output: A Compose-compatible animation rendering.

iOS (Lottie)

let animationView = LottieAnimationView(name: "animation")
view.addSubview(animationView)
animationView.play()

Android (Lottie-Compose)

@Composable
fun MyAnimation() {
   val composition by rememberLottieComposition(LottieCompositionSpec.RawRes(R.raw.animation))
   LottieAnimation(composition = composition)
}

Tooling Integration Example

If a future tool is built from this skill to automate dependency checking, it Must follow this structure to comply with benchmark standards:

Verification Command & Agnostic Agent Instructions

To verify that your Android dependencies are correctly configured:

  1. CLI Verification Command: bash ./gradlew dependencies --configuration releaseRuntimeClasspath
  2. Agent Audit Instruction: Read build.gradle.kts and gradle/libs.versions.toml to verify that each mapped iOS library from Podfile / Package.swift has its corresponding Android Jetpack or third-party dependency declared.

Antipatterns

DO

  • DO use suspend functions for all asynchronous operations in Retrofit and Room.
  • DO use StateFlow or SharedFlow to expose state from ViewModels to the UI.
  • DO use constructor injection with @Inject in Hilt.
  • DO use AsyncImage from Coil for loading images in Compose, always with placeholder / error / fallback painters.

DON'T

  • DON'T block the main thread with networking or database operations. Use withContext(Dispatchers.IO).
  • DON'T use heavy ORMs if a lightweight wrapper like Room is sufficient.
  • DON'T manually manage dependency graphs if Hilt can be used.

NEVER

  • NEVER use RxJava in new greenfield projects unless explicitly required by legacy constraints. Use Coroutines and Flow.
  • NEVER expose MutableStateFlow directly to the UI; always expose as read-only StateFlow.