Introduction

Well, you made it! This is the documentation in book form for the firebase-js (and firebase-js-sys) packages, freely available on crates.io

Versioning

These packages are still very much in development, esspecially the high-level firebase-js, however they do work. There will be breaking changes, obviously proceed with due caution and I suggest git cloneing for maximum flexibility.

It is likely these crates will never be promoted to 1.0.0 by myself, so contributions are welcome! I will try my best to review and merge any PRs as well as triarge and resolve GH issues that pop up.

These packages will try to follow SemVer as best as possible, but during the 0.x versions breaking changes will occur during minor releases.

The problem

Imagine you want to build a website (and/or integrate a custom backend), using the firebase provided by Google. You have many options:

  • Plain JavaScript with the firebase npm package / SDK
  • Flutter / Dart with flutterfire package
  • JavaScript frameworks, integration the firebase JS SDK

However, all of the above solutions use languages that are sub-optimal.

In dart, for example, you cannot establish type-safe JavaScript interop. Period. The interop does exist, but for your own custom purposes it requires you authoring (and probably publishing) a Flutter plugin. Then, the types are validated at runtime only, since dart typing is like that, and compiling with optimizations has the potential for the wrong types to 'leak' through your code base.

'Well,' you might respond, 'what about the other JS solutions? They seem pretty standard, being the only solution for many decades.' I would resopnd with the argument, 'Can't we do better?' If you have dealt with npm and large interrelated JS projects before, you have often come up against an error like undefined is not a function. Tracking this errors is relatively time consuming compared with tracking Rust errors, for a few major reasons:

  • Rust is compiled and knows everything about your project (not necessarily guarenteed with other compiled languages)
  • JavaScript errors primarily happen at runtime (I often encounter SyntaxErrors at runtime, when dynamic programming like eval or appending script tags to the DOM are involved)
  • Meta programming is hard to trace errors through in edge cases, which Rust solves quite practically with its implementations of macros.

'Well, how can you use firebase in a stable and debuggable manner?' My answer is: Rust

Package relationships

firebase-js depends on:

  • firebase-js-wrappers for type wrappers
  • firebase-js-sys for the actual bindings IF feature flag sys is enabled

firebase-js-sys depends on:

  • firebase-js-wrappers for type wrappers
  • wasm-bindgen, js-sys e.t.c. for the actual bindings
  • Bunch of hand-written js code and the npm package firebase

firebase-js-wrappers depends on: Nothing important.

Firebase JS sys

This crate provides a low-level wrapper around the Firebase JS SDK, the useful functions and types are #[wasm_bindgen]ed into Rust, keeping JS semantics.

This package intends to be a solid foundation for building onto of, with extensive tests and common known errors mapped into Rust.

Contributions welcome!

Aim

To provide the very first 'glue' between Rust and JS for firebase. Any errors emenating from this library should be soley from the JavaScript world, caused by an incorrect value being passed into a rust function that should be interpretted as a JS function.

This library is definitely not practical to use, is is designed to provide a stable base to build other libraries on top of, notably firebase-js.

Firebase Types

Implementation agnostic types for 'native' firebase types in Rust. These types try to reflect the types you would use in the official firebase SDKs.

Installation

Cargo

Install using cargo like:

cargo add firebase-types

By default, this package ships with features serde but not expose-jsvalue. I (the author) am using this package to implement firebase-js, interopping with JS, which is the reason for the expose-jsvalue. You can obviously disable serde if you so desire:

cargo add firebase-types --no-default-features

git

Clone the repo like so:

git clone https://github.com/ActuallyHappening/rust-firebase-js/

Then, you can establish a local dependency for more fine-grained control:

[dependancies.firebase-types]
path = "../path/to/repo/firebase-types"
version = "X.Y.Z" # Optional for publishing, relies on `crates.io` version instead of local

Firebase JS