heliosrx

heliosRX

heliosRX is a front-end ORM (Object-Relational Mapping) layer for reactive real-time web applications using Firebase Realtime Database and Vue.

• 🍭 Firebase ORM Elegant abstraction layer for Firebase Realtime Database.
• 🍱 Model based state management Declare models with reactive getters and custom actions.
• ♻️ One codebase Generate Frontend API and Backend API from one codebase.
• ⚡ Faster development Significantly reduced development time.

The basic idea behind heliosRX is:

Describe your data structures by providing a schema. Based on that schema heliosRX will generate a client (with automatic client-side validation) and a server ( = security rules).

Documentation

• Full Documentation

When should I use heliosRX?

If you're using Firebase as your backend and if you're building something that is a little bit more complex then just a simple to-do list, then heliosRX is probably very useful for you. Some reasons why you might chose heliosRX over just Firebase Client API are:

• ➡️ You want to develop a SPA with Vue and Firebase
• ➡️ You want object oriented state management
• ➡️ You want to write significantly less code
• ➡️ You want consistent data validation on client and server
• ➡️ You want an additional layer of abstraction and therfore less vendor lock-in
• ➡️ You want automatic type conversion for timestamps

heliosRX will likely support other backends in the future.

You can read more about it in the announcement post.

Install

• Install with npm

npm install --save heliosrx

• Install with yarn

yarn add heliosrx

heliosRX comes with a CLI:

npm install -g heliosrx-cli
# - or -
yarn global add heliosrxc-cli

heliosRX requires bolt-compiler as a peer dependency, so please run:

npm install -g bolt-compiler
# - or -
yarn add -g bolt-compiler

Configuration

Before you can start using heliosRX, you have to configure Firebase and heliosRX. Usually, this should be pretty straight forward. You can read more in the documentation.

Configure Firebase Realtime Database

There is a few ways how you can configure firebase. One way to do it, is to get your Firebase configuration and put it in a new file in src/firebase.js that looks something like this:

// file: src/firebase.js

// Firebase App (the core Firebase SDK) is always required and must be listed first
import * as firebase from "firebase/app";

// Add the Firebase products that you want to use
import "firebase/auth";
import "firebase/database";

// TODO: Replace the following with your app's Firebase project configuration
const firebaseConfig = {
  apiKey:            "<YOUR API KEY>",
  authDomain:        "<YOUR AUTH DOMAIN>",
  databaseURL:       "<YOUR DATABASE URL>",
  projectId:         "<YOUR PROJECT ID>",
  storageBucket:     "<YOUR STORAGE BUCKET>",
  messagingSenderId: "<YOUR MESSAING SENDER ID>",
  appId:             "<YOUR APP ID>"
};

// Initialize Firebase
firebase.initializeApp(firebaseConfig);

// Initialize Realtime DB
export const rtdb = firebase.database(); // < Export a database instance here!

Please feel free to do this in a way that suits your needs best. The important thing here is that we need to import rtdb later on, which is why we're exporting it here.

Create folder structure and configuration files

Next, create the following folder structure:

├── rules               - Used for database access rules
│   └── rules.bolt      - Default access rules
└── src
    └── models          - New models are defined here
        ├── example/*   - Model definition for 'example'
        └── config.js   - Models are assigned to DB paths here
                         (Models we export here, can be accessed through this.$models)

by running

helios init

which will create these files and folders automatically.

Add heliosRX to your main.js

heliosRX can be used as a Vue-Plugin:

import Vue from 'vue'
import heliosRX from 'heliosRX'
import { rtdb } from './firebase' // Import realtime database
import models from '@/models'

Vue.use(heliosRX, {
  userModels:  models, // 'src/models',
  firebaseDb:  rtdb
  devMode:     true,
})

...

new Vue({
  render: h => h(App)
}).$mount('#app');

now models are available as this.$models.

Quickstart

This is an example of a simple To-Do app:

1. Define a Schema

const taskModelDefinition = {
  schema: {
    fields: {
      title:     { type: 'String', required: true },
      createdAt: { type: 'ServerTimestamp' },
      isDone:    { type: 'Boolean' },
    }
  }
};

export const task = new GenericStore( '/user/{userId}/task/*', taskModelDefinition );

2. Use auto-generated API

<template>
  <!-- Example: Simple To-Do App -->
  <ul>
    <li v-for="task in tasks.items" :key="task.$key">
      <input type="checkbox" @input="onCheckTask( task )">
      {{task.title}}
      <a href="#" @click.prevent="onDeleteTask( task )">del</a>
    </li>
    <input v-model="title" />
    <button @click="onAddTask">add</button>
  </ul>
</template>

<script>
export default {
  data() {
    return {
      title: ""
    }
  },
  computed: {
    tasks() {
      return this.$models.task.subscribeList(); // "connect" tasks to realtime database
    }
  },
  methods: {
    onCheckTask( task ) {
      task = task.clone()
      task.isDone = !task.isDone;
      task.write();
      // or: this.$models.task.update( task.$id, { isDone: !task.isDone } )
    },
    onAddTask() {
      this.$models.task.add({
        title: this.title
      });
    },
    onDeleteTask( task ) {
      task.remove();
      // or: this.$models.task.remove( task.$id );
    }
  }
}
</script>

3. Generate Security Rules automatically

> helios rules --write <output-file>

type Task {
  title: String
  createdAt: ServerTimestamp | Null
  isDone: Boolean | Null
}
...

• Demo
• Code

Changelog

See CHANGELOG.md.

Roadmap

See ROADMAP.md.

Related

• vuefire
• Vuex ORM
  • Vuex ORM takes a similar approach, but has no Firebase backend

Pull request

I'd be happy to review any pull requests that may better the heliosRX project, in particular, if you have a bug fix or enhancement. Before doing so, please first make sure that all of the tests pass (yarn test).

License

MIT License

Copyright (c) 2019-present, Thomas Weustenfeld