Enables direct integration with Firebase across multiple platforms, utilizing coroutines and serialization. Supports various Firebase services with Kotlin-first design, offering asynchronous operations and polymorphic serialization.
The following libraries are available for the various Firebase products.
Is the Firebase library or API you need missing? Create an issue to request additional API coverage or be awesome and submit a PR
Unlike the Kotlin Extensions for the Firebase Android SDK this project does not extend a Java based SDK so we get the full power of Kotlin including coroutines and serialization!
Asynchronous operations that return a single or no value are represented by suspending functions in the SDK instead of callbacks, listeners or OS specific types such as Task, for example:
suspend fun signInWithCustomToken(token: String): AuthResult
It is important to remember that unlike a callback based API, waiting for suspending functions to complete is implicit and so if you don't want to wait for the result you can launch a new coroutine:
//TODO don't use GlobalScope
GlobalScope.launch {
Firebase.auth.signOut()
}
Asynchronous streams of values are represented by Flows in the SDK instead of repeatedly invoked callbacks or listeners, for example:
val snapshots: Flow<DocumentSnapshot>
The flows are cold, which means a new listener is added every time a terminal operator is applied to the resulting flow. A buffer with the default size is used to buffer values received from the listener, use the buffer operator on the flow to specify a user-defined value and to control what happens when data is produced faster than consumed, i.e. to control the back-pressure behavior. Often you are only interested in the latest value received, in this case you can use the operator to disable buffering.
The listener is removed once the flow completes or is cancelled.
The official Firebase SDKs use different platform-specific ways to support writing data with and without custom classes in Cloud Firestore, Realtime Database and Functions.
The Firebase Kotlin SDK uses Kotlin serialization to read and write custom classes to Firebase. To use Kotlin serialization in your project add the plugin to your gradle file:
plugins {
kotlin("multiplatform") version "1.9.20" // or kotlin("jvm") or any other kotlin plugin
kotlin("plugin.serialization") version "1.9.20"
}
Then mark your custom classes @Serializable:
@Serializable
data class City(val name: String)
Instances of these classes can now be passed along with their serializer to the SDK:
db.collection("cities").document("LA").set(City.serializer(), city) { encodeDefaults = true }
The buildSettings closure is optional and allows for configuring serialization behaviour.
Setting the encodeDefaults parameter is optional and defaults to true, set this to false to omit writing optional properties if they are equal to theirs default values.
Using @EncodeDefault on properties is a recommended way to locally override the behavior set with encodeDefaults.
You can also omit the serializer if it can be inferred using serializer<KType>().
To support contextual serialization or open polymorphism the serializersModule can be overridden in the buildSettings closure:
Firestore and the Realtime Database provide a sentinel value you can use to set a field in your document to a server timestamp. So you can use these values in custom classes:
@Serializable
data class Post(
// In case using Realtime Database.
val timestamp = ServerValue.TIMESTAMP,
// In case using Cloud Firestore.
val timestamp: Timestamp = Timestamp.ServerTimestamp,
// or
val alternativeTimestamp = FieldValue.serverTimestamp,
// or
@Serializable(with = DoubleAsTimestampSerializer::class),
val doubleTimestamp: Double = DoubleAsTimestampSerializer.serverTimestamp
)
In addition firebase-firestore provides [GeoPoint] and [DocumentReference] classes which allow persisting
geo points and document references in a native way:
@Serializable
data class PointOfInterest(
val reference: DocumentReference,
val location: GeoPoint
)
val document = PointOfInterest(
reference = Firebase.firestore.collection("foo").document("bar"),
location = GeoPoint(51.939, 4.506)
)
This sdk will handle polymorphic serialization automatically if you have a sealed class and its children marked as Serializable. It will include a type property that will be used to discriminate which child class is the serialized.
You can change this type property by using the @FirebaseClassDiscrminator annotation in the parent sealed class:
@Serializable
@FirebaseClassDiscriminator("class")
sealed class Parent {
@Serializable
@SerialName("child")
data class Child(
val property: Boolean
) : Parent
}
In combination with a SerialName specified for the child class, you have full control over the serialized data. In this case it will be:
{
"class": "child",
"property": true
}
documentRef.updateFields {
// Root level encode settings
encodeDefaults = false
serializersModule = module
"field" to "value"
// Set the value of otherField to "1" using a custom Serializer
"otherField".to(IntAsStringSerializer(), 1)
// Overwrite build settings. All fields added within this block will have these build settings applied
withEncodeSettings {
encodeDefaults = true
serializersModule = otherModule
"city" to abstractCity
}
}
Similarly, the Query methods startAt/startAfter/endAt/endBefore have an alternative method in startAtFieldValues/startAfterFieldValues//
query.orderBy("field", "otherField", "city").startAtFieldValues { // similar syntax for startAfter/endAt/endBefore
// Root level encode settings
encodeDefaults = false
serializersModule = module
add("Value")
// Starts at "1" for the otherField value
add(1, IntAsStringSerializer())
// Overwrite build settings. All field values added within this block will have these build settings applied
withEncodeSettings {
encodeDefaults = true
serializersModule = otherModule
add(abstractCity)
}
}
To reduce boilerplate, default arguments are used in the places where the Firebase Android SDK employs the builder pattern:
UserProfileChangeRequest profileUpdates = new UserProfileChangeRequest.Builder()
.setDisplayName("Jane Q. User")
.setPhotoUri(Uri.parse("https://example.com/jane-q-user/profile.jpg"))
.build()
user.updateProfile(profileUpdates)
.addOnCompleteListener(new OnCompleteListener<Void>() {
@Override
public void onComplete(@NonNull Task<Void> task) {
if (task.isSuccessful()) {
Log.d(TAG, "User profile updated.")
}
}
})
//...becomes...
user.updateProfile(displayName = , photoURL = )
To improve readability and reduce boilerplate for functions such as the Cloud Firestore query operators are built with infix notation:
In cases where it makes sense, such as Firebase Functions HTTPS Callable, operator overloading is used:
val addMessage = functions.getHttpsCallable("addMessage")
//In the official android Firebase SDK this would be addMessage.call(...)
addMessage(mapOf("text" to text, "push" to true))
The Firebase Kotlin SDK provides a common API to access Firebase for projects targeting iOS, Android, JVM and JS meaning you can use Firebase directly in your common code. Under the hood, the SDK achieves this by binding to the respective official Firebase SDK for each supported platform.
It uses the Firebase Java SDK to support the JVM target. The library requires additional initialization compared to the official Firebase SDKs.
In some cases you might want to access the underlying official Firebase SDK in platform specific code, for example when the common API is missing the functionality you need. For this purpose each class in the SDK has android, ios and js extension properties that hold the equivalent object of the underlying official Firebase SDK. For JVM, as the firebase-java-sdk is a direct port of the Firebase Android SDK, is it also accessed via the android property.
These properties are only accessible from the equivalent target's source set. For example to disable persistence in Cloud Firestore on Android you can write the following in your Android specific code (e.g. androidMain or androidTest):
Firebase.firestore.android.firestoreSettings = FirebaseFirestoreSettings.Builder(Firebase.firestore.android.firestoreSettings)
.setPersistenceEnabled(false)
.build()
On android, some modules (config) require you to enable Core library desugaring if you have a minSDK lower than API 26.
On iOS the official Firebase iOS SDK in not linked as a transitive dependency. Therefore, any project using this SDK needs to link the actual Firestore SDK as well. This can be done through your preferred installation method (Cocoapods/SPM).
Similarly, tests require linking as well. Make sure to add the required frameworks to the search path of your test targets. This can be done by specifying a cocoapods block in your build.gradle:
cocoapods {
pod("FirebaseCore") // Repeat for Firebase pods required by your project, e.g FirebaseFirestore for the `firebase-firestore` module.
}
If you'd like to contribute to this project then you can fork this repository. You can build and test the project locally.
sudo gem install -n /usr/local/bin cocoapodspublishToMavenLocalTo run the tests you can use the following gradle tasks:
./gradlew connectedAndroidTest (an emulator needs to be running)
./gradlew iosSimulatorArm64Test (On Apple Chip) ./gradlew iosX64Test (On Intel Chip)
./gradlew jsNodeTest
./gradlew jvmTest
For some tests you need to have the firebase emulator suite running. After installing them you can run the following command inside the test directory:
firebase emulators:start
For every publicly available class or function there needs to be documentation written in the KDoc syntax.
To ensure changes to the public API are well documented, this library validates its binary API. If you make changes to the API, make sure to run
./gradlew apiDump
This library uses the Intellij Kotlin code style. Run the linter to make sure you follow these styles.
./gradlew formatKotlin to format to the proper style
./gradlew lintKotlin to validate the correct style is used
When this project began, the official Firebase Android SDK was a pure java library and the separate Kotlin extensions (KTX) module consisted of only a few extensions providing some syntactic sugar, for example Firebase.firestore instead of Firebase.getInstance(), which we naturally copied for the Firebase Kotlin SDK.
But with the majority of the Android SDK being designed for Java, the Kotlin SDK was primarily guided by Kotlin-first design principles.
More recently, with the official SDK for Android providing better support for Kotlin and the inclusion of the new Kotlin-friendly features direct in the main modules, the API differences between the official SDK and this project are likely to start to blur. Therefore, in particular for developers porting android code to multiplatform, one of the project goals going forward will be API compatibility with the Android SDK where possible.
For contributors this means following these points when adding new code to the public API of this project:
And finally, please remember that this is an open source project, all the project maintainers are volunteers, they are not paid to maintain this project, and they have their own jobs, so please be patient when waiting for a response to your issue or PR. Any form of abuse or harassment will not be tolerated and will result in being reported to GitHub.
| Service or Product | Gradle Dependency | API Coverage |
|---|
conflate
abstract class AbstractCity {
abstract val name: String
}
data class Capital(override val name: String, val isSeatOfGovernment: Boolean) : AbstractCity()
val module = SerializersModule {
polymorphic(AbstractCity::class, AbstractCity.serializer()) {
subclass(Capital::class, Capital.serializer())
}
}
val city = Capital("London", true)
db.collection("cities").document("UK").set(AbstractCity.serializer(), city) {
encodeDefaults = true
serializersModule = module
}
val storedCity = db.collection("cities").document("UK").get().data(AbstractCity.serializer()) {
serializersModule = module
}
endAtFieldValuesendBeforeFieldValuescitiesRef.whereEqualTo("state", "CA")
citiesRef.whereArrayContains("regions", "west_coast")
citiesRef.where(Filter.and(
Filter.equalTo("state", "CA"),
Filter.or(
Filter.equalTo("capital", true),
Filter.greaterThanOrEqualTo("population", 1000000)
)
))
//...becomes...
citiesRef.where { "state" equalTo "CA" }
citiesRef.where { "regions" contains "west_coast" }
citiesRef.where {
all(
"state" equalTo "CA",
any(
"capital" equalTo true,
"population" greaterThanOrEqualTo 1000000
)
)
}
com.google to dev.gitlive.Surfaced from shared tags and platforms — no rankings paid for.