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:
- Retrofit
- Save data in a local database using Room | Android Developers
- Dependency injection with Hilt | Android Developers
- Guide to coroutines | Kotlin
- Compose | Coil
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
Resultcontaining 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
suspendfunctions 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
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:
- CLI Verification Command:
bash ./gradlew dependencies --configuration releaseRuntimeClasspath - Agent Audit Instruction:
Read
build.gradle.ktsandgradle/libs.versions.tomlto verify that each mapped iOS library fromPodfile/Package.swifthas its corresponding Android Jetpack or third-party dependency declared.
Antipatterns
DO
- DO use
suspendfunctions for all asynchronous operations in Retrofit and Room. - DO use
StateFloworSharedFlowto expose state from ViewModels to the UI. - DO use constructor injection with
@Injectin Hilt. - DO use
AsyncImagefrom Coil for loading images in Compose, always withplaceholder/error/fallbackpainters.
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
RxJavain new greenfield projects unless explicitly required by legacy constraints. Use Coroutines and Flow. - NEVER expose
MutableStateFlowdirectly to the UI; always expose as read-onlyStateFlow.