RoomAndNavigation3

This project is a Kotlin Multiplatform app that shows:

Navigation with Navigation3
Room 3 database for shared CRUD
Android, iOS, Desktop, JS, and Wasm web support
Live UI updates using Flow

The app is a simple notes app:

Screen A shows a form and a notes list
Screen B is a second screen to prove navigation works
You can add, edit, and delete notes
The list updates live
Notes are stored in a local database

Platforms

This project currently supports these Room paths:

Android: Room 3 + BundledSQLiteDriver
iOS: Room 3 + BundledSQLiteDriver
Desktop/JVM: Room 3 + BundledSQLiteDriver
Web JS: Room 3 + sqlite-web + worker
Web Wasm: Room 3 + sqlite-web + worker

Modules

androidApp Android launcher
desktopApp Desktop launcher
shared Shared UI, navigation, Room entities, DAO, repository, screen model, and platform database creation
webApp Web launcher for JS and Wasm
sqliteWasmWorker Worker package used by Room web

Important Versions

These versions are defined in gradle/libs.versions.toml:

Kotlin: 2.4.0
Compose Multiplatform: 1.11.1
Room 3: 3.0.0-alpha06
SQLite web/bundled: 2.7.0-alpha06

File Map

Shared UI and navigation

Shared Room files

Platform database builders

App entry points

Web worker setup

How Data Moves

The flow in this project is:

ScreenA -> NotesScreenModel -> NotesRepository -> NoteDao -> AppDatabase

Then Room emits Flow<List<NoteEntity>> back to the UI.

That is why the list updates by itself when you add, edit, or delete.

Architecture Diagram

flowchart LR
    A["Android MainActivity"] --> UI["App + Navigation3"]
    I["iOS MainViewController"] --> UI
    D["Desktop main.kt"] --> UI
    W["Web main.kt"] --> UI

    UI --> SA["ScreenA"]
    SA --> SM["NotesScreenModel"]
    SM --> REPO["NotesRepository"]
    REPO --> DAO["NoteDao"]
    DAO --> DB["AppDatabase"]

    DB --> AD["Android BundledSQLiteDriver"]
    DB --> ID["iOS BundledSQLiteDriver"]
    DB --> JD["Desktop BundledSQLiteDriver"]
    DB --> WD["WebWorkerSQLiteDriver"]

Step By Step: Build This Project From Zero

This section is written like a recipe.

Step 1: Create the modules

Your root project includes:

include(":androidApp")
include(":desktopApp")
include(":shared")
include(":webApp")
include(":sqliteWasmWorker")

See settings.gradle.kts.

Step 2: Add versions

In gradle/libs.versions.toml, add:

room3 = "3.0.0-alpha06"
sqlite = "2.7.0-alpha06"

And libraries:

room3-runtime = { module = "androidx.room3:room3-runtime", version.ref = "room3" }
room3-compiler = { module = "androidx.room3:room3-compiler", version.ref = "room3" }
sqlite-bundled = { module = "androidx.sqlite:sqlite-bundled", version.ref = "sqlite" }
sqlite-web = { module = "androidx.sqlite:sqlite-web", version.ref = "sqlite" }

Step 3: Add the Room 3 plugin at the root

In build.gradle.kts:

id("androidx.room3") version "3.0.0-alpha06" apply false

Step 4: Configure the shared module

In shared/build.gradle.kts:

apply Kotlin Multiplatform
apply Compose
apply KSP
apply androidx.room3
create targets for Android, iOS, JVM, JS, and Wasm

Important shared dependencies:

commonMain.dependencies {
    api(libs.room3.runtime)
}

androidMain.dependencies {
    implementation(libs.sqlite.bundled)
}

iosMain.dependencies {
    implementation(libs.sqlite.bundled)
}

jvmMain.dependencies {
    implementation(libs.sqlite.bundled)
}

webMain.dependencies {
    implementation(libs.sqlite.web)
    implementation(project(":sqliteWasmWorker"))
}

Important KSP lines:

add("kspAndroid", libs.room3.compiler)
add("kspJvm", libs.room3.compiler)
add("kspIosSimulatorArm64", libs.room3.compiler)
add("kspIosArm64", libs.room3.compiler)
add("kspJs", libs.room3.compiler)
add("kspWasmJs", libs.room3.compiler)

Important schema line:

room3 {
    schemaDirectory(layout.projectDirectory.dir("schemas"))
}

Step 5: Create the entity

File: shared/src/commonMain/kotlin/org/roomnav/project/RoomSetup/NoteEntity.kt

@Entity
data class NoteEntity(
    @PrimaryKey(autoGenerate = true)
    val id: Long = 0,
    val title: String,
    val description: String,
    val updatedAt: Long = System.now().toEpochMilliseconds()
)

This is one note row in the database table.

Step 6: Create the DAO

File: shared/src/commonMain/kotlin/org/roomnav/project/RoomSetup/NoteDao.kt

@Dao
interface NoteDao {
    @Query("SELECT * FROM NoteEntity ORDER BY updatedAt DESC")
    fun observeAllNotes(): Flow<List<NoteEntity>>

    @Insert
    suspend fun insertNote(note: NoteEntity): Long

    @Update
    suspend fun updateNote(note: NoteEntity)

    @Query("DELETE FROM NoteEntity WHERE id = :id")
    suspend fun deleteById(id: Long)
}

This file says how to:

read all notes
insert one note
update one note
delete one note

Step 7: Create the database

File: shared/src/commonMain/kotlin/org/roomnav/project/RoomSetup/AppDatabase.kt

@Database(entities = [NoteEntity::class], version = 1)
@ConstructedBy(AppDatabaseConstructor::class)
abstract class AppDatabase : RoomDatabase() {
    abstract fun noteDao(): NoteDao
}

@Suppress("KotlinNoActualForExpect")
expect object AppDatabaseConstructor : RoomDatabaseConstructor<AppDatabase> {
    override fun initialize(): AppDatabase
}

This is the main Room database.

Step 8: Create the repository

File: shared/src/commonMain/kotlin/org/roomnav/project/RoomSetup/NotesRepository.kt

The repository is a clean middle layer between UI and DAO.

It calls:

dao.observeAllNotes()
dao.insertNote(...)
dao.updateNote(...)
dao.deleteById(...)

Step 9: Create the screen model

File: shared/src/commonMain/kotlin/org/roomnav/NotesScreenModel.kt

This class:

holds a CoroutineScope
turns the DAO flow into a StateFlow
exposes add, update, and delete

This is why the UI can do:

val notes by model.notes.collectAsState()

Step 10: Create navigation

Navigation files:

The screen keys are:

sealed interface ScreenNavigation {
    data object ScreenA : ScreenNavigation
    data object ScreenB : ScreenNavigation
}

The app uses:

NavDisplay(backStack = backStack, entryProvider = entryProvider { ... })

That means:

backStack stores the current screen history
entry<ScreenNavigation.ScreenA> { ... } draws Screen A
entry<ScreenNavigation.ScreenB> { ... } draws Screen B

Step 11: Create Screen A

File: shared/src/commonMain/kotlin/org/roomnav/project/ScreenA.kt

This file does all of this:

shows title and description inputs
shows Add or Save
shows Clear
shows a note list
lets you edit a note
lets you delete a note
lets you go to Screen B

The most important UI lines are:

val notes by model.notes.collectAsState()

and:

if (id == null) model.add(title, description)
else model.update(id, title, description)

Step 12: Create Screen B

File: shared/src/commonMain/kotlin/org/roomnav/project/ScreenB.kt

This is just a simple second screen to prove navigation works.

Step 13: Create the database builder for Android

File: shared/src/androidMain/kotlin/org/roomnav/project/CreateDatabase.kt

It uses:

Room.databaseBuilder<AppDatabase>(
    context = context.applicationContext,
    name = dbFile.absolutePath,
)
    .setDriver(BundledSQLiteDriver())
    .build()

Step 14: Create the database builder for Desktop

File: shared/src/jvmMain/kotlin/org/roomnav/project/CreateDatabase.kt

Desktop stores the DB in:

File(System.getProperty("user.home"), "navnotes.db")

Step 15: Create the database builder for iOS

File: shared/src/iosMain/kotlin/org/roomnav/project/CreateDatabase.kt

iOS stores the DB in the documents directory.

Step 16: Create the database builder for web

File: shared/src/webMain/kotlin/org/roomnav/project/CreateDatabase.kt

fun createDatabase(): AppDatabase {
    return Room.databaseBuilder<AppDatabase>("navnotes.db")
        .setDriver(createWebWorkerDriver())
        .setSingleConnectionPool()
        .build()
}

Important:

web uses sqlite-web
web needs a worker
web uses a single connection pool

Step 17: Create JS and Wasm web worker drivers

Files:

This split is needed because:

webMain declares expect fun createWebWorkerDriver()
jsMain gives the JS actual
wasmJsMain gives the Wasm actual

Step 18: Create the worker module

Files:

The worker module pulls in:

npm("sqlite-wasm-worker", layout.projectDirectory.dir("worker").asFile)

The worker.js file:

opens a DB
prepares statements
executes steps
closes statements and DBs

It also has a safe fallback:

sqlite3.oo1?.OpfsDb
    ? new sqlite3.oo1.OpfsDb(requestData.fileName)
    : new sqlite3.oo1.DB(requestData.fileName, 'ct');

That means:

if OPFS persistence is available, use it
if not, still open a working DB instead of crashing

Step 19: Create the web app module

File: webApp/build.gradle.kts

This module:

creates js browser executable
creates wasmJs browser executable
depends on shared
depends on sqliteWasmWorker

It also contains the Wasm npm sync workaround so Wasm webpack can see the worker package:

syncSqliteWorkerForWasm
syncSqliteRuntimeForWasm

Step 20: Add webpack headers for Wasm OPFS

File: webApp/webpack.config.d/devserver-headers.js

config.devServer.headers = {
  ...(config.devServer.headers || {}),
  "Cross-Origin-Opener-Policy": "same-origin",
  "Cross-Origin-Embedder-Policy": "require-corp",
};

These headers matter for web persistence support.

Step 21: Add web HTML and CSS

Files:

Very important line:

<script src="webApp.js"></script>

Without that line, the browser only shows a white screen because the app never starts.

Step 22: Create platform entry points

Android

File: androidApp/src/main/kotlin/org/roomnav/project/MainActivity.kt

Flow:

val db = createDatabase(this)
val repo = NotesRepository(db.noteDao())
val model = NotesScreenModel(repo)
setContent { App(model) }

Desktop

File: desktopApp/src/main/kotlin/org/roomnav/project/main.kt

Flow:

val db = createDatabase()
val repo = NotesRepository(db.noteDao())
val model = NotesScreenModel(repo)
Window { App(model) }

iOS

File: shared/src/iosMain/kotlin/org/roomnav/project/MainViewController.kt

Flow:

val db = createDatabase()
val repo = NotesRepository(db.noteDao())
val model = NotesScreenModel(repo)
App(model)

Web

File: webApp/src/webMain/kotlin/org/roomnav/project/main.kt

Flow:

ComposeViewport {
    val db = remember { createDatabase() }
    val repo = remember { NotesRepository(db.noteDao()) }
    val model = remember { NotesScreenModel(repo) }
    App(model)
}

Run The Project

Android Studio

Open the root folder: RoomAndNavigation3
Wait for Gradle sync to finish.
If Android Studio asks for a JDK, use JDK 17.
Select the androidApp run configuration. If it is missing, open MainActivity.kt and run it from the gutter.
Start an emulator or connect a real Android device.
Press Run.

Xcode

Open iosApp/iosApp.xcodeproj.
Select the iosApp scheme.
Pick an iPhone simulator such as iPhone 16.
Press Run.
The Xcode build phase will call ./gradlew :shared:embedAndSignAppleFrameworkForXcode for you.
If the first launch fails because the Kotlin framework is not ready yet, run:

./gradlew :shared:compileKotlinIosSimulatorArm64

and then press Run again in Xcode.

Web JS

Development:

./gradlew :webApp:jsBrowserDevelopmentRun

Production bundle:

./gradlew :webApp:jsBrowserDistribution

Web Wasm

Development:

./gradlew :webApp:wasmJsBrowserDevelopmentRun

Production bundle:

./gradlew :webApp:wasmJsBrowserDistribution

Compile checks

./gradlew :shared:compileKotlinJs :shared:compileKotlinWasmJs :webApp:compileKotlinJs :webApp:compileKotlinWasmJs

Android

Open in Android Studio and run the androidApp configuration.

Desktop

Run the desktop entry:

./gradlew :desktopApp:run

iOS From Terminal

If you only want to confirm the shared iOS code compiles:

./gradlew :shared:compileKotlinIosSimulatorArm64

What You Should See

When everything is working:

App starts on Screen A
You type a title and description
Press Add
Note appears in the list
Press Edit to load note into the form
Press Save to update it
Press Delete to remove it
Press Go to Screen B
Press Go to Screen A
Notes remain because they are stored in Room

Simple Mental Model

If you want to explain this project to a child, say it like this:

NoteEntity is one note
NoteDao knows how to save and read notes
AppDatabase is the notes box
NotesRepository is the helper who talks to the box
NotesScreenModel is the brain for the screen
ScreenA is what the user sees
App.kt decides which screen to show
each platform creates the same app with its own database path

Notes About Web

JS and Wasm both run
Wasm needed extra setup
web uses a worker
the custom HTML must include webApp.js
dev server headers help the browser allow OPFS features
if OPFS is not available, the worker fallback keeps the app alive

Common Mistakes And Fixes

1. `Plugin [id: 'androidx.room3'] was not found`

Add the plugin at the root in build.gradle.kts:

id("androidx.room3") version "3.0.0-alpha06" apply false

Then apply it in shared/build.gradle.kts:

id("androidx.room3")

2. `The Room Gradle plugin was applied but no schema location was specified`

Add this in shared/build.gradle.kts:

room3 {
    schemaDirectory(layout.projectDirectory.dir("schemas"))
}

3. `Argument type mismatch ... Action<KspExtension> was expected`

Do not write ksp("...") like a dependency string in Kotlin DSL configuration blocks. Use normal dependencies or KSP target lines like these in shared/build.gradle.kts:

add("kspAndroid", libs.room3.compiler)
add("kspJvm", libs.room3.compiler)
add("kspIosSimulatorArm64", libs.room3.compiler)
add("kspIosArm64", libs.room3.compiler)
add("kspJs", libs.room3.compiler)
add("kspWasmJs", libs.room3.compiler)

4. `Cannot access 'androidx.room3.RoomDatabase'`

This usually means the module using AppDatabase does not have the Room 3 runtime on its classpath through shared. Make sure shared/build.gradle.kts has:

commonMain.dependencies {
    api(libs.room3.runtime)
}

5. `createDatabase()` is not found in web code

Put the shared web database builder in:

shared/src/webMain/kotlin/org/roomnav/project/CreateDatabase.kt

and call it from:

webApp/src/webMain/kotlin/org/roomnav/project/main.kt

The package name must match.

6. `Expected class WebWorkerSQLiteDriver does not have default constructor`

Do not instantiate the web driver in webMain. Keep only:

expect fun createWebWorkerDriver(): SQLiteDriver

in shared/src/webMain/kotlin/org/roomnav/project/WebWorkerDriver.kt, then create the actual driver separately in:

7. `Module not found: Can't resolve 'sqlite-web-worker/worker.js'`

The worker package must be available to the web bundle. Keep:

and keep the Wasm sync tasks in webApp so webpack can see the worker package.

8. Web app builds but shows a white screen

Check these three things:

webApp/src/webMain/resources/index.html must include:

<script src="webApp.js"></script>

webApp/webpack.config.d/devserver-headers.js must set:

"Cross-Origin-Opener-Policy": "same-origin",
"Cross-Origin-Embedder-Policy": "require-corp",

The worker fallback in sqliteWasmWorker/worker/worker.js should still handle browsers that do not expose OpfsDb.

If You Want To Extend This Project

Easy next steps:

add search
add note timestamps to the UI
add note details screen
add validation messages
split UI into smaller composables
add tests for DAO and repository

Name		Name	Last commit message	Last commit date
androidApp		androidApp
desktopApp		desktopApp
gradle		gradle
iosApp		iosApp
shared		shared
sqliteWasmWorker		sqliteWasmWorker
webApp		webApp
.gitignore		.gitignore
README.md		README.md
build.gradle.kts		build.gradle.kts
gradle.properties		gradle.properties
settings.gradle.kts		settings.gradle.kts

Latest commit

History

Folders and files

Repository files navigation

RoomAndNavigation3

Platforms

Modules

Important Versions

File Map

Shared UI and navigation

Shared Room files

Platform database builders

App entry points

Web worker setup

How Data Moves

Architecture Diagram

Step By Step: Build This Project From Zero

Step 1: Create the modules

Step 2: Add versions

Step 3: Add the Room 3 plugin at the root

Step 4: Configure the shared module

Step 5: Create the entity

Step 6: Create the DAO

Step 7: Create the database

Step 8: Create the repository

Step 9: Create the screen model

Step 10: Create navigation

Step 11: Create Screen A

Step 12: Create Screen B

Step 13: Create the database builder for Android

Step 14: Create the database builder for Desktop

Step 15: Create the database builder for iOS

Step 16: Create the database builder for web

Step 17: Create JS and Wasm web worker drivers

Step 18: Create the worker module

Step 19: Create the web app module

Step 20: Add webpack headers for Wasm OPFS

Step 21: Add web HTML and CSS

Step 22: Create platform entry points

Android

Desktop

iOS

Web

Run The Project

Android Studio

Xcode

Web JS

Web Wasm

Compile checks

Android

Desktop

iOS From Terminal

What You Should See

Simple Mental Model

Notes About Web

Common Mistakes And Fixes

1. Plugin [id: 'androidx.room3'] was not found

2. The Room Gradle plugin was applied but no schema location was specified

3. Argument type mismatch ... Action<KspExtension> was expected

4. Cannot access 'androidx.room3.RoomDatabase'

5. createDatabase() is not found in web code

6. Expected class WebWorkerSQLiteDriver does not have default constructor

7. Module not found: Can't resolve 'sqlite-web-worker/worker.js'

8. Web app builds but shows a white screen

If You Want To Extend This Project

About

Topics

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages

1. `Plugin [id: 'androidx.room3'] was not found`

2. `The Room Gradle plugin was applied but no schema location was specified`

3. `Argument type mismatch ... Action<KspExtension> was expected`

4. `Cannot access 'androidx.room3.RoomDatabase'`

5. `createDatabase()` is not found in web code

6. `Expected class WebWorkerSQLiteDriver does not have default constructor`

7. `Module not found: Can't resolve 'sqlite-web-worker/worker.js'`