firestorable

Mobx observable wrapper for firebase firestore database.

Usage no npm install needed!

<script type="module">
  import firestorable from 'https://cdn.skypack.dev/firestorable';
</script>

README

Firestorable

A strong typed observable wrapper using mobx for firebase firestore database.

Cloud Build Coverage Status

Installation

npm install firestorable

Firestorable - example applications

There is a separate github repo with example applications to demonstrate how to use firestorable with react and mobx.

example applications

How to use: basic example

Create an instance of a firestorable collection:

const db = firebase.firestore();

// create a type or interface that matches the data in the firestore collection
interface IRegistration {
    time: number;
    description: string;
}

// use the interface as generic type when creating the firestorable collection
const registrationCollection = new Collection<IRegistration>(
  db,
  "registrations", // name of your firestore collection
);

And use that instance in a mobx observable react component:

const RegistrationsList = observer(() =>
      <div className="registrations-list">
        {
            // Each item in the docs property of the create Collection has a strong typed (IRegistration) data property representing the document data from the firestore 'registrations' collection.
            registrationCollection.docs
                .map(doc => <div key={doc.id}>
                    <div>Time: {doc.data.time}</div>
                    <div>Description: {doc.data.description}</div>
                </div>)
        }
      </div>
  );
});

This RegistrationsList component will now rerender whenever changes occur in the 'registrations' collection of your firestore database.

Contributing

These instructions will get you a copy of the project for development and testing purposes.

Prerequisites

node

I assume you already have node with npm installed.

firebase-tools

You need to have firebase-tools installed globally to run the firebase emulator:

npm i -g firebase-tools

java

java is required to run the tests with a firestore emulator.

Install java on linux (debian, ubuntu)

sudo apt-get install openjdk-8-jre

Installing

  1. Clone this repo
git clone https://github.com/thdk/firestorable.git
  1. Step into the new repo directory
cd firestorable
  1. Install dependencies
npm install
  1. Build
npm run build

Testing

Before running the tests, you need to start to firestore emulator:

 npm run emulator

Keep the emulator running in one terminal window and run tests in another terminal:

 npm run test

Note: after running npm run test you can run npm run coverage to view the code coverage of the last ran tests.

Note: By default emulator will use port 8080. If you need to use another port, then you have to set the port number in firebase.json.

To make sure the tests run using the port set in firebase.json, run your tests a below:

firebase emulators:exec --only firestore jest

Above command will start the emulator, run 'jest', and stop the emulator after the tests.

Built With

  • mobx - Simple, scalable state management
  • typescript - Javascript that scales
  • jest - Javascript testing framework
  • firebase - App development platform
  • npm - Package manager
  • google cloud build - Build, test, and deploy on googles serverless CI/CD platform

Authors

  • Thomas Dekiere - Initial work - thdk

License

This project is licensed under the MIT License - see the LICENSE.txt file for details