Forem: Saad Alkentar

KMP Native UI networking with Ktro

Saad Alkentar — Mon, 30 Mar 2026 16:21:35 +0000

We have our dependency injection ready and have tested our dummy view model on both Android and iOS. It is time to get some data...

We need to pay attention to the project structure at this stage. Clean architecture has 3 layers,

data: contains data sources and repository implementation
domain: contains the abstract logic of the application
presentation or UI, contains the view models, actions, states, and screens

In KMP, the screens themselves are in the Native Projects, while the rest of the data, domain, and presentation are in the shared codebase.

What are the app features?

For our simple project, we will add two features.

Products feature: where we can list products and show their details.
Auth feature: Where we can fill in the login form and navigate to the home screen.

Where to get it from?

I found a website called dummy json that provides both Auth and Products endpoints. In this tutorial, we will only use the Products api. The auth will be used in another tutorial.

Setup Ktor client library

Let's start by updating the toml file. According to ktor docs we should add those libs.

[versions]
ktor = "3.4.1"

[libraries]
ktor-client-core = { module = "io.ktor:ktor-client-core", version.ref = "ktor" }
ktor-client-okhttp = { module = "io.ktor:ktor-client-okhttp", version.ref = "ktor" }
ktor-client-darwin = { module = "io.ktor:ktor-client-darwin", version.ref = "ktor" }

# ktor extensions
ktor-client-content-negotiation = { module = "io.ktor:ktor-client-content-negotiation", version.ref = "ktor" }
ktor-client-logging = { module = "io.ktor:ktor-client-logging", version.ref = "ktor" }
ktor-serialization-kotlinx-json = { module = "io.ktor:ktor-serialization-kotlinx-json", version.ref = "ktor" }
ktor-client-auth = { module = "io.ktor:ktor-client-auth", version.ref = "ktor" }

[bundles]
ktor = [
    "ktor-client-core",
    "ktor-client-content-negotiation",
    "ktor-client-auth",
    "ktor-client-logging",
    "ktor-serialization-kotlinx-json",
]

The next step is to update build.gradle

shared/build.gradle.kts


plugins {
    ...
    alias(libs.plugins.kotlinSerialization) // for model class serialization
}

kotlin {
    ...
    sourceSets {
        commonMain.dependencies {
            ...
            implementation(libs.koin.ktor)
            implementation(libs.bundles.ktor)
        }

        androidMain.dependencies {
            implementation(libs.ktor.client.okhttp)
        }

        nativeMain.dependencies {
            implementation(libs.ktor.client.darwin)
        }
        ...
    }
}

Set up Ktor with Koin

Let's start by creating the Ktor client and setting up the Logger, JSON serializer, content type, and timeout.

shared/commonMain/core/data/HttpClientFactory.kts

import io.ktor.client.HttpClient
import io.ktor.client.engine.HttpClientEngine
import io.ktor.client.plugins.HttpTimeout
import io.ktor.client.plugins.contentnegotiation.ContentNegotiation
import io.ktor.client.plugins.defaultRequest
import io.ktor.client.plugins.logging.LogLevel
import io.ktor.client.plugins.logging.Logger
import io.ktor.client.plugins.logging.Logging
import io.ktor.http.ContentType
import io.ktor.http.contentType
import io.ktor.serialization.kotlinx.json.json
import kotlinx.serialization.json.Json

object HttpClientFactory {

    fun create(engine: HttpClientEngine): HttpClient {
        return HttpClient(engine) {
            install(ContentNegotiation) {
                json(
                    json = Json {
                        ignoreUnknownKeys = true
                    }
                )
            }
            install(HttpTimeout) {
                socketTimeoutMillis = 20_000L
                requestTimeoutMillis = 20_000L
            }
            install(Logging) {
                logger = object : Logger {
                    override fun log(message: String) {
                        println(message)
                    }
                }
                level = LogLevel.ALL
            }
            defaultRequest {
                contentType(ContentType.Application.Json)
            }
        }
    }
}

Then, we create the client factory singleton to be used in data sources later

shared/commonMain/di/KoinModules.kt

val sharedModule = module {
    single { HttpClientFactory.create(get()) }
    ...
}

expect val platformModule: Module

Now for the module-level setup

shared/androidMain/di/PlatformModule.android.kt

import io.ktor.client.engine.HttpClientEngine
import io.ktor.client.engine.okhttp.OkHttp
import org.koin.dsl.module

actual val platformModule = module {
    single<HttpClientEngine> { OkHttp.create() }
}

shared/iosMain/di/PlatformModule.ios.kt

import io.ktor.client.engine.HttpClientEngine
import io.ktor.client.engine.darwin.Darwin
import org.koin.dsl.module

actual val platformModule = module {
    single<HttpClientEngine> { Darwin.create() }
}

Products Clean Architecture shared module

Create the product structure in the shared modules

-shared
--commonMein

---product

----data
-----ProductDataSource.kt
-----ProductRepositoryImpl.kt

----domain
-----models
-----ProductRepository.kt

----ui
-----ProductActions.kt
-----ProductState.kt
-----ProductViewModel.kt

JSON objects to Kotlin classes

Where to get the products from? For this tutorial, we can get it from dummy json api.
As always in clean architecture, we start from the domain layer.
We will use JSON To Kotlin Class to convert JSON to Kotlin classes

To parse JSON to Kotlin models, we start by left-clicking the models folder. With one click, we get the Product class (I've renamed every model to have model postfix. Make sure to annotate the classes as @Serializable
I grow not to trust the backend devs (even if it's me!). So I usually edit the advanced setting to make all fields nullable and to annotate them with Kotlin serialization

shared/commonMain/product/domain/models/ProductModel.kt

import kotlinx.serialization.Serializable

@Serializable
data class ProductModel(
    @SerialName("availabilityStatus")
    val availabilityStatus: String? = null,
    @SerialName("brand")
    val brand: String? = null,
    @SerialName("category")
    val category: String? = null,
    @SerialName("description")
    val description: String? = null,
    @SerialName("dimensions")
    val dimensions: DimensionsModel? = null,
    @SerialName("discountPercentage")
    val discountPercentage: Double? = null,
    @SerialName("id")
    val id: Int? = null,
    @SerialName("images")
    val images: List<String>? = null,
    @SerialName("meta")
    val meta: MetaModel? = null,
    @SerialName("minimumOrderQuantity")
    val minimumOrderQuantity: Int? = null,
    @SerialName("price")
    val price: Double? = null,
    @SerialName("rating")
    val rating: Double? = null,
    @SerialName("returnPolicy")
    val returnPolicy: String? = null,
    @SerialName("reviews")
    val reviews: List<ReviewModel>? = null,
    @SerialName("shippingInformation")
    val shippingInformation: String? = null,
    @SerialName("sku")
    val sku: String? = null,
    @SerialName("stock")
    val stock: Int? = null,
    @SerialName("tags")
    val tags: List<String>? = null,
    @SerialName("thumbnail")
    val thumbnail: String? = null,
    @SerialName("title")
    val title: String? = null,
    @SerialName("warrantyInformation")
    val warrantyInformation: String? = null,
    @SerialName("weight")
    val weight: Int? = null
)

Now for the product response model

shared/commonMain/product/domain/models/ProductResponse.kt

import kotlinx.serialization.Serializable

@Serializable
data class ProductResponse(
    @SerialName("limit")
    val limit: Int? = null,
    @SerialName("products")
    val products: List<ProductModel>? = null,
    @SerialName("skip")
    val skip: Int? = null,
    @SerialName("total")
    val total: Int? = null
)

PS. Notice that I'm creating the models in the domain layer. In the clean architecture standard, they suggest creating the API / database models in the data layer and then mapping them to the domain layer models.
Well ... most companies use a clean API designed to suit the UI needs, and this mapping processing makes things more complicated.

From a real-life scenario with the suggested clean architecture:

They changed the API response because they want to add an extra field in the UI.
We need to update the models in the data layer.
Then we need to update the models in the domain layer.
Then, we need to update the models' mapping process between them
Finally, update the UI.

Removing the data layer models will save us at least two steps; I believe it is an improvement for a well-designed API.

Products repository

shared/commonMain/product/domain/ProductRepository.kt

interface ProductRepository {

    suspend fun getProductsList() : List<ProductModel>
    suspend fun getProductsItem(id: Int) : ProductModel

}

Data layer, Products DataSource

It is time to start with the data layer.

shared/commonMain/product/data/ProductDataSource.kt

import io.ktor.client.HttpClient
import io.ktor.client.request.get
import io.ktor.client.request.parameter
import io.ktor.client.statement.HttpResponse

class ProductDataSource(
    private val httpClient: HttpClient
) {
    suspend fun productList(
        limit: Int = 10,
        skip: Int = 0,
        sortBy: String = "title",
        order: String = "asc",
    ): HttpResponse {
        return httpClient.get(
            urlString = "$BASE_URL/products/"
        ) {
            parameter("limit", limit)
            parameter("skip", skip)
            parameter("sortBy", sortBy)
            parameter("order", order)
        }
    }

    suspend fun productGet(
        id: Int,
    ): HttpResponse {
        return httpClient.get(
            urlString = "$BASE_URL/products/$id"
        )
    }
}

It is time to implement the products repository in the data layer

shared/commonMain/product/data/ProductRepositoryImpl.kt

class ProductRepositoryImpl(
    private val dataSource: ProductDataSource
) : ProductRepository {

    override suspend fun getProductsList(): List<ProductModel> {
        TODO("Not yet implemented")
    }

    override suspend fun getProductsItem(id: Int): ProductModel {
        TODO("Not yet implemented")
    }

}

We need a way to map the HttpResponse to the desired response. And how to inform the UI of any possible errors? I found a great solution from Philipp Lackner videos and tweaked it a little here

Let's create a helper model to allow that. I'll call it DataState

shared/commonMain/core/domain/DataState.kt

// the basic class
sealed interface DataState<out D, out E: DataError> {
    data class Success<out D>(val data: D): DataState<D, Nothing>
    data class Error<out E: DataError>(val error: E, val message: String? = null):
        DataState<Nothing, E>
}

// class extension to map response
inline fun <T, E: DataError, R> DataState<T, E>.map(map: (T) -> R): DataState<R, E> {
    return when(this) {
        is DataState.Error -> DataState.Error(error = error, message = message)
        is DataState.Success -> DataState.Success(map(data))
    }
}

// another extension for empty response
fun <T, E: DataError> DataState<T, E>.asEmptyDataResult(): EmptyResult<E> {
    return map {  }
}

// an extension to map success state
inline fun <T, E: DataError> DataState<T, E>.onSuccess(action: (T) -> Unit): DataState<T, E> {
    return when(this) {
        is DataState.Error -> this
        is DataState.Success -> {
            action(data)
            this
        }
    }
}

// an extension to map error state
inline fun <T, E: DataError> DataState<T, E>.onError(action: (E, String?) -> Unit): DataState<T, E> {
    return when(this) {
        is DataState.Error -> {
            action(error, message)
            this
        }
        is DataState.Success -> this
    }
}

typealias EmptyResult<E> = DataState<Unit, E>

shared/commonMain/core/domain/DataError.kt

sealed interface DataError {
    enum class Remote: DataError {
        REQUEST_TIMEOUT,
        TOO_MANY_REQUESTS,
        NO_INTERNET,
        SERVER,
        SERIALIZATION,
        UNKNOWN
    }

}

Let's create a wrapper function to make network calls safer to handle

shared/commonMain/core/data/HttpClientExt.kt

import io.ktor.client.call.NoTransformationFoundException
import io.ktor.client.call.body
import io.ktor.client.network.sockets.SocketTimeoutException
import io.ktor.client.statement.HttpResponse
import io.ktor.client.statement.bodyAsText
import io.ktor.util.network.UnresolvedAddressException
import kotlinx.coroutines.ensureActive
import kotlin.coroutines.coroutineContext
import kotlinx.serialization.json.Json
import kotlinx.serialization.json.contentOrNull
import kotlinx.serialization.json.jsonObject
import kotlinx.serialization.json.jsonPrimitive


suspend inline fun <reified T> safeCall(
    execute: () -> HttpResponse
): DataState<T, DataError.Remote> {
    val response = try {
        execute()
    } catch(e: SocketTimeoutException) {
        return DataState.Error(DataError.Remote.REQUEST_TIMEOUT, e.message)
    } catch(e: UnresolvedAddressException) {
        return DataState.Error(DataError.Remote.NO_INTERNET, e.message)
    } catch (e: Exception) {
        coroutineContext.ensureActive()
        return DataState.Error(DataError.Remote.UNKNOWN, e.message)
    }

    return responseToResult(response)
}

suspend inline fun <reified T> responseToResult(
    response: HttpResponse
): DataState<T, DataError.Remote> {
    return when(response.status.value) {
        in 200..299 -> {
            try {
                DataState.Success(response.body<T>())
            } catch(e: NoTransformationFoundException) {
                DataState.Error(DataError.Remote.SERIALIZATION)
            }
        }
        400 -> DataState.Error(DataError.Remote.SERVER, response.extractErrorMessage())
        401 -> DataState.Error(DataError.Remote.SERVER, response.extractErrorMessage())
        408 -> DataState.Error(DataError.Remote.REQUEST_TIMEOUT, response.extractErrorMessage())
        429 -> DataState.Error(DataError.Remote.TOO_MANY_REQUESTS, response.extractErrorMessage())
        in 500..599 -> DataState.Error(DataError.Remote.SERVER, response.extractErrorMessage())
        else -> DataState.Error(DataError.Remote.UNKNOWN, response.extractErrorMessage())
    }
}


// this function gets the error message from the error response based on the response schema
// a dummyjson error response contains one field `details` which contains the error message
// update this function to match your api error response
suspend fun HttpResponse.extractErrorMessage(): String? {
    return runCatching {
        val rawBody = bodyAsText()
        Json.parseToJsonElement(rawBody)
            .jsonObject["details"]
            ?.jsonPrimitive
            ?.contentOrNull
            ?.takeIf { it.isNotBlank() }
    }.getOrNull()
}

With our new helper model, we must update the repository and the repository implementation

shared/commonMain/product/domain/ProductRepository.kt

interface ProductRepository {

    suspend fun getProductsList() : DataState<List<ProductModel>, DataError.Remote>
    suspend fun getProductsItem(id: Int) : DataState<ProductModel, DataError.Remote>
}

and the implementation should look like

shared/commonMain/product/data/ProductRepositoryImpl.kt

class ProductRepositoryImpl(
    private val dataSource: ProductDataSource
) : ProductRepository {
    override suspend fun getProductsList(): DataState<List<ProductModel>, DataError.Remote> =
        safeCall<ProductResponse> {
            dataSource.productList()
        }.map { it.products ?: emptyList() }

    override suspend fun getProductsItem(id: Int): DataState<ProductModel, DataError.Remote> =
        safeCall<ProductModel> {
            dataSource.productGet(id=id)
        }
}

We used the map extension function in the getProductsList to return the list directly. We can pass the limit, skip, sortBy, order parameters if needed, but we are not passing them to simplify this tutorial.

Presentation layer, Bloc ViewModel

I'm a fan of Bloc library in Flutter, so I'll try to build a similar logic with the View-Model. Best practices suggest one state per screen

There is only one action for this screen: getting data.
You might have a filter action, a search action, and a pagination action for the actual app.

shared/commonMain/product/ui/ProductActions.kt

sealed interface ProductAction {

    class GetProductsList: ProductAction
    data class GetProductsItem(val id: Int): ProductAction
    data class GetProductsPage(val limit: Int, val skip: Int): ProductAction

}

shared/commonMain/product/ui/ProductState.kt

data class ProductState (
    val productsList: List<ProductModel> = emptyList(),
    val isLoading: Boolean = false,
    val errorMessage: String? = null
)

shared/commonMain/product/ui/ProductViewModel.kt

class ProductViewModel(
    private val repository: ProductRepository
) : ViewModel() {

    private var productsJob: Job? = null

    private val _state = MutableStateFlow(
        ProductState(
            productsList = emptyList(),
            isLoading = false,
            errorMessage = null
        )
    )

    @NativeCoroutinesState
    val state: StateFlow<ProductState> = _state
        .stateIn(
            viewModelScope,
            SharingStarted.WhileSubscribed(5000L),
            _state.value
        )


    fun onAction(action: ProductAction) {
        when (action) {
            is ProductAction.GetProductsList -> {
                productsJob?.cancel()
                productsJob = getProductsList()
            }

            is ProductAction.GetProductsItem -> {
                TODO("Not yet implemented")
            }

            is ProductAction.GetProductsPage -> {
                TODO("Not yet implemented")
            }

        }

    }


    private fun getProductsList() = viewModelScope.launch {
        _state.update {
            it.copy(
                isLoading = true
            )
        }

        repository.getProductsList()
            .onSuccess { response ->
                _state.update {
                    it.copy(
                        isLoading = false,
                        errorMessage = null,
                        productsList = response
                    )
                }
            }
            .onError { error, message ->
                _state.update {
                    it.copy(
                        isLoading = false,
                        productsList = emptyList(),
                        errorMessage = message ?: error.toString()
                    )
                }
            }
    }
}

Dependency Injection for Products repository

We should provide the required dependencies for HttpClientFactory, ProductDataSource, and ProductRepositoryImpl

shared/commonMain/di/KoinModules.kt

val sharedModule = module {
    single { HttpClientFactory.create(get()) }
    singleOf(::ProductDataSource)
    singleOf(::ProductRepositoryImpl).bind<ProductRepository>()

    viewModelOf(::ProductViewModel)
    // ...
}

expect val platformModule: Module

We have two options for view models injection, either as a singleton or as a view model. View model injection keeps the model alive with the view context. The view dies, the model dies along with it, but singleton DI keeps it alive the whole time.
We will use viewModelOf, since it is cleaner, but you can use either.

For iOS DI to work, we need to use the iOS helper class

shared/iosMain/di/KoinHelper.kt

class KoinHelper : KoinComponent {
    fun productsViewModel() = get<ProductViewModel>()
    // ...
}

Finally ... it is time for the UI

Products list in Android (Finally)

I'll be short on this; The native code is part of the UI (presentation) layer. It will reflect the same project structure, a folder for every app module (Product). It will include the ProductScreen and its components.

Make sure to implement the Koin view model in the Android module before using it in the screen

composeApp/build.gradle.kts

kotlin {
    ...
    sourceSets {
        ...
        commonMain.dependencies {
            ...
            implementation(libs.koin.compose)
            implementation(libs.koin.compose.viewmodel)
        }
    }
}

Now, for the screen design... I promis to improve it in later tutorials, so accept this basic design for now.

composeApp/kotlin/product/ProductScreen.kt

import org.koin.compose.viewmodel.koinViewModel

@Composable
fun ProductScreen(
    modifier: Modifier = Modifier,
    viewModel: ProductViewModel = koinViewModel()
) {
    val state by viewModel.state.collectAsState()

    LaunchedEffect(Unit) {
        viewModel.onAction(ProductAction.GetProductsList())
    }

    LazyColumn(
        modifier = modifier
            .fillMaxSize()
    ) {
        items(state.productsList.size) { index ->
            val product = state.productsList[index]
            ProductItem(product = product)
        }
    }
}

@Composable
fun ProductItem(product: ProductModel, modifier: Modifier = Modifier) {

    val imageUrl = product.thumbnail ?: product.images?.firstOrNull { it.isNotBlank() }

    Row(
        modifier = modifier
            .padding(vertical = 5.dp, horizontal = 5.dp)
    ) {
        Image(
            modifier = Modifier.padding(end = 5.dp).width(80.dp),
            painter = painterResource(id = R.drawable.ic_launcher_background),
            contentDescription = product.title,
        )

        Column {
            Text(text = product.title ?: "")
            Text(text = product.description ?: "")
        }
    }

}

We are using LaunchedEffect to issue a "get products list" action. We can do it in the init function of the view model too

shared/commonMain/product/ui/ProductViewModel.kt

class ProductViewModel(
    private val repository: ProductRepository
) : ViewModel() {

    private var productsJob: Job? = null

    private val _state = MutableStateFlow(
        ProductState(
            productsList = emptyList(),
            isLoading = false,
            errorMessage = null
        )
    )

    init {
        onAction(ProductAction.GetProductsList()) // new
    }
    //...
}

Then we won't need the LaunchedEffect, but I prefer it with LaunchedEffect

To show the screen ...

composeApp/kotlin/MainActivity.kt

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        initKoin()
        enableEdgeToEdge()
        super.onCreate(savedInstanceState)

        setContent {
            ProductScreen()
        }
    }
}

Products list in iOS (Finally * 2)

We start by creating ProductViewModel wrapper for iOS

iosApp/product/ProductViewModelWrapper.swift

import Foundation
import Shared
import KMPNativeCoroutinesCombine
import Combine

final class ProductViewModelWrapper: ObservableObject {
    @Published var lastUpdated = Date()

    let viewModel: ProductViewModel = KoinHelper().productsViewModel()
    private var cancellables = Set<AnyCancellable>()

    init() {
        createPublisher(for: viewModel.stateFlow)
        .receive(on: DispatchQueue.main)
        .sink { _ in } receiveValue: { [weak self] _ in
            self?.lastUpdated = Date()
        }
        .store(in: &cancellables)
    }
}

and the list screen

iosApp/product/ProductScreen.swift

import SwiftUI
import Shared

struct ProductScreen: View {
    @StateObject private var wrapper = ProductViewModelWrapper()
    @State private var showErrorAlert = false
    @State private var errorAlertText = ""
    @State private var lastErrorMessage: String?

    var body: some View {
        let state = wrapper.viewModel.state

        ZStack {
            List {
                ForEach(Array(state.productsList.enumerated()), id: \.offset) { _, product in
                    ProductItemView(product: product)
                }
            }
            .listStyle(.plain)

            if state.isLoading {
                Color.black.opacity(0.5)
                    .ignoresSafeArea()
                ProgressView()
                    .scaleEffect(1.4)
                    .tint(.white)
            }
        }
        .onAppear {
            wrapper.viewModel.onAction(action: ProductActionGetProductsList())
        }
        .onChange(of: wrapper.lastUpdated) { _, _ in
            let current = wrapper.viewModel.state
            if let message = current.errorMessage,
               !message.isEmpty,
               message != lastErrorMessage {
                lastErrorMessage = message
                errorAlertText = message
                showErrorAlert = true
            }
        }
        .alert("Error", isPresented: $showErrorAlert) {
            Button("OK", role: .cancel) {}
        } message: {
            Text(errorAlertText)
        }
    }
}

private struct ProductItemView: View {
    let product: ProductModel

    var body: some View {
        HStack(alignment: .top, spacing: 8) {
            AsyncImage(url: URL(string: product.thumbnail ?? product.images?.first ?? "")) { phase in
                switch phase {
                case .success(let image):
                    image
                        .resizable()
                        .scaledToFill()
                case .failure(_), .empty:
                    Image(systemName: "photo")
                        .resizable()
                        .scaledToFit()
                        .padding(16)
                        .foregroundStyle(.secondary)
                @unknown default:
                    EmptyView()
                }
            }
            .frame(width: 80, height: 80)
            .background(Color.gray.opacity(0.15))
            .clipShape(RoundedRectangle(cornerRadius: 8))

            VStack(alignment: .leading, spacing: 4) {
                Text(product.title ?? "")
                    .font(.headline)
                    .lineLimit(1)
                Text(product.description_ ?? "")
                    .font(.subheadline)
                    .foregroundStyle(.secondary)
                    .lineLimit(2)
            }
        }
        .padding(.vertical, 4)
    }
}

and to show it

iosApp/iOSApp.swift

@main
struct iOSApp: App {
    init() {
        KoinInitIosKt.doInitKoinIos()
    }
    var body: some Scene {
        WindowGroup {
            ProductScreen()
        }
    }
}

Thanks for reading this very very long article

No such module 'Shared' fixed for KMP Xcode

Saad Alkentar — Tue, 24 Mar 2026 19:09:12 +0000

I believe you have already tried to open Kotlin multi-platform iOS project in Xcode, and voalla, No such module 'Shared'

Let's jump directly to the solution. You can also find the solution here

Start by choosing to edit schemas in Xcode

Then add the script as a pre-build action

cd "$SRCROOT/.."
./gradlew :shared:embedAndSignAppleFrameworkForXcode

and make sure to select to provide the build settings from iosApp

Time to try to build again, success? Good for you, same error? move on ...
Let's debug the script to find the issue

echo "Hello world"
cd "$SRCROOT/.."
./gradlew :shared:embedAndSignAppleFrameworkForXcode

The operation couldn’t be completed. Unable to locate a Java Runtime.
Please visit http://www.java.com for information on installing Java.

So, couldn't find the Java runtime...

I need to set JAVA_HOME. We can do it on the system level, the script level, or on the project level. I'll choose the third.
Select your project, project properties, click the add button, and add a user-defined setting.

and add the JAVA_HOME env var

For my device, the path is

export JAVA_HOME="/Applications/Android Studio.app/Contents/jbr/Contents/Home"

It should build successfully now

Stay tuned for Networking with KMP

KMP Native UI view model injection for iOS and Android

Saad Alkentar — Mon, 23 Mar 2026 13:06:18 +0000

Cross-platform development significantly reduces overhead for both developers and organizations. While React Native leveraged web expertise and Flutter introduced a unified UI for multi-platform delivery, Kotlin Multiplatform (KMP) represents the next evolution. KMP offers the flexibility of Compose for shared UI, while uniquely allowing developers to implement native interfaces where maximum performance and stability are required—all while maintaining a single shared logic base in Kotlin.

Finding comprehensive resources for Kotlin Multiplatform (KMP) using Native UI can be challenging, so this series aims to bridge that gap.

We will build a production-ready foundation using a modular Clean Architecture—the industry standard for scalable apps. Our roadmap covers the essential pillars of modern development:

Dependency Injection (Koin),
Networking (Ktor),
and Architecture (Clean Architecture).

In this article, we will test the dependency injection setup by injecting a view model for iOS and Android. Be sure to follow the previous article for setting up Koin di.

View model library

let's start by updating the shared module shared/build.gradle.kts

...
kotlin {
    ...
    sourceSets {
        commonMain.dependencies {
            ...
            implementation(libs.androidx.lifecycle.viewmodelCompose)

        }
        ...
    }
}

It should already be in the toml file, if not, you can add it

[versions]
androidx-lifecycle = "2.9.6"

[libraries]
androidx-lifecycle-viewmodelCompose = { module = "org.jetbrains.androidx.lifecycle:lifecycle-viewmodel-compose", version.ref = "androidx-lifecycle" }

Let's create a simple view model to make sure DI works as expected

A simple shared ViewModel

In the shared module, we create a view model.

// shared/kotlin/home/HomeViewModel.kt

import androidx.lifecycle.ViewModel
import kotlinx.coroutines.flow.MutableStateFlow
import kotlinx.coroutines.flow.StateFlow
import kotlinx.coroutines.flow.asStateFlow

class HomeViewModel : ViewModel() {
    private val _state = MutableStateFlow("initial state")

    val state: StateFlow<String> = _state.asStateFlow()

    fun updateString(newString: String) {
        _state.value = newString
    }
}

Inject our ViewModel where needed

We need to provide our view model in the shared Koin module in order to use it in other platforms

shared/commonMain/di/KoinModules.kt

import org.koin.core.module.dsl.singleOf
import org.koin.core.module.dsl.viewModelOf
import org.koin.core.module.Module

val sharedModule = module {
    //...
    singleOf(::HomeViewModel)
}

We have multiple injection options, either as a singleton singleOf or as a view model viewModelOf. Singletons will never die (until you close the app), view models are attached to a single screen context and will die with it. I'll use viewModelOf in the coming tutorials, so I'll keep it as a singleton here.

View models usage in Android

We will update the App.kt to test our new view model.

// composeApp/kotlin/App.kt

...
import androidx.lifecycle.compose.collectAsStateWithLifecycle
import androidx.lifecycle.viewmodel.compose.viewModel
import com.irsc.kotlinnativedemo.home.presentation.HomeViewModel
import org.koin.java.KoinJavaComponent.inject

@Composable
@Preview
fun App() {
    val viewModel: HomeViewModel by inject(HomeViewModel::class.java)
    val state by viewModel.state.collectAsStateWithLifecycle()

    MaterialTheme {
        var showContent by remember { mutableStateOf(false) }
        Column(
            modifier = Modifier
                .background(MaterialTheme.colorScheme.primaryContainer)
                .safeContentPadding()
                .fillMaxSize(),
            horizontalAlignment = Alignment.CenterHorizontally,
        ) {
            Button(onClick = {
                showContent = !showContent
                viewModel.updateString("new string")
            }) {
                Text("Click me!")
            }
            Text(state)
            ...
        }
    }
}

PS. If you are injecting the ViewModel as a view model, make sure to use koinViewModel instead of inject; you may need to install the koinViewModel library for the Android platform.

import org.koin.compose.viewmodel.koinViewModel
...
    val viewModel: AccountViewModel = koinViewModel()

Clicking the button should update the state, and the state flow should update the text under the button. Now we are sure the DI works in Android, the easy one, next is the iOS...

View models usage in iOS

Using view models in iOS is more challenging; the Observable class is actually the iOS ViewModel, but it is kinda tricky mapping them, according to this we have two options

KMP-NativeCoroutines: the recommended one for now
SKIE: I think it is better, but it does not support Kotlin 2.3.20; this may have changed by the time you read this article. I should create another article for it by the time.

KMP-NativeCoroutines libraries setup

We start by adding the plugins to the toml file

[versions]
ksp = "2.3.6"
nativecoroutines = "1.0.2"

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }
devtools-ksp = { id = "com.google.devtools.ksp", version.ref = "ksp" }
kmp-nativecoroutines = { id = "com.rickclephas.kmp.nativecoroutines", version.ref = "nativecoroutines" }

make sure to sync after every toml file update to help the IDE

Next, we update the root project build.gradle.kts

// build.gradle.kts
plugins {
    // this is necessary to avoid the plugins to be loaded multiple times
    // in each subproject's classloader
    ...

    alias(libs.plugins.devtools.ksp) apply false
    alias(libs.plugins.kmp.nativecoroutines) apply false

}

Then, we update the shared module build.gradle.kts

// shared/build.gradle.kts

import org.jetbrains.kotlin.gradle.dsl.JvmTarget

plugins {
    alias(libs.plugins.kotlinMultiplatform)
    alias(libs.plugins.androidLibrary)

    alias(libs.plugins.koin.compiler)
    alias(libs.plugins.devtools.ksp) // new
    alias(libs.plugins.kmp.nativecoroutines) // new
}
...

and finally, the shared module sourceSets

// shared/build.gradle.kts
kotlin {
    // ...
    sourceSets{
        all {
            languageSettings {
                optIn("kotlin.experimental.ExperimentalObjCName")
                optIn("kotlin.time.ExperimentalTime")
            }
        }
        // ...
    }
}

Nice, this should work, let's build the project ...

> Task :shared:compileKotlinIosSimulatorArm64 FAILED
error: org.jetbrains.kotlin.cli.jvm.plugins.PluginCliParser$PluginProcessingError: Plugin com.rickclephas.kmp.nativecoroutines.compiler.KmpNativeCoroutinesCompilerPluginRegistrar is incompatible with the current version of the compiler.
error: org.jetbrains.kotlin.cli.jvm.plugins.PluginCliParser$PluginProcessingError: Plugin com.rickclephas.kmp.nativecoroutines.compiler.KmpNativeCoroutinesCompilerPluginRegistrar is incompatible with the current version of the compiler.

org.jetbrains.kotlin.cli.jvm.plugins.PluginCliParser$PluginProcessingError: Plugin com.rickclephas.kmp.nativecoroutines.compiler.KmpNativeCoroutinesCompilerPluginRegistrar is incompatible with the current version of the compiler.

Caused by: java.lang.AbstractMethodError: Missing implementation of resolved method 'abstract java.lang.String getPluginId()' of abstract class org.jetbrains.kotlin.compiler.plugin.CompilerPluginRegistrar.
Caused by: java.lang.AbstractMethodError: Missing implementation of resolved method 'abstract java.lang.String getPluginId()' of abstract class org.jetbrains.kotlin.compiler.plugin.CompilerPluginRegistrar.

Those errors confused me a lot. Finding error causes in 3 platforms is kinda ugly. In short, the problem is in our stars, the Kotlin version. let's update it.

[versions]
...
kotlin = "2.3.20"
...

Syncing and building again should resolve the error.

KMP-NativeCoroutines shared code update

We should inform the NativeCoroutines of our public state flow, there are multiple options like @NativeCoroutines and @NativeCoroutinesState. Personally, I suggest to always use NativeCoroutinesState. Let's update our view model class

// shared/kotlin/home/HomeViewController.kt

import com.rickclephas.kmp.nativecoroutines.NativeCoroutinesState

class HomeViewModel : ViewModel() {
    private val _state = MutableStateFlow("initial state")

    @NativeCoroutinesState // new
    val state: StateFlow<String> = _state.asStateFlow()

    fun updateString(newString: String) {
        _state.value = newString
    }
}

Great, we need to update the iOS native project next ...

KMP-NativeCoroutines iOS project update

We need to open the iOS project in Xcode, choose to add a package dependency

look for

https://github.com/rickclephas/KMP-NativeCoroutines.git

and install KMPNativeCoroutinesAsync, KMPNativeCoroutinesCombine, and KMPNativeCoroutinesCore and finally click add packages

Nice, now we can use KMP-NativeCoroutines in iOS, let's go back to Android Studio.
PS. I know you tried to build it in Xcode and faced No such module 'Shared', we will solve this in another article

The ViewModel in Swift UI

I wanted to map ViewModel directly to @Observable Swift class, but it is still work in progress, for now we will wrap it with ObservableObject. Before that, we need to create a DI helper class

// shared/src/iosMain/kotlin/di/KoinHelper.kt

import com.irsc.kotlinnativedemo.home.presentation.HomeViewModel
import org.koin.core.component.KoinComponent
import org.koin.core.component.get


class KoinHelper : KoinComponent {
    fun homeViewModel(): HomeViewModel = get()
}

Time to create our own ObservableObject

import Foundation
import Shared
import KMPNativeCoroutinesCombine
import Combine

class HomeViewModelWrapper : ObservableObject {
    @Published var lastUpdated = Date()

    let viewModel: HomeViewModel = KoinHelper().homeViewModel()
    private var cancellables = Set<AnyCancellable>()

    init() {
        // Observe the flow, but we don't need to manually copy every field to Swift anymore
        createPublisher(for: viewModel.stateFlow)
        .receive(on: DispatchQueue.main)
        .sink { _ in } receiveValue: { [weak self] _ in
            // Just trigger a refresh; the View will read from viewModel.state directly
            self?.lastUpdated = Date()
        }
        .store(in: &cancellables)
    }

}

Let's point out a few points here

The lastUpdated field is used to trigger UI reload only.
We read data and called methods directly from the viewModel.
The state field in the view-model is reflected as stateFlow in Swift, because we are using @NativeCoroutinesState; it would be different if we used @NativeCoroutines.
This ObservableObject class blueprint should work for any type of view model
I still think an @observable class would be better, but I couldn't find the best way to deploy it yet.

Finally, let's test it in the ContentView

import SwiftUI
import Shared

struct ContentView: View {
    @State private var showContent = false
    @StateObject private var wrapper = HomeViewModelWrapper()

    var body: some View {
        VStack {
            Button("Click me!") {
                withAnimation {
                    showContent = !showContent
                    wrapper.viewModel.updateString(newString:"new string")
                }
            }
            Text(wrapper.viewModel.state)

            if showContent {
                VStack(spacing: 16) {
                    Image(systemName: "swift")
                        .font(.system(size: 200))
                        .foregroundColor(.accentColor)
                    Text("SwiftUI: \(Greeting().greet())")
                }
                .transition(.move(edge: .top).combined(with: .opacity))
            }
        }
        .frame(maxWidth: .infinity, maxHeight: .infinity, alignment: .top)
        .padding()
    }
}

That is it, it wasn't too simple for iOS, I know, yet fun and reusable, I hope

We are fixing No such module 'Shared' for Xcode project next time, so
Stay tuned

KMP Native UI Dependency Injection with Koin

Saad Alkentar — Sun, 22 Mar 2026 10:44:15 +0000

Finding comprehensive resources for Kotlin Multiplatform (KMP) using Native UI can be challenging, so this series aims to bridge that gap.

We will build a production-ready foundation using a modular Clean Architecture—the industry standard for scalable apps. Our roadmap covers the essential pillars of modern development:

Dependency Injection (Koin),
Networking (Ktor),
and Architecture (Clean Architecture).

In this first installment, we’ll kick things off by implementing Dependency Injection with Koin.

Creating a new Project

The recommended IDEs are IntelliJ IDEA and Android Studio. I'll use Android Studio

Install the KMP plugin: in the sidebar of Android Studio, select plugins
Look for "Kotlin Multiplatform" and install it
It is time to create a new Project
Complete the wizard process by choosing the project name, and do not share the UI

That is it, simple and easy

Koin Implementation Guide for Native UI

We start with:

Koin Build libs

Basically, it is this article from Koin documentation, in short:

in gradle/libs.versions.toml:

[versions]
koin = "4.2.0"
koin-plugin = "0.4.1"

[libraries]
koin-core = { module = "io.insert-koin:koin-core", version.ref = "koin" }
koin-annotations = { module = "io.insert-koin:koin-annotations", version.ref = "koin" }
koin-compose = { module = "io.insert-koin:koin-compose", version.ref = "koin" }
koin-compose-viewmodel = { module = "io.insert-koin:koin-compose-viewmodel", version.ref = "koin" }
koin-ktor = { module = "io.insert-koin:koin-ktor", version.ref = "koin" }
koin-test = { module = "io.insert-koin:koin-test", version.ref = "koin" }

[plugins]
koin-compiler = { id = "io.insert-koin.compiler.plugin", version.ref = "koin-plugin" }

In the shared module's shared/build.gradle.kts:

plugins {
    alias(libs.plugins.koin.compiler)
}

kotlin {
    ...

    sourceSets {
        commonMain.dependencies {
            implementation(libs.koin.core)
            implementation(libs.koin.annotations)
            implementation(libs.koin.compose.viewmodel)
            implementation(libs.koin.ktor) // for Ktor web client DI
        }


        commonTest.dependencies {
            implementation(libs.koin.test)
        }
    }

}

In the Android module's composeApp/build.gradle.kts

kotlin {
    ...

    sourceSets {
        ...
        commonMain.dependencies {
            ...
            implementation(libs.koin.compose) // contains android
            implementation(libs.koin.compose.viewmodel)
        }
        ...
    }
}

Compose contains the Android Koin dependency; it can be used as a common or Android dependency.

Koin Project setup

After installing all libraries, it is time to set up the code. You can follow this also to set it up

create KoinModules in the shared module

// shared/commonMain/kotlin/di/KoinModules.kt
import org.koin.core.module.Module
import org.koin.dsl.module

val sharedModule = module {

}

expect val platformModule: Module

create the platform modules, Android

// shared/androidMain/kotlin/di/PlatformModule.android.kt
import org.koin.dsl.module

actual val platformModule = module {

}

iOS:

// shared/iosMain/kotlin/di/PlatformModule.ios.kt
import org.koin.dsl.module

actual val platformModule = module {

}

Koin initialization: we start with the shared module

// shared/commonMain/kotlin/di/KoinInit.kt
import org.koin.core.context.startKoin
import org.koin.core.KoinApplication
import org.koin.dsl.KoinAppDeclaration
import org.koin.dsl.includes

fun initKoin(config: KoinAppDeclaration? = null): KoinApplication {
    return startKoin {
        includes(config)
        modules(
            sharedModule,
            platformModule
        )
    }
}

Now, with the Android module, the simplest way is to add initKoin() in the MainActivity

// composeApp/kotlin/MainActivity.kt
...
import com.irsc.kotlinnativedemo.di.initKoin

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        initKoin()
        ...
    }
}

But for the iOS module, we will follow the instructions this time. Let's start by creating KoinInitIos in the shared module.

// shared/src/iosMain/kotlin/di/KoinInitIos.kt
fun initKoinIos() {
    initKoin()
}

Now to call it in the iOS native code

import SwiftUI
import Shared

@main
struct iOSApp: App {

    init() {
        KoinInitIosKt.doInitKoinIos()
    }

    var body: some Scene {
        WindowGroup {
            ContentView()
        }
    }
}

Please notice that we are importing Shared (capital S), the Kotlin file KoinInitIos.kt is used with Kt postfix, and the function is used with do prefix

I have submitted a fix for the documentation code; hopefully, it will be fixed by the time you read this article

That is it, we have added Koin to our project successfully. The next step is to test it with view model injection

Stay tuned for the next article

Your Own Email Verification SaaS Server

Saad Alkentar — Mon, 18 Aug 2025 09:34:46 +0000

With an estimated six billion email addresses in the world, it's a huge challenge to know which ones on your contact list are valid. Many are temporary, fraudulent, or simply abandoned. Email verification is a technology designed to solve this by identifying good and bad email addresses without sending an email. It uses a variety of techniques, from simple syntax checks to more complex methods, to assess the validity of an email.

This is critical for many applications:

Marketing: Increases deliverability and ROI by ensuring your campaigns reach real people.
CRM: Keeps your customer data accurate, leading to better support and engagement.
Fraud Prevention: Helps prevent fake sign-ups and transactions on e-commerce sites.
Data Hygiene: Maintains a high-quality database for more reliable analytics.

Ultimately, email verification protects your reputation, saves you money, and ensures your communication efforts are not wasted.

The Idea

Well, to make sure an email exists, we should check

Check whether the given email address conforms to the general format requirements of valid email addresses.
Check whether the domain part of the given email address (the part behind the "@") is known as a disposable and temporary email address domain. These are often used to register dummy users in order to spam or abuse some services.
Check whether there is a valid list of servers responsible for delivering emails to the given email address.
Check whether the given email address exists by simulating an actual email delivery.

How to do that? Well... luckily, I found a Python library that does that exactly!
It is called py3-validate-email, it covers the 4 points altogether, the only weakness is NOT working with shared hosting servers, so be sure to host your project in a VPS or a dedicated server.

Django project setup

Let's start by creating the Django project and the apps for accounts, admin, and main functionality app

# install Django lib and extensions
pip install Django
pip install django-filter
pip install djangorestframework
pip install djangorestframework_simplejwt
pip install pillow

pip install py3-validate-email

# create the project
django-admin startproject saas
cd saas
python manage.py startapp app_account
python manage.py startapp app_admin
python manage.py startapp app_main

Email verification API

To simplify this step, let's skip using serializers and pass the IP as a GET parameter, in the views file

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.exceptions import APIException
from common.utils import *

from validate_email import validate_email

class EmailValidationView(APIView):
    permission_classes = ( )
    renderer_classes = [CustomRenderer, BrowsableAPIRenderer]

    def is_valid_email(self, email):
        is_valid = validate_email(email)
        return is_valid

    def get(self, request, *args, **kwargs):
        email = request.query_params.get('email', None)
        if not email:
            raise APIException("The 'email' query parameter is required.")

        try:
            is_valid = self.is_valid_email(email)
            return Response(is_valid)
        except Exception as e:
            raise APIException(f"Information for email address '{email}' not found.")

app_main/views.py

We are getting the Email from GET parameters, then passing it to py3-validate-email, and responding with its direct response.
Let's assign a URL for the view

from django.urls import path, include
from .views import *

urlpatterns = [
    path('email/', EmailValidationView.as_view()),
]

app_main/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('app_main.urls')),
]

saas/urls.py

let's try it now

GET /api/email/?email=saad.zgm@gmail.com

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "status": "success",
    "code": 200,
    "data": true,
    "message": null
}

GET /api/email/?email=saad@gmail.com

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "status": "success",
    "code": 200,
    "data": false,
    "message": null
}

Bonus, error handling

Most issues come from smtp. Therefore, it can be useful to debug it using smtp_debug=True flag

validate_email("saad@gmail.com", smtp_debug=True)
19:42:10.715698 connect: to ('gmail-smtp-in.l.google.com', 25) None
19:42:10.890421 reply: b'220 mx.google.com ESMTP a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp\r\n'
19:42:10.890715 reply: retcode (220); Msg: b'mx.google.com ESMTP a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp'
19:42:10.890749 connect: b'mx.google.com ESMTP a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp'
19:42:10.890991 send: 'ehlo saads-MacBook-Pro.local\r\n'
19:42:10.955439 reply: b'250-mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\r\n'
19:42:10.955753 reply: b'250-SIZE 157286400\r\n'
19:42:10.955789 reply: b'250-8BITMIME\r\n'
19:42:10.956789 reply: b'250-STARTTLS\r\n'
19:42:10.956828 reply: b'250-ENHANCEDSTATUSCODES\r\n'
19:42:10.956860 reply: b'250-PIPELINING\r\n'
19:42:10.956884 reply: b'250-CHUNKING\r\n'
19:42:10.956908 reply: b'250 SMTPUTF8\r\n'
19:42:10.956957 reply: retcode (250); Msg: b'mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\nSIZE 157286400\n8BITMIME\nSTARTTLS\nENHANCEDSTATUSCODES\nPIPELINING\nCHUNKING\nSMTPUTF8'
19:42:10.958356 send: 'STARTTLS\r\n'
19:42:11.016002 reply: b'220 2.0.0 Ready to start TLS\r\n'
19:42:11.016104 reply: retcode (220); Msg: b'2.0.0 Ready to start TLS'
19:42:11.224310 send: 'ehlo saads-MacBook-Pro.local\r\n'
19:42:11.289252 reply: b'250-mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\r\n'
19:42:11.289533 reply: b'250-SIZE 157286400\r\n'
19:42:11.289568 reply: b'250-8BITMIME\r\n'
19:42:11.289595 reply: b'250-ENHANCEDSTATUSCODES\r\n'
19:42:11.289620 reply: b'250-PIPELINING\r\n'
19:42:11.289642 reply: b'250-CHUNKING\r\n'
19:42:11.289666 reply: b'250 SMTPUTF8\r\n'
19:42:11.289724 reply: retcode (250); Msg: b'mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\nSIZE 157286400\n8BITMIME\nENHANCEDSTATUSCODES\nPIPELINING\nCHUNKING\nSMTPUTF8'
19:42:11.290287 send: 'mail FROM:<saad@gmail.com>\r\n'
19:42:11.355813 reply: b'250 2.1.0 OK a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp\r\n'
19:42:11.356098 reply: retcode (250); Msg: b'2.1.0 OK a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp'
19:42:11.356577 send: 'rcpt TO:<saad@gmail.com>\r\n'
19:42:11.412227 reply: b'550-5.1.1 The email account that you tried to reach does not exist. Please try\r\n'
19:42:11.412510 reply: b"550-5.1.1 double-checking the recipient's email address for typos or\r\n"
19:42:11.412545 reply: b'550-5.1.1 unnecessary spaces. For more information, go to\r\n'
19:42:11.412575 reply: b'550 5.1.1  https://support.google.com/mail/?p=NoSuchUser a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp\r\n'
19:42:11.412633 reply: retcode (550); Msg: b"5.1.1 The email account that you tried to reach does not exist. Please try\n5.1.1 double-checking the recipient's email address for typos or\n5.1.1 unnecessary spaces. For more information, go to\n5.1.1  https://support.google.com/mail/?p=NoSuchUser a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp"
19:42:11.412835 send: 'quit\r\n'
19:42:11.463657 reply: b'221 2.0.0 closing connection a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp\r\n'
19:42:11.463919 reply: retcode (221); Msg: b'2.0.0 closing connection a640c23a62f3a-af921f507c1si1870667666b.448 - gsmtp'

validate_email("saad.zgm@gmail.com", smtp_debug=True)
19:43:07.253112 connect: to ('gmail-smtp-in.l.google.com', 25) None
19:43:07.340865 reply: b'220 mx.google.com ESMTP a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp\r\n'
19:43:07.341149 reply: retcode (220); Msg: b'mx.google.com ESMTP a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp'
19:43:07.341181 connect: b'mx.google.com ESMTP a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp'
19:43:07.341309 send: 'ehlo saads-MacBook-Pro.local\r\n'
19:43:07.392175 reply: b'250-mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\r\n'
19:43:07.392454 reply: b'250-SIZE 157286400\r\n'
19:43:07.392475 reply: b'250-8BITMIME\r\n'
19:43:07.392492 reply: b'250-STARTTLS\r\n'
19:43:07.392521 reply: b'250-ENHANCEDSTATUSCODES\r\n'
19:43:07.392536 reply: b'250-PIPELINING\r\n'
19:43:07.392549 reply: b'250-CHUNKING\r\n'
19:43:07.392562 reply: b'250 SMTPUTF8\r\n'
19:43:07.392590 reply: retcode (250); Msg: b'mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\nSIZE 157286400\n8BITMIME\nSTARTTLS\nENHANCEDSTATUSCODES\nPIPELINING\nCHUNKING\nSMTPUTF8'
19:43:07.392728 send: 'STARTTLS\r\n'
19:43:07.463363 reply: b'220 2.0.0 Ready to start TLS\r\n'
19:43:07.463626 reply: retcode (220); Msg: b'2.0.0 Ready to start TLS'
19:43:07.667088 send: 'ehlo saads-MacBook-Pro.local\r\n'
19:43:07.741871 reply: b'250-mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\r\n'
19:43:07.743250 reply: b'250-SIZE 157286400\r\n'
19:43:07.743800 reply: b'250-8BITMIME\r\n'
19:43:07.743848 reply: b'250-ENHANCEDSTATUSCODES\r\n'
19:43:07.743876 reply: b'250-PIPELINING\r\n'
19:43:07.743900 reply: b'250-CHUNKING\r\n'
19:43:07.743924 reply: b'250 SMTPUTF8\r\n'
19:43:07.743972 reply: retcode (250); Msg: b'mx.google.com at your service, [2a02:3035:b62:b597:7d95:8114:3e04:4156]\nSIZE 157286400\n8BITMIME\nENHANCEDSTATUSCODES\nPIPELINING\nCHUNKING\nSMTPUTF8'
19:43:07.744572 send: 'mail FROM:<saad.zgm@gmail.com>\r\n'
19:43:07.785285 reply: b'250 2.1.0 OK a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp\r\n'
19:43:07.785366 reply: retcode (250); Msg: b'2.1.0 OK a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp'
19:43:07.785530 send: 'rcpt TO:<saad.zgm@gmail.com>\r\n'
19:43:07.957576 reply: b'250 2.1.5 OK a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp\r\n'
19:43:07.957956 reply: retcode (250); Msg: b'2.1.5 OK a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp'
19:43:07.958220 send: 'quit\r\n'
19:43:08.011109 reply: b'221 2.0.0 closing connection a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp\r\n'
19:43:08.011380 reply: retcode (221); Msg: b'2.0.0 closing connection a640c23a62f3a-af91a295112si1970106166b.978 - gsmtp'

That is it for this tutorial. We still need to add the SaaS users/ tokens/ stats management, which we will discuss in another tutorial, so

Stay tuned 😎

Your Own GeoIP SaaS Server

Saad Alkentar — Tue, 12 Aug 2025 12:11:57 +0000

In modern web development, there's often a need to determine a user's geographical location without using the browser's Geolocation API, which requires explicit user permission. A common alternative is using GeoIP, which maps a user's IP address to a physical location.

While this is a powerful and reliable method, it's important to be aware of the costs. Many GeoIP service providers charge based on the number of API requests, and for high-traffic applications, these costs can escalate significantly.

Here's a breakdown of some popular GeoIP providers and their approximate monthly costs for a bundle of one million requests:

Provider	1 mil/month cost
https://www.ip2location.com	$27980
https://www.maxmind.com	$4664
https://ipinfo.io	$9324
https://ipgeolocation.io	$7488
https://db-ip.com	$2400
https://ipregistry.co	$1200
https://apiip.net	$312
https://ipdata.co	$1152

The Idea

In this tutorial, we're going to build our own GeoIP server. I'll walk you through setting up the core functionality of a GeoIP SaaS application using Django, the GeoIP2 library, and the DB-IP database. While this tutorial will focus on the main GeoIP feature, a separate tutorial will cover the basic setup of a SaaS server.
Let's dive in!

Django project setup

Let's start by creating the Django project and the apps for accounts, admin, and main functionality app

# install Django lib and extensions
pip install Django
pip install django-filter
pip install djangorestframework
pip install djangorestframework_simplejwt
pip install pillow

pip install geoip2

# create the project
django-admin startproject saas
cd saas
python manage.py startapp app_account
python manage.py startapp app_admin
python manage.py startapp app_main

The next step is to setup GeoIP2 library in the project settings

...
INSTALLED_APPS = [
    'django.contrib.admin',
    'django.contrib.auth',
    'django.contrib.contenttypes',
    'django.contrib.sessions',
    'django.contrib.messages',
    'django.contrib.staticfiles',
    'corsheaders',
    'rest_framework', # for restful api
    'django_filters',
    'app_account', # the apps
    'app_admin',
    'app_main',
]
...
GEOIP_PATH =os.path.join(BASE_DIR, 'geoip') # the location of ip db

saas/settings.py

Let's create a folder in the main app path with the name 'geoip' to store the IP databases in the next step.

PS. I highly recommend using the account management app from previous tutorials to save time and effort later on.

DP-IP datasets

Now that we have our project ready, we can download IP databases from DP-IP. It has multiple free "IP Geolocation Databases" that update monthly. Let's start by downloading the database we want to use from

https://db-ip.com/db/lite.php

We will use IP to city db, after agreeing with the licensing terms, make sure to download the MMDB version of the database. It was about 60MB at the time of writing this tutorial.

Extract the downloaded MMDB file, rename it to GeoLite2-City.mmdb, and make sure to put it in the geoip folder in the project folder

GeoIP implementation testing

Let's check if it works. Firstly, we need to migrate the dataset and make sure the project works properly

python manage.py makemigrations
python manage.py migrate
python manage.py runserver 0.0.0.0:8555

This should run the project on port 8555. If it works successfully, we can

python manage.py shell

In [1]: from django.contrib.gis.geoip2 import GeoIP2                                     

In [2]: g = GeoIP2()                                                                     

In [3]: g.city("72.14.207.99")                                                           
Out[3]:                                                                                  
{'city': 'Mountain View',
 'continent_code': 'NA',
 'continent_name': 'North America',
 'country_code': 'US',
 'country_name': 'United States',
 'dma_code': None,
 'is_in_european_union': False,
 'latitude': 37.4225,
 'longitude': -122.085,
 'postal_code': None,
 'region': None,
 'time_zone': None}

In [4]:

Great! Now that we know it works, let's create a simple API where users send the IP and we answer with its location.

GeoIP API

To simplify this step, let's skip using serializers and pass the IP as a GET parameter, in the views file

from rest_framework.views import APIView
from rest_framework.response import Response
from rest_framework.exceptions import APIException
from common.utils import *

from django.contrib.gis.geoip2 import GeoIP2, GeoIP2Exception

class GeoIPView(APIView):
    permission_classes = ( )
    renderer_classes = [CustomRenderer, BrowsableAPIRenderer]

    def get(self, request, *args, **kwargs):
        ip_address = request.query_params.get('ip', None)
        if not ip_address:
            raise APIException("The 'ip' query parameter is required.")

        try:
            g = GeoIP2()
            # You can use .city(ip), .country(ip), etc. depending on the data you need
            geoip_data = g.city(ip_address)
            return Response(geoip_data)
        except GeoIP2Exception:
            # This exception is raised if the IP address is not in the database.
            raise APIException(f"Information for IP address '{ip_address}' not found.")

app_main/views.py

We are getting the IP from GET parameters, then passing it to GeoIP, and responding with its direct response.
Let's assign a URL for the view

from django.urls import path, include
from .views import *

urlpatterns = [
    path('geoip/', GeoIPView.as_view()),
]

app_main/urls.py

from django.contrib import admin
from django.urls import path, include

urlpatterns = [
    path('admin/', admin.site.urls),
    path('api/', include('app_main.urls')),
]

saas/urls.py

Let's try it out!

great!
Let's do something more entertaining, let's edit the API to respond with the user's IP location if the IP parameter is not provided!

from django.contrib.gis.geoip2 import GeoIP2, GeoIP2Exception

class GeoIPView(APIView):
    permission_classes = ( )
    renderer_classes = [CustomRenderer, BrowsableAPIRenderer]

    def _get_client_ip(self, request):
        """Helper method to get the client's real IP address from the request."""
        # Check for the X-Forwarded-For header, which is used by proxies
        x_forwarded_for = request.META.get('HTTP_X_FORWARDED_FOR')
        if x_forwarded_for:
            # The header can contain a comma-separated list of IPs; the first is the client
            ip = x_forwarded_for.split(',')[0]
        else:
            # If not behind a proxy, use the standard REMOTE_ADDR
            ip = request.META.get('REMOTE_ADDR')
        return ip

    def get(self, request, *args, **kwargs):
        ip_address = request.query_params.get('ip', None)
        if not ip_address:
            ip_address = self._get_client_ip(request)


        try:
            g = GeoIP2()
            # You can use .city(ip), .country(ip), etc. depending on the data you need
            geoip_data = g.city(ip_address)
            return Response(geoip_data)
        except Exception as e:
            # This exception is raised if the IP address is not in the database.
            raise APIException(f"Information for IP address '{ip_address}' not found.")

app_main/views.py

We start by looking for ip parameter in the GET request; if it exists, we look for it; if not, we will try to get the request IP.
_get_client_ip will get the request IP, locally it will get the local IP, if online, it will get the user request IP.

Let's try it online

GET /api/geoip/

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "status": "success",
    "code": 200,
    "data": {
        "city": "Remscheid",
        "continent_code": "EU",
        "continent_name": "Europe",
        "country_code": "DE",
        "country_name": "Germany",
        "dma_code": null,
        "is_in_european_union": true,
        "latitude": 51.1798,
        "longitude": 7.1925,
        "postal_code": null,
        "region": null,
        "time_zone": null
    },
    "message": null
}

GET /api/geoip/

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "status": "success",
    "code": 200,
    "data": {
        "city": "Nicosia",
        "continent_code": "EU",
        "continent_name": "Europe",
        "country_code": "CY",
        "country_name": "Cyprus",
        "dma_code": null,
        "is_in_european_union": true,
        "latitude": 35.1728,
        "longitude": 33.354,
        "postal_code": null,
        "region": null,
        "time_zone": null
    },
    "message": null
}

Bonus, User IP 🤓

We can add the user IP to the response by adding one line to the view as

...
        try:
            g = GeoIP2()
            # You can use .city(ip), .country(ip), etc. depending on the data you need
            geoip_data = g.city(ip_address)
            geoip_data['ip'] = ip_address
            return Response(geoip_data)
        except Exception as e:
            # This exception is raised if the IP address is not in the database.
            raise APIException(f"Information for IP address '{ip_address}' not found.")

app_main/views.py

the response

GET /api/geoip/

HTTP 200 OK
Allow: GET, HEAD, OPTIONS
Content-Type: application/json
Vary: Accept

{
    "status": "success",
    "code": 200,
    "data": {
        "city": "Beirut",
        "continent_code": "AS",
        "continent_name": "Asia",
        "country_code": "LB",
        "country_name": "Lebanon",
        "dma_code": null,
        "is_in_european_union": false,
        "latitude": 33.8938,
        "longitude": 35.5018,
        "postal_code": null,
        "region": null,
        "time_zone": null,
        "ip": "185.227.133.12"
    },
    "message": null
}

That is it for this tutorial. We still need to add the SaaS users/ tokens/ stats management, which we will discuss in another tutorial, so

Stay tuned 😎

Setup iOS Account for Production

Saad Alkentar — Thu, 03 Jul 2025 10:13:20 +0000

Have you ever tried to publish an iOS app for yourself / a company/ a client? or maybe you are a DevOps trying to setup an iOS build pipeline for Bitrise, Bitbucket, AWS CloudFormation, or some other DevOps platform?
It simply asks for a certificate and a profile, but how to get them? well, I'm trying to help you obtain the required certificate and profile for publication
Let's dive in

Create a distribution certificate

I'll divide the operation into steps, let's start at the beginning

Create a certificate request from authority

Open Keychain Access: Command + Space -> type keychain
Create a certificate request from the main app menu
Use your email address and choose to save the request to disk

Open the used Apple Developer account https://developer.apple.com/account
Choose the correct account namespace (if it has many)
Choose Certificates
Create a new certificate
Select distribution certificate (Apple or iOS)
Then use the certificate request created before
Memorize the certificate expiration date, since we don’t have control over the certificate name, and download it

Create a profile

From the Apple Developer account, choose profiles and create a new one
Choose the distribution ad-hoc profile
Select the App ID
Select the certificate you created before (make sure using the expiration date)
Select all devices to be tested on
Name the certificate, something like UserName-AppName profile
Download the profile

Setup the project

Select the project, and choose the “Signing & Capabilities” tab
From the provisioning profile, choose “Import profile.”

This should be it. If you have any issues with the new profile, you can enable “Automatically manage signing” and disable it again to allow XCode

We will continue on more tips for iOS in coming tutorials so
Stay tuned 😎

Open Finder folder with IntelliJ IDEA, Sublime Text or VSCode

Saad Alkentar — Sun, 16 Feb 2025 06:17:56 +0000

What to expect from this article?

Finder is absolutely the best file browser for Mac! Don't waste your time looking for a better one (you would do it anyway, in case you are coming from a Linux background like me 🤓). But Finder has a few issues, actually

No option to show hidden files
No clear file/folder path
No option to customize the context menu

First two are actually simple to solve.

command + shift + . shows hidden files 😁
from View menu, choose show path bar 😉
this one is still kinda ugly ⚠️

This is a simple tip for Mac users in order to speed up opening code folders in Finder files explorer.

Where to start?

Start by opening Mac Automator app. command+space, type automator
Choose to create a Quick Action
Choose to show your quick action for folders in Finder, then choose an image (for some reason, it doesn't work for me since I use the path bar, but it might work for you)
Choose the action from Files ... olders, and double-click on Open Finder Items
Choose the app to lunch; if you cannot find it directly, choose Other...
Save the action; just press command + s and choose a name
Test it in the finder!
Either right-click on any folder and choose it from quick actions section

or from right-clicking any folder in the path bar

or from the quick preview section

A special tip: If you have already created too many actions (like me while testing 😅), you might prefer to be able to remove the unused ones.
You can find the created actions at /Users/username/Library/Services folder
Use command + shift + . to show hidden files and folders to find the Library

Stay tuned for more tips and tricks 😎

Flutter app, fading chat logic with bloc and hooks

Saad Alkentar — Mon, 10 Feb 2025 06:22:07 +0000

What can you expect from this article?

We finished the fading transition implementation in the previous article and will use it to finish our home chat page.
It is a specific scenario we are trying to build, so it is a good practice for bloc with hooks usage. Yet, it might be too specific, so feel free to skip this article.
PS. we are working on our already built code base.

The scenario we are trying to build is

The user clicks on the text field
The app closes the keyboard (for the first time)
The app sends a conversation request to the AI
The app fades in the server response
The user clicks on the text field to start writing the response
The app fades out the server response
The user clicks the send button from the keyboard
The app sends the message to the AI
The app fades out the user text and fades in the server response

The app should read the server response, and the user can use STT (speech to text) instead of writing. Please refer to Flutter App, Speech to Text and Text to Speech for detailed implementation of TTS and STT.

API calls and models (optional)

We will try to concentrate on the home screen UI since we have already detailed how to implement any API in our clean architecture project, but it doesn't hurt to repeat. So feel free to skip this part of the article if you are familiar with the process.

Start at the domain layer

We always start by creating the models in the domain layer

class MessageModel {
  MessageModel({
      this.created, 
      this.active, 
      this.text, 
      this.isUser, 
      this.conversation, 
      this.id,});

  MessageModel.fromJson(dynamic json) {
    created = json['created'];
    active = json['active'];
    text = json['text'];
    isUser = json['is_user'];
    conversation = json['conversation'];
    id = json['id'];
  }

  String? created;
  bool? active;
  String? text;
  bool? isUser;
  int? conversation;
  int? id;

  Map<String, dynamic> toJson() {
    final map = <String, dynamic>{};
    map['created'] = created;
    map['active'] = active;
    map['text'] = text;
    map['is_user'] = isUser;
    map['conversation'] = conversation;
    map['id'] = id;
    return map;
  }
}

lib/domain/models/entities/message_model.dart

Next is to update the repository schema in the domain layer

import '../models/entities/message_model.dart';

...
abstract class RemoteRepository {

  ...

  Future<DataState<GenericResponse<MessageModel>>> conversationStart();

  Future<DataState<GenericResponse<MessageModel>>> conversationSend({
    required String? text,
    required int? conversation,
  });
}

lib/domain/repositories/remote_repository.dart

Data layer

The first step in the data layer is to add the requests to the data source

...
  @GET('/conversation/')
  Future<HttpResponse<GenericResponse<MessageModel>>> conversationStart({
    @Header("Authorization") String? token,
    @Header("Accept-Language") String? lang,
  });

  @POST('/conversation/')
  Future<HttpResponse<GenericResponse<MessageModel>>> conversationSend({
    @Body() MessageRequest? request,
    @Header("Authorization") String? token,
    @Header("Accept-Language") String? lang,
  });
...

lib/data/sources/remote_datasource.dart

PS. Don't forget to issue dart run build_runner build to generate the data source code.

Next is to implement the repository schema

...
  @override
  Future<DataState<GenericResponse<MessageModel>>> conversationSend({
    String? text,
    int? conversation
  }) => getStateOf(
    request: () => remoteDatasource.conversationSend(
      request: MessageRequest(
        text: text,
        conversation: conversation
      ),
      lang: "en",
      token: "Bearer ${preferencesRepository.getToken()}",
    ),
  );

  @override
  Future<DataState<GenericResponse<MessageModel>>> conversationStart() => getStateOf(
    request: () => remoteDatasource.conversationStart(
      lang: "en",
      token: "Bearer ${preferencesRepository.getToken()}",
    ),
  );
...

lib/data/repositories/remote_repository_impl.dart

nice and easy, let's begin with the serious work

Chat screen events and states

Back to our home screen, let's start working on the bloc logic, as always, when working with bloc, we start with the events, then the states and finally the bloc logic itself

The events

We already have two events, one for TTS and another for STT, we need two extra events, one for starting a conversation, and another one for sending a text.

part of 'home_bloc.dart';

@immutable
sealed class HomeEvent {
  final String? text;
  const HomeEvent({this.text});
}

class HomeSTTEvent extends HomeEvent {}

class HomeTTSEvent extends HomeEvent {
  const HomeTTSEvent({super.text});
}

class HomeStartEvent extends HomeEvent {}
class HomeSendEvent extends HomeEvent {
  const HomeSendEvent({super.text});
}

lib/presentation/screens/home/home_event.dart

The States

With the events ready, we move to the states, we already have states for listening, reading, and errors. but we also need states for loading and receiving text.

part of 'home_bloc.dart';

@immutable
sealed class HomeState {
  final String? text;
  final String? error;
  const HomeState({
    this.text,
    this.error,
  });
}

final class HomeInitial extends HomeState {}
final class HomeListeningState extends HomeState {}
final class HomeReadingState extends HomeState {}
final class HomeErrorState extends HomeState {
  const HomeErrorState({super.error});
}
final class HomeSTTState extends HomeState {
  const HomeSTTState({super.text});
}

final class HomeLoadingState extends HomeState {}
final class HomeReceiveState extends HomeState {
  const HomeReceiveState({super.text});
}

lib/presentation/screens/home/home_state.dart

With our states and events ready, it is time to connect them in the bloc file

Bloc logic

In order to make the conversation requests, we are going to need access to the remote_repository, so let's add it to the bloc dependencies

...
  final RemoteRepository repository;

  HomeBloc(this.stt, this.tts, this.repository) : super(HomeInitial()) {
...

lib/presentation/screens/home/home_bloc.dart

We need to pass the new dependency from the main app file, just update the current bloc provider to provide it

...
-          BlocProvider(create: (context)=>HomeBloc(locator(), locator())),
+          BlocProvider(create: (context)=>HomeBloc(locator(), locator(), locator())),
...

lib/main.dart

Next step is to handle our newly added events, let's start with HomeStartEvent, when we receive it, we should make a start conversation request

import '../../../utils/data_state.dart';
import '../../../utils/dio_exception_extension.dart';
...
  HomeBloc(this.stt, this.tts, this.repository) : super(HomeInitial()) {
  int? conversationId = 0;
...
  HomeBloc(this.stt, this.tts, this.repository) : super(HomeInitial()) {
    ...
    on<HomeStartEvent>(handleStartEvent);
  }
...
  FutureOr<void> handleStartEvent(
      HomeStartEvent event,
      Emitter<HomeState> emit,
  ) async {
    emit(HomeLoadingState());

    final response = await repository.conversationStart();

    if (response is DataSuccess) {
      conversationId = response.data?.data?.conversation;

      emit(HomeReceiveState(
        text: response.data?.data?.text,
      ));
    } else {
      emit(HomeErrorState(error: response.error?.getErrorMessage(),));
    }
  }

lib/presentation/screens/home/home_bloc.dart

when receiving the event, we are making the start conversation request, the conversation id is saved in the bloc instance, then we emit the response text through HomeReceiveState

now for handling the send event

...
  HomeBloc(this.stt, this.tts, this.repository) : super(HomeInitial()) {
...
    on<HomeSendEvent>(handleSendEvent);
  }
...
  FutureOr<void> handleSendEvent(
      HomeSendEvent event,
      Emitter<HomeState> emit,
  ) async {
    emit(HomeLoadingState());

    recognizedText = "";

    final response = await repository.conversationSend(
      text: event.text ?? "",
      conversation: conversationId ?? 0,
    );

    if (response is DataSuccess) {
      emit(HomeReceiveState(
        text: response.data?.data?.text,
      ));

    } else if (response is DataFailed) {
      emit(HomeErrorState(
        error: response.error?.getErrorMessage(),
      ));
    }

  }

lib/presentation/screens/home/home_bloc.dart

We are cleaning the recognized text (in case of using STT by the user) then making the conversation send request, and passing the response text through HomeReceiveState to the UI
it is time to move the home screen itself

Home screen

We are working on the last version of Home screen after the TTS and STT article and the hooks article. We already have text field, microphone button, and a bloc listener, the full code look like

import 'package:alive_diary_app/config/dependencies.dart';
import 'package:alive_diary_app/config/router/app_router.dart';
import 'package:alive_diary_app/domain/repositories/preferences_repository.dart';
import 'package:alive_diary_app/presentation/widgets/layout_widget.dart';
import 'package:auto_route/auto_route.dart';
import 'package:easy_localization/easy_localization.dart';
import 'package:flutter/material.dart';
import 'package:flutter/services.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:flutter_hooks/flutter_hooks.dart';
import 'package:google_fonts/google_fonts.dart';
import 'home_bloc.dart';


@RoutePage()
class HomeScreen extends HookWidget {
  const HomeScreen({super.key, this.title});

  final String? title;

  @override
  Widget build(BuildContext context) {
    final bloc = BlocProvider.of<HomeBloc>(context);

    final isLoading = useState(false);
    final speechText = useState("");
    final canWrite = useState<bool?>(null);
    final textController = useTextEditingController();

    AnimationController animationController = useAnimationController(
        duration: const Duration(seconds: 4),
        initialValue: 0,
    );

    void showText(String? text) async {
      await Future.delayed(const Duration(milliseconds: 100));
      SystemChannels.textInput.invokeMethod('TextInput.hide');
      animationController.animateBack(0, duration: const Duration(seconds: 1));
      await Future.delayed(const Duration(seconds: 2));
      textController.text = text ?? "";
      animationController.forward();
    }

    void clearText() async {
      animationController.animateBack(0, duration: const Duration(seconds: 1));
      await Future.delayed(const Duration(seconds: 2));
      textController.text = "";
      animationController.forward();
    }

    return BlocListener<HomeBloc, HomeState>(
      listener: (context, state) {
        isLoading.value = state is HomeListeningState;

        if (state is HomeSTTState) {
          speechText.value = state.text ?? "";
        }

      },
      child: LayoutWidget(
        title: 'home'.tr(),
        actions: [
          IconButton(
            icon: const Icon(Icons.logout, color: Colors.black,),
            onPressed: (){
              locator<PreferencesRepository>().logout();
              appRouter.replaceAll([LoginRoute()]);
            },
          )
        ],
        floatingActionButton: FloatingActionButton(
          tooltip: 'Listen',
          child: Icon(
            Icons.keyboard_voice_outlined,
            color: isLoading.value ? Colors.green : Colors.blue,
          ),
          onPressed: () => bloc.add(HomeSTTEvent()),
        ),
        child:Container(
          height: double.infinity,
          padding: const EdgeInsets.symmetric(horizontal: 15),
          decoration: const BoxDecoration(
            image: DecorationImage(
              image: AssetImage("assets/images/paper_bg.jpg"),
              fit: BoxFit.cover,
            ),
          ),
          child: FadeTransition(
            opacity: animationController,
            child: TextField(
              decoration: const InputDecoration(border: InputBorder.none),
              // focusNode: textNode,
              cursorHeight: 35,
              style: GoogleFonts.caveat(
                fontSize: 30,
                color: Colors.black,
              ),
              keyboardType: TextInputType.multiline,
              textInputAction: TextInputAction.send,
              controller: textController,
              maxLines: null,
              onTap: () async {

                if (canWrite.value == null) {
                  showText("How was your day?");
                  canWrite.value = true;
                } else if (canWrite.value == true) {
                  clearText();
                }

              },
              onSubmitted: (text) async {
                showText("Tell me more");
              },
            ),
          ),
        ),
      ),

    );
  }
}

lib/presentation/screens/home/home_screen.dart

when clicking on the text field for the first time, a conversation start request should be made, and when receiving the response, it should be shown using the HomeReceiveState

...
    return BlocListener<HomeBloc, HomeState>(
      listener: (context, state) {

        if (state is HomeReceiveState) {
          showText(state.text);
          canWrite.value = true;
        }

...

          child: FadeTransition(
            opacity: animationController,
            child: TextField(
...
              onTap: () async {

                if (canWrite.value == null) {
                  bloc.add(HomeStartEvent()); // new
                } else if (canWrite.value == true) {
                  clearText();
                }

              },
              onSubmitted: (text) async {
                bloc.add(HomeSendEvent(text: text)); // new
              },
            ),
          ),

lib/presentation/screens/home/home_screen.dart

We should be able to test it now, clicking on the text box should show the server response, clicking on it again should fade away the text and allow user to type the message, hitting keyboard submit should send the message back to the server and show its response

first response	typing message	receiving a response

Now for the reader, it is kinda easy from now, when receiving the server response, all we need to do is to add a TTS event

...
    void showText(String? text) async {
      await Future.delayed(const Duration(milliseconds: 100));
      SystemChannels.textInput.invokeMethod('TextInput.hide');
      animationController.animateBack(0, duration: const Duration(seconds: 1));
      await Future.delayed(const Duration(seconds: 2));
      textController.text = text ?? "";
      animationController.forward();
      bloc.add(HomeTTSEvent(text: text));
    }
...

lib/presentation/screens/home/home_screen.dart

That is it for this article. I know it is too much to handle, and too many details to follow, just treat it as an optional if you didn't follow previous ones.

This app is finished now, we have fully implemented the main feature with this article. I'll start working on apps I want to publish on the store next, so, as always

Stay tuned 😎

Flutter App, Simple animation with Hooks 🪝

Saad Alkentar — Tue, 04 Feb 2025 10:49:48 +0000

What to expect from this tutorial?

This is a simple tutorial to add fading animation for a text field using flutter_hooks

usually, to add animation to any Flutter UI element, it has to be a state-full widget, the animation controller should be created in the state class, initState should be overwritten to populate the animation instance, and we should also override dispose to clean the memory from our animation controller when navigating to another screen!
It has always been a hurdle 😵, so I avoided using it as much as possible, but flutter_hooks has finally simplified the operation a bit, let's start by cleaning the home_screen code (you can start with your own screen of course).

The idea

Well, our diary is kinda similar to "Tom Riddle" diary (in "Harry Potter and the Chamber of Secrets"). And I liked how Harry's writing disappears, and Tom's answer appears in the diary. So, let's add fading animation to the text when sent to the AI and an appearing animation when received back from the AI. We will start by creating a simple fade-in and fade-out animation, then work on building app-specific behavior.

The behavior we wanna build is like this:

The user clicks on the text field
The app closes the keyboard (for the first time)
The app sends a conversation request to the AI
app fade in the server response
The user clicks on the text field to start writing the response
The app fades out the server response
The user clicks the send button from the keyboard
The app sends the message to the AI
the app fades out the user text and fades in the server response

Clean `home_screen` code (optional)

If you are following this tutorial series, you will have some code in home_screen, so let's clean it a bit by using LayoutWidget from the previous article, removing screen contents, changing the action button to a logout button, and showing only the listen floating button

import 'package:alive_diary_app/config/dependencies.dart';
import 'package:alive_diary_app/config/router/app_router.dart';
import 'package:alive_diary_app/domain/repositories/preferences_repository.dart';
import 'package:alive_diary_app/presentation/widgets/layout_widget.dart';
import 'package:auto_route/auto_route.dart';
import 'package:easy_localization/easy_localization.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:flutter_hooks/flutter_hooks.dart';
import 'home_bloc.dart';


@RoutePage()
class HomeScreen extends HookWidget {
  const HomeScreen({super.key, this.title});

  final String? title;

  @override
  Widget build(BuildContext context) {
    final bloc = BlocProvider.of<HomeBloc>(context);

    final isLoading = useState(false);
    final speechText = useState("");

    return BlocListener<HomeBloc, HomeState>(
      listener: (context, state) {
        isLoading.value = state is HomeListeningState;

        if (state is HomeSTTState) {
          speechText.value = state.text ?? "";
        }

      },
      child: LayoutWidget(
        title: 'home'.tr(),
        actions: [
          IconButton(
            icon: const Icon(Icons.logout, color: Colors.black,),
            onPressed: (){
              locator<PreferencesRepository>().logout();
              appRouter.replaceAll([LoginRoute()]);
            },
          )
        ],
        floatingActionButton: FloatingActionButton(
          tooltip: 'Listen',
          child: Icon(
            Icons.keyboard_voice_outlined,
            color: isLoading.value ? Colors.green : Colors.blue,
          ),
          onPressed: () => bloc.add(HomeSTTEvent()),
        ),
        child: Container(
          alignment: Alignment.center,
          child: const Text("Empty"),
        ),
      ),

    );
  }
}

lib/presentation/screens/home/home_screen.dart

The fun part 😁, the Animation!

To create animations with flutter_hooks, we start by creating the animation controller hook

    AnimationController animationController = useAnimationController(
        duration: const Duration(seconds: 4),
        initialValue: 1,
    );

then we use it in the Transition component

              FadeTransition(
                opacity: animationController,
                child: Center(
                    child: Text("Hello World")
                ),
              ),

that is it! no initState, no dispose, no headache

For our app, we need to show and hide text, so let's add two buttons to the home screen, one for showing and another one for hiding, it would look somewhat like

import 'package:alive_diary_app/config/dependencies.dart';
import 'package:alive_diary_app/config/router/app_router.dart';
import 'package:alive_diary_app/domain/repositories/preferences_repository.dart';
import 'package:alive_diary_app/presentation/widgets/layout_widget.dart';
import 'package:auto_route/auto_route.dart';
import 'package:easy_localization/easy_localization.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:flutter_hooks/flutter_hooks.dart';
import 'package:google_fonts/google_fonts.dart';
import 'home_bloc.dart';


@RoutePage()
class HomeScreen extends HookWidget {
  const HomeScreen({super.key, this.title});

  final String? title;

  @override
  Widget build(BuildContext context) {
    final bloc = BlocProvider.of<HomeBloc>(context);

    final isLoading = useState(false);
    final speechText = useState("");

    AnimationController animationController = useAnimationController(
        duration: const Duration(seconds: 4),
        initialValue: 1,
    );

    return BlocListener<HomeBloc, HomeState>(
      listener: (context, state) {
        isLoading.value = state is HomeListeningState;

        if (state is HomeSTTState) {
          speechText.value = state.text ?? "";
        }

      },
      child: LayoutWidget(
        title: 'home'.tr(),
        actions: [
          IconButton(
            icon: const Icon(Icons.logout, color: Colors.black,),
            onPressed: (){
              locator<PreferencesRepository>().logout();
              appRouter.replaceAll([LoginRoute()]);
            },
          )
        ],
        floatingActionButton: FloatingActionButton(
          tooltip: 'Listen',
          child: Icon(
            Icons.keyboard_voice_outlined,
            color: isLoading.value ? Colors.green : Colors.blue,
          ),
          onPressed: () => bloc.add(HomeSTTEvent()),
        ),
        child:Container(
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            children: [
              FadeTransition(
                opacity: animationController,
                child: Center(
                    child: Text("Hello World",
                      style: GoogleFonts.caveat(
                        fontSize: 30,
                        color: Colors.black,
                      ),
                    )
                ),
              ),
              ElevatedButton(
                child: Text("show".tr()),
                onPressed: () async {
                  animationController.forward();
                },
              ),

              ElevatedButton(
                child: Text("hide".tr()),
                onPressed: (){
                  animationController.animateBack(0,
                      duration: const Duration(seconds: 1),
                  );
                },
              )

            ],
          ),
        ),
      ),

    );
  }
}

lib/presentation/screens/home/home_screen.dart

We are using google_fonts to make the font more human-like 🤓, with google fonts, you are free to choose from a wide range of great fonts, but feel free to ignore it since it doesn't have to do with the animation itself 😅

The home UI should look somewhat like

hidden	shown

The text should be visible in the initial state, clicking hide should fade it away, and clicking show should fade it in. We can change the initial text state to hidden by changing initialValue to 0.

simple and great! no need to run from UI animation anymore 😁, now for the app behavior, let's start working on it

Diary app text field behavior

Let's start by creating a large text field, with a nice paper-like background, and address the onTab and onSubmit actions

...
  Widget build(BuildContext context) {
    final textController = useTextEditingController();

...
      child: LayoutWidget(
        title: 'home'.tr(),
...
        child:Container(
          height: double.infinity,
          padding: const EdgeInsets.symmetric(horizontal: 15),
          decoration: const BoxDecoration(
            image: DecorationImage(
              image: AssetImage("assets/images/paper_bg.jpg"),
              fit: BoxFit.cover,
            ),
          ),
          child: TextField(
            decoration: const InputDecoration(border: InputBorder.none),
            cursorHeight: 35,
            style: GoogleFonts.caveat(
              fontSize: 30,
              color: Colors.black
            ),
            keyboardType: TextInputType.multiline,
            textInputAction: TextInputAction.send,
            controller: textController,
            maxLines: null,
            onTap: () async {

            },
            onSubmitted: (text) async {

            },
          ),
        ),
      ),
...

lib/presentation/screens/home/home_screen.dart

We have added a text field, with a background, multiple lines support, and functions for clicking and submitting (the software keyboard submit button), let's start with how to dismiss the software keyboard?

Dismiss the software keyboard in flutter

How to dismiss the software keyboard? it is kinda tricky, in Android, we start by adding PROCESS_TEXT query in the manifest at the same level as the application section

...
    <queries>
        <intent>
            <action android:name="android.intent.action.PROCESS_TEXT"/>
            <data android:mimeType="text/plain"/>
        </intent>
    </queries>

    <application
        android:label="alive_diary_app"
        android:name="${applicationName}"
        android:icon="@mipmap/launcher_icon">
...

android/app/src/main/AndroidManifest.xml

Now we can test it in the app with the TextInput.hide method as

import 'package:flutter/services.dart';

...
            child: TextField(
              decoration: const InputDecoration(border: InputBorder.none),
              cursorHeight: 35,
              style: GoogleFonts.caveat(
                fontSize: 30,
                color: Colors.black,
              ),
              keyboardType: TextInputType.multiline,
              textInputAction: TextInputAction.send,
              controller: textController,
              maxLines: null,
              onTap: () async {
                await Future.delayed(const Duration(seconds: 2));
                SystemChannels.textInput.invokeMethod('TextInput.hide');

              },
...

lib/presentation/screens/home/home_screen.dart

The keyboard will appear when clicking on the text field, then after two seconds, it will just disappear.

Text field animation

We want to apply the animation on the text field, so it must be wrapped with FadeTransition, and we need two functions

showText function, which hides the keyboard, sets the new value and fades it in
clearText function, which fades out field contents, and sets it to an empty text.

...
  Widget build(BuildContext context) {
    final isLoading = useState(false);
    final speechText = useState("");
    final canWrite = useState<bool?>(null);
    final textController = useTextEditingController();

...
    void showText(String? text) async {
      await Future.delayed(const Duration(milliseconds: 100));
      SystemChannels.textInput.invokeMethod('TextInput.hide');
      animationController.animateBack(0, duration: const Duration(seconds: 1));
      await Future.delayed(const Duration(seconds: 2));
      textController.text = text ?? "";
      animationController.forward();
    }

    void clearText() async {
      animationController.animateBack(0, duration: const Duration(seconds: 1));
      await Future.delayed(const Duration(seconds: 2));
      textController.text = "";
      animationController.forward();
    }
...
            child: TextField(
              decoration: const InputDecoration(border: InputBorder.none),
              cursorHeight: 35,
              style: GoogleFonts.caveat(
                fontSize: 30,
                color: Colors.black,
              ),
              keyboardType: TextInputType.multiline,
              textInputAction: TextInputAction.send,
              controller: textController,
              maxLines: null,
              onTap: () async {

                if (canWrite.value == null) {
                  showText("How was your day?");
                  canWrite.value = true;
                } else if (canWrite.value == true) {
                  clearText();
                }

              },
              onSubmitted: (text) async {
                showText("Tell me more");
              },
            ),
...

lib/presentation/screens/home/home_screen.dart

That is it! well, almost, we are mimicking the server response with a plain text, but whatever, let's concentrate on the behavior for now

we have created the two functions showText and clearText, we have created a new helper state canWrite in order to distinguish the first click,
if this is the first click, we show the server response (static text for now), but if this is not the first time, then we simply clear the text.
when clicking the keyboard submit button, we (should send the text to server and show its response) show the message "Tell me more"

This is the required behavior as described, let's continue building the app together and as always

Stay tuned 😎

Flutter app, layout widget and bottom navigation bar with auto-router

Saad Alkentar — Mon, 27 Jan 2025 14:44:12 +0000

What to expect from this tutorial?

This is a simple tutorial that covers creating a bottom navigation bar with the auto_route library

auto_route is one of the most common Flutter navigation packages, it allows for strongly typed arguments passing, and effortless deep-linking and it uses code generation to simplify route setup.

bottom navigation bar is very popular in modern apps due to its simplicity and wide acceptance from users. this article will cover implementing it in our Flutter app.

The complete picture!

We want to build a bottom navigation bar with three navigation buttons. The screen code should be independent of the navigation code. So, we will start by creating our three screens, just as empty screens, and then connect them through the navigation bar as planned. let's also allow child screens to hide the bottom navigation bar as most apps do.
We have already initiated the auto_route library in previous article, refer to Screen routing with auto_route paragraph in the tutorial for basic library initiation.

Create navigation screens

Let's start by creating three screens; we will call them home, memories, and profile screens.
We will use our previously designed home and memories screens. simplest profile screen would look somewhat like

import 'package:auto_route/auto_route.dart';
import 'package:flutter/material.dart';

@RoutePage()
class ProfileScreen extends StatelessWidget {
  const ProfileScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return Container(
      child: Text("profile"),
    );
  }
}

lib/presentation/screens/profile/profile_screen.dart

PS. We can use similarly simple home and memories screens too

notice that we are using RoutePage annotation for all screens, so make sure to generate the router code after creating screens by issuing

dart run build_runner build - delete-conflicting-outputs

next step is to create the bottom navigation screen itself, there are multiple ways to do so as auto_route documentation mentioned, but I found the easiest way is to use AutoTabsScaffold

import 'package:alive_diary_app/config/router/app_router.dart';
import 'package:auto_route/auto_route.dart';
import 'package:flutter/material.dart';


@RoutePage()
class HomeNavScreen extends StatelessWidget {
  const HomeNavScreen({super.key});

  @override
  Widget build(BuildContext context) {

    return AutoTabsScaffold(
      routes: [
        HomeRoute(),
        const MemoriesRoute(),
        const ProfileRoute(),
      ],

      bottomNavigationBuilder: (context, tabsRouter) {
        return BottomNavigationBar(
          currentIndex: tabsRouter.activeIndex,
          onTap: tabsRouter.setActiveIndex,
          backgroundColor: Theme.of(context).primaryColor,
          selectedItemColor: Colors.white,
          unselectedItemColor: Colors.white54,
          items: const [
            BottomNavigationBarItem(icon: Icon(Icons.home), label: "home"),
            BottomNavigationBarItem(icon: Icon(Icons.menu_book_sharp), label: "memories"),
            BottomNavigationBarItem(icon: Icon(Icons.person), label: "profile"),
          ],
        );
      },
    );

  }
}

lib/presentation/screens/home_nav/home_nav_screen.dart

the two main parameters for AutoTabsScaffold are routes, which indicate the child screen routes, and bottomNavigationBuilder, which builds the bottom navigation bar. we can also build the top navigation bar using appBarBuilder, but I recommend customizing it per screen (each screen has its own bar).

Navigation config

after building the navigation screen itself, it is time to config it in the app_router file

import 'package:alive_diary_app/domain/repositories/preferences_repository.dart';
import 'package:auto_route/auto_route.dart';
import 'package:flutter/material.dart';

import '../../presentation/screens/home/home_screen.dart';
import '../../presentation/screens/home_nav/home_nav_screen.dart';
import '../../presentation/screens/login/login_screen.dart';
import '../../presentation/screens/memories/memories_screen.dart';
import '../../presentation/screens/profile/profile_screen.dart';
import '../dependencies.dart';


part 'app_router.gr.dart';


@AutoRouterConfig()
class AppRouter extends _$AppRouter {

  bool invalidToken() => locator<PreferencesRepository>().invalidToken();

  @override
  List<AutoRoute> get routes => [
    AutoRoute(page: LoginRoute.page, initial: invalidToken()),

    AutoRoute(
      page: HomeNavRoute.page,
      initial: !invalidToken(),
      children: [
        AutoRoute(page: HomeRoute.page),
        AutoRoute(page: MemoriesRoute.page),
        AutoRoute(page: ProfileRoute.page),
      ],
    ),

  ];
}

final appRouter = AppRouter();

lib/config/router/app_router.dart

this is the complete app router config file, notice how we set the tab screens as children of the main navigation screen. we can also pass the screen title to the AutoRoute if preferable.

We have already explained the token validation previously. in case of an invalid token, we are showing the login screen, otherwise, we are showing the main screen.

great, let's run the app now

home	memories	profile

home and memories screens look great, since we have already implemented their own top navigation bar, but what about our new simple profile screen then??

I would recommend creating a layout widget that can be easily reused for all your apps

Layout widget

How to create a layout widget? it is simple actually, we basically need access to the page title and maybe the floating button only, why keep the headache of the full scaffold every time!

import 'package:flutter/material.dart';

class LayoutWidget extends StatelessWidget {
  final Widget child;
  final String title;
  final Widget? floatingActionButton;
  final List<Widget>? actions;

  const LayoutWidget({
    super.key,
    required this.child,
    this.title="home",
    this.floatingActionButton,
    this.actions,
  });

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(
        title: Text(title),
        iconTheme: const IconThemeData(
          color: Colors.white,
        ),
        backgroundColor: Theme
            .of(context)
            .colorScheme
            .inversePrimary,
        actions: actions,
      ),
      body: Container(
        child: child,
      ),
      floatingActionButton: floatingActionButton,
    );
  }
}

lib/presentation/widgets/layout_widget.dart

we are wrapping the scaffold in our widget, with the ability to add actions, a floating action button, and the main screen body. Let's use this widget for our newly created profile screen

import 'package:auto_route/auto_route.dart';
import 'package:flutter/material.dart';

import '../../widgets/layout_widget.dart';

@RoutePage()
class ProfileScreen extends StatelessWidget {
  const ProfileScreen({super.key});

  @override
  Widget build(BuildContext context) {
    return LayoutWidget(
      title: "Profile",
      child: Container(
        child: Text("profile"),
      ),
    );
  }
}

lib/presentation/screens/profile/profile_screen.dart

it should look somewhat like

looking great! we should use it for both the home and memories screens too. using it everywhere allows us to change the styles of the app navigation bar from one place.

That is it! great job. we will continue working on the app on the next articles so stay tuned
PS. To avoid repeating some ideas, and since I'm building on the same skeletal project, I might jump over some details, please don't hesitate to ask if you found any issues implementing this tutorial for your app.

as always...
Stay tuned 😎

Flutter app, Generic blocs for loading and listing

Saad Alkentar — Mon, 20 Jan 2025 11:17:02 +0000

What to expect from this tutorial?

The idea is to create generic reusable blocs, mainly for these two functionalities

loading indicator
messaging user, toasts
list loading, refreshing and pagination

usually, we create a loading indicator for each page alone, like hiding the login button and showing loading indicator in its place, for messaging, we usually listen for certain bloc states, and show their messages, it is also arranged separately for each screen.
instead of repeating this code in every screen, we will build a single bloc that handles those functionalities

Loading bloc

The idea is to build a loader on top of the main screen, this loader overlay the main screen preventing user from playing around while loading. We are also planing to pass messages to this bloc for showing, let's being with the events

part of 'loading_bloc.dart';

@immutable
sealed class LoadingEvent {
  final String? text;

  const LoadingEvent({this.text});
}

class LoadingStartEvent extends LoadingEvent {}
class LoadingStopEvent extends LoadingEvent {}
class LoadingMessageEvent extends LoadingEvent {
  const LoadingMessageEvent({super.text});
}

lib/presentation/blocs/loading/loading_event.dart

so we have an event to start loading, another one to stop loading of course and a final one to show messages, I guess it is enough for this bloc, you can add more events if necessary.
moving to the states file, it should reflect events file I guess

part of 'loading_bloc.dart';

@immutable
sealed class LoadingState {
  final String? text;

  const LoadingState({this.text});
}

final class LoadingInitial extends LoadingState {}

final class LoadingProgressState extends LoadingState {}
final class LoadingIdleState extends LoadingState {}
final class LoadingMessageState extends LoadingState {
  const LoadingMessageState({super.text});
}

lib/presentation/blocs/loading/loading_state.dart

similar to the events file, now for the bloc file, it is straightforward, when we get a certain event, we emit its state

import 'dart:async';
import 'dart:io';

import 'package:bloc/bloc.dart';
import 'package:meta/meta.dart';

part 'loading_event.dart';
part 'loading_state.dart';

class LoadingBloc extends Bloc<LoadingEvent, LoadingState> {


  LoadingBloc() : super(LoadingInitial()) {

    on<LoadingStartEvent>(handleStartEvent);
    on<LoadingStopEvent>(handleStopEvent);
    on<LoadingMessageEvent>(handleMessageEvent);
  }

  FutureOr<void> handleStartEvent(
      LoadingStartEvent event,
      Emitter<LoadingState> emit,
  ) async {
    emit(LoadingProgressState());
  }

  FutureOr<void> handleStopEvent(
      LoadingStopEvent event,
      Emitter<LoadingState> emit,
  ) {
    emit(LoadingIdleState());
  }

  FutureOr<void> handleMessageEvent(
      LoadingMessageEvent event,
      Emitter<LoadingState> emit,
  ) {
    emit(LoadingMessageState(text: event.text));
  }
}

lib/presentation/blocs/loading/loading_bloc.dart

it cannot be simpler I guess 😅, the trick is in the implementation, we need to implement the loading indicator on top of all screens, so let's edit the main app file in order to do that (we are building upon the last main.dart file from previous tutorials, but you can tune this to your needs 😉)

import 'presentation/blocs/loading/loading_bloc.dart';
import 'package:flutter/cupertino.dart';

...

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  // This widget is the root of your application.
  @override
  Widget build(BuildContext context) {

    final loadingBloc = LoadingBloc();

    return MaterialApp(
      title: 'Flutter Demo',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: Colors.deepPurple),
        useMaterial3: true,
      ),
      debugShowCheckedModeBanner: false,
      home: MultiBlocProvider(
        providers: [
          BlocProvider(create: (context)=>loadingBloc),
          BlocProvider(create: (context)=>HomeBloc(locator(), locator())),
          BlocProvider(create: (context)=>LoginBloc(locator(), locator())),
        ],
        child: OKToast(
          position: ToastPosition.bottom,
          child: Stack(
            children: [
              MaterialApp.router(
                supportedLocales: context.supportedLocales,
                localizationsDelegates: context.localizationDelegates,
                locale: context.locale,
                routerConfig: appRouter.config(),
              ),


              BlocConsumer<LoadingBloc, LoadingState>(
                listener: (context, state) {
                  if (state is LoadingMessageState) {
                    showToast(state.text ?? "Unexpected error");
                  }
                },
                builder: (context, state) {
                  return (state is LoadingProgressState) ?
                  Container(
                    alignment: Alignment.center,
                    color: Colors.lightBlueAccent.withOpacity(0.1),
                    child: const CupertinoActivityIndicator(),
                  ) :
                  Container();
                },
              ),

            ],
          ),
        ),
      ),
    );
  }
}

lib/main.dart

We are creating the loading bloc, well... it is not a good idea to create it in the build function, so we should move it to the DI later.
In order to show the loader over the main screen, we are putting it in the top of a stack, and to show messages, we are listening for the message state.
the build function can be called multiple times, to avoid creating the loading bloc multiple times, let's move it to the DI config file

import '../presentation/blocs/loading/loading_bloc.dart';

final locator = GetIt.instance;

Future<void> initializeDependencies() async {

  locator.registerSingleton<LoadingBloc>(LoadingBloc());
...

we can remove the creation code from the build function and use the DI object instead

...
- final loadingBloc = LoadingBloc();
...
-           BlocProvider(create: (context)=>loadingBloc),
+           BlocProvider(create: (context)=>locator<LoadingBloc>()),
...

great! let's test it on the login screen bloc, instead of showing the indicator on the login button we will use loadingBloc, so in the login bloc

import 'dart:async';

import 'package:alive_diary_app/domain/repositories/preferences_repository.dart';
import 'package:alive_diary_app/presentation/blocs/loading/loading_bloc.dart';
import 'package:bloc/bloc.dart';
import 'package:meta/meta.dart';

import '../../../domain/repositories/remote_repository.dart';
import '../../../utils/data_state.dart';
import '../../../utils/dio_exception_extension.dart';

part 'login_event.dart';
part 'login_state.dart';

class LoginBloc extends Bloc<LoginEvent, LoginState> {

  final RemoteRepository repository;
  final PreferencesRepository preferencesRepository;
  final LoadingBloc loadingBloc;

  LoginBloc(this.repository, this.preferencesRepository, this.loadingBloc) : super(LoginInitial()) {
    on<LoginPressedEvent>(handleLoginEvent);
  }

  FutureOr<void> handleLoginEvent(
      LoginPressedEvent event,
      Emitter<LoginState> emit,
  ) async {
    // emit(LoginLoadingState());
    loadingBloc.add(LoadingStartEvent());

    final response = await repository.login(
      username: event.username,
      password: event.password,
    );

    if (response is DataSuccess) {
      final tokenModel = response.data?.data;
      preferencesRepository.saveLoginModel(tokenModel);

      emit(LoginSuccessState());
    } else if (response is DataFailed) {
      loadingBloc.add(LoadingMessageEvent(text: response.error?.getErrorMessage()));

      // emit(LoginErrorState(message: response.error?.getErrorMessage()));
    }
    loadingBloc.add(LoadingStopEvent());
  }
}

we are passing the loading bloc to the login bloc, and emitting start loading and stop loading when needed, we are also using the message event to show message instead of using the login bloc for that, we need to add the loading bloc as dependency for the login bloc so in the main app file we need to

-          BlocProvider(create: (context)=>LoginBloc(locator(), locator())),
+          BlocProvider(create: (context)=>LoginBloc(locator(), locator(), locator())),

just added locator as the third parameter, since it is provided by our DI already, and that is it

loading	message

it seems to work well, whenever we need to show the loading indicator or a message to the user, we can always use this loading bloc

Listing bloc

listing is a common functionality in most apps, there is always a screen with list of stuff. The idea is to create a list bloc that can used in any listing screen, let's start with the events

part of 'list_bloc.dart';

@immutable
sealed class ListEvent {
  final int? id;
  final String? query;

  const ListEvent({this.id, this.query});
}

class ListGetEvent extends ListEvent {
  const ListGetEvent({super.query});
}

class ListDeleteEvent extends ListEvent {
  const ListDeleteEvent({super.id});
}
class ListRefreshEvent extends ListEvent {
  const ListRefreshEvent({super.query});

}

lib/presentation/blocs/list/list_event.dart

we are creating three events, one for getting list data, and another one for refreshing the list, and an event to delete item. we are expecting a query string to filter the list, and an id to know which item to delete. nice and easy, now to the states

part of 'list_bloc.dart';

@immutable
sealed class ListState<T> {
  final List<T>? list;
  final String? errorMessage;
  final bool? noMoreData;

  const ListState({this.list, this.errorMessage, this.noMoreData});
}

final class ListInitialState<T> extends ListState<T> {}

final class ListLoadingState<T> extends ListState<T> {
  const ListLoadingState({super.list});
}

final class ListSuccessState<T> extends ListState<T> {
  const ListSuccessState({super.list, super.noMoreData});
}

final class ListErrorState<T> extends ListState<T> {
  const ListErrorState({super.errorMessage});
}

lib/presentation/blocs/list/list_state.dart

We have three states, one to show loading indicator, another one to show an error message, and one for loading data successfully.

Bloc logic is kinda complicated let's walk through it ...

create aliases for get data function and delete item function
pass those functions to the bloc logic
the get data event calls get data function
delete item event calls delete item function

that is it in a glance, we are

import 'dart:async';

import 'package:bloc/bloc.dart';
import 'package:meta/meta.dart';

import '../../../domain/models/responses/generic_response.dart';
import '../../../domain/models/responses/list_response.dart';
import '../../../utils/data_state.dart';
import '../../../utils/dio_exception_extension.dart';

part 'list_event.dart';
part 'list_state.dart';

typedef BuildListFuture<T> = Future<DataState<GenericResponse<ListResponse<T>>>> Function(int page, String? query);
typedef BuildDelFuture<T> = Future<DataState<GenericResponse<T>>> Function(int id);

class ListBloc<T> extends Bloc<ListEvent, ListState<T>> {

  int page= 1;
  List<T> list = [];
  bool noMore = false;
  String? query;

  final BuildListFuture<T>? getRequest;
  final BuildDelFuture<String>? deleteRequest;

  ListBloc({
    this.getRequest,
    this.deleteRequest,
  }) : super(ListInitialState<T>()) {
    on<ListGetEvent>(handleGetEvent);
    on<ListRefreshEvent>(handleRefreshEvent);
    on<ListDeleteEvent>(handleDeleteEvent);
  }

  FutureOr<void> handleGetEvent(
      ListGetEvent event,
      Emitter<ListState<T>> emit,
      ) async {

    if (noMore) return;

    emit(ListLoadingState<T>(list: list));

    final response = await getRequest?.call(page, query);
    if (response is DataSuccess) {
      noMore = response?.data?.data?.next == null;

      list.addAll(response?.data?.data?.results ?? []);
      page ++;

      emit(ListSuccessState<T>(
        list: list,
        noMoreData: noMore,
      ));

    } else if (response is DataFailed) {
      emit(ListErrorState(errorMessage: response?.error?.getErrorMessage()));
    }

  }

  FutureOr<void> handleDeleteEvent(
      ListDeleteEvent event,
      Emitter<ListState<T>> emit,
      ) async {

    emit(ListLoadingState<T>(list: list));

    final response = await deleteRequest?.call(event.id ?? 0);
    if (response is DataSuccess) {

      add(ListRefreshEvent());

    } else if (response is DataFailed) {
      emit(ListErrorState(errorMessage: response?.error?.getErrorMessage()));
    }

  }

  FutureOr<void> handleRefreshEvent(
      ListRefreshEvent event,
      Emitter<ListState<T>> emit,
      ) async {

    page = 1;
    list.clear();
    noMore = false;
    query = event.query;
    add(ListGetEvent(query: event.query));

  }
}

lib/presentation/blocs/list/list_bloc.dart

Notice that we are using our generic list response to our benefit here 😉, since we know all list requests have this certain response schema, we are using this knowledge to find whether this is the last page based on having the field next there. and getting the data list items from the results field. make sure to tune this based on your list response schema.

With the bloc logic ready, let's test it on an actual page 😁

Listing page

with our listing bloc ready, let's create a list widget that can be easily reused

import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:flutter_hooks/flutter_hooks.dart';

class AppListWidget<T> extends HookWidget {
  const AppListWidget({
    super.key,
    this.getPageDate,
    this.onRefresh,
    this.onSearch,
    this.buildItem,
    this.list,
    this.noMoreData = true,
    this.isLoading = false,

  });

  final Function(String)? getPageDate;
  final Function(String)? onRefresh;
  final Function(String)? onSearch;
  final Function(T?)? buildItem;
  final List<T>? list;

  final bool noMoreData;
  final bool isLoading;

  @override
  Widget build(BuildContext context) {

    final scrollController = useScrollController();
    final textController = useTextEditingController();


    useEffect(() {

      scrollController.onScrollEndsListener(() {
        getPageDate?.call(textController.text);
      });
      getPageDate?.call(textController.text);

      return null;
    }, []);

    return RefreshIndicator(
      backgroundColor: Colors.white,
      onRefresh: () async {
        onRefresh?.call(textController.text);
      },
      child: Container(
        child: CustomScrollView(
          physics: const AlwaysScrollableScrollPhysics(),
          controller: scrollController,
          slivers: [
            SliverToBoxAdapter(
              child: onSearch == null ? Container() : Container(
                padding: EdgeInsets.symmetric(horizontal: 20, vertical: 10),
                child: SearchBar(
                  controller: textController,
                  padding: const WidgetStatePropertyAll<EdgeInsets>(
                      EdgeInsets.symmetric(horizontal: 16.0)),
                  onTap: () {

                  },
                  onChanged: (str) {

                    if (str.isEmpty) {
                      onSearch?.call("");
                    } else if (str.length >= 3) {
                      onSearch?.call(str);
                      // getPageDate?.call(str);
                    }
                  },
                  leading: const Icon(Icons.search),
                ),
              ),
            ),

            SliverList(
              delegate: SliverChildBuilderDelegate(
                    (context, index) =>buildItem?.call(list?[index]),
                childCount: list?.length ?? 0,
              ),
            ),
            if (!noMoreData || isLoading)
              const SliverToBoxAdapter(
                child: Padding(
                  padding: EdgeInsets.only(top: 14, bottom: 32),
                  child: CupertinoActivityIndicator(),
                ),
              )
          ],
        ),
      ),
    );
  }
}

extension ScrollControllerExtensions on ScrollController {
  void onScrollEndsListener(
      final void Function() callback, {
        double offset = 0,
      }) {
    addListener(() {
      final maxScroll = position.maxScrollExtent;
      final currentScroll = position.pixels - offset;

      if (currentScroll == maxScroll) {
        callback();
      }
    });
  }
}

lib/presentation/widgets/app_list_widget.dart

This widget support auto loading with scrolling out of the box. it uses custom scroll view with slivers. it also show loading indicator while the data is loading.

great, it is time to finish up the screen design

import 'package:auto_route/auto_route.dart';
import 'package:flutter/material.dart';
import 'package:flutter_bloc/flutter_bloc.dart';
import 'package:flutter_hooks/flutter_hooks.dart';
import 'package:oktoast/oktoast.dart';

import '../../blocs/list/list_bloc.dart';
import '../../widgets/app_list_widget.dart';
import '../../../domain/models/entities/memory_model.dart';

@RoutePage()
class MemoriesScreen extends HookWidget {
  const MemoriesScreen({super.key});

  @override
  Widget build(BuildContext context) {
    final listBloc = BlocProvider.of<ListBloc<MemoryModel>>(context);

    return Scaffold(
      appBar: AppBar(
        backgroundColor: Theme
            .of(context)
            .colorScheme
            .inversePrimary,
        title: Text( "Memories"),
      ),
      body: Container(
        child: BlocConsumer<ListBloc<MemoryModel>, ListState<MemoryModel>>(
          listener: (context, state) {
            if (state is ListErrorState) {
              showToast(state.errorMessage ?? "error");
            }
          },
          builder: (context, state) {
            return AppListWidget<MemoryModel>(
              list: state.list,
              isLoading: state is ListLoadingState,
              getPageDate: (str) => listBloc.add(ListGetEvent()),
              buildItem: (item) => Container(
                alignment: Alignment.center,
                child: Text(item?.title ?? ""),
                height: 150,
              ),
              noMoreData: state.noMoreData ?? true,
              onRefresh: (str) => listBloc.add(ListRefreshEvent()),
            );
          },
        ),
      ),
    );
  }
}

lib/presentation/screens/memories/memories_screen.dart

it uses the AppListWidget with the generic ListBloc, we should change the buildItem to build the actual list item, all the rest can be reused as is in most list screens 🤓.

of course for it to work, we should provide the list bloc in the main app file

...
      home: MultiBlocProvider(
        providers: [
          BlocProvider(create: (context)=>locator<LoadingBloc>()),
          BlocProvider(create: (context)=>HomeBloc(locator(), locator())),
          BlocProvider(create: (context)=>LoginBloc(locator(), locator(), locator())),
          BlocProvider(create: (context) => ListBloc(
              getRequest: (page, query)=>locator<RemoteRepository>().memoriesList(
                page: page,
              ),
              // deleteRequest: (id)=>locator<RemoteRepository>().memoriesDelete(
              //   id: id,
              // )
          )),
        ],
...

lib/main.dart

we are providing the list bloc with the get and delete function (if we need to). we are using the remote repository to get the data. with this setup ready, we should be able to load the memories list in the memories screen

loading	more

That is it! I know it is kinda complicated, so ask me if you need more explanation for the generic list bloc. I believe the code is kinda clear for you all to read and understand. yet, I'm always here

We will continue with the app design on next articles, so

Stay tuned 😎

Forem: Saad Alkentar

KMP Native UI networking with Ktro

What are the app features?

Where to get it from?

Setup Ktor client library

Set up Ktor with Koin

Products Clean Architecture shared module

JSON objects to Kotlin classes

Products repository

Data layer, Products DataSource

Presentation layer, Bloc ViewModel

Dependency Injection for Products repository

Products list in Android (Finally)

Products list in iOS (Finally * 2)

No such module 'Shared' fixed for KMP Xcode

KMP Native UI view model injection for iOS and Android

View model library

A simple shared ViewModel

Inject our ViewModel where needed

View models usage in Android

View models usage in iOS

KMP-NativeCoroutines libraries setup

KMP-NativeCoroutines shared code update

KMP-NativeCoroutines iOS project update

The ViewModel in Swift UI

KMP Native UI Dependency Injection with Koin

Creating a new Project

Koin Implementation Guide for Native UI

Koin Build libs

Koin Project setup

Your Own Email Verification SaaS Server

The Idea

Django project setup

Email verification API

Bonus, error handling

Your Own GeoIP SaaS Server

The Idea

Django project setup

DP-IP datasets

GeoIP implementation testing

GeoIP API

Bonus, User IP 🤓

Setup iOS Account for Production

Create a distribution certificate

Create a profile

Setup the project

Open Finder folder with IntelliJ IDEA, Sublime Text or VSCode

What to expect from this article?

Where to start?

Flutter app, fading chat logic with bloc and hooks

What can you expect from this article?

API calls and models (optional)

Start at the domain layer

Data layer

Chat screen events and states

The events

The States

Bloc logic

Home screen

Flutter App, Simple animation with Hooks 🪝

What to expect from this tutorial?

The idea

Clean home_screen code (optional)

The fun part 😁, the Animation!

Diary app text field behavior

Dismiss the software keyboard in flutter

Text field animation

Flutter app, layout widget and bottom navigation bar with auto-router

What to expect from this tutorial?

The complete picture!

Create navigation screens

Navigation config

Layout widget

Flutter app, Generic blocs for loading and listing

What to expect from this tutorial?

Loading bloc

Listing bloc

Listing page

Clean `home_screen` code (optional)