FeathersJS on Techformist

Learn FeathersJS by Building a Simple CRM - Client App

Wed, 22 Apr 2020 06:30:00 +0000

Here we see how to build a real-world client application for your FeathersJS backend. We will use Vue + Feathers-Vuex and quickly create the frontend app.

Building the Client Application

Previously you saw how we could use Feathers to quickly build a backend application. The beauty of feathers is not only that it is quick to build, but it is also universal.

We can use FeathersJS and Feathers-Vuex (our choice of client storage) to conjure up a client application that totally blows away our users.

Our choice of technology for building client -

Vue + Feathers-Vuex
Vuetify

Client: Get Started

This is what we will build for the client..

Let’s get started.

All great things in life starts with Vue CLI.

But, we don’t have the time and this is not a Vue tutorial. So, it’s time to work the magic and improve that statement.

So, we change the above quote..

A few great things start with boilerplates.

Unfortunately, again, we don’t quite have a starter-friendly boilerplate. We can either start from our vue-vuetify-booster boilerplate, or start afresh.

Either ways your Vue application should be setup in the client folder that is adjacent to the server folder where FeathersJS server resides. We will get our design inspiration from the above boilerplate.

Panel / Subpanel etc. are layouts defined in that boilerplate - we will reuse them
There are a few useful ways shortcuts to show snackbar, alerts etc, which we carry forward to this project
The home page, toolbar and navigation drawers will remain largely unchanged except for the links

See the Github repository for Featherlight CRM when in doubt.

At a high level, the client package.json has -

Vue + Vuetify

FeathersJS recommended packages. We will use communication over socket.io (alternatively we can use REST, but real-time using socket is more exciting)

npm i @feathersjs/feathers @feathersjs/rest-client @feathersjs/authentication-client @vue/composition-api feathers-vuex feathers-hooks-common --save

Add/modify transpileDependencies line to your vue.config.js -

module.exports = {
  // code

  transpileDependencies: ["vuetify", "feathers-vuex"],

  // more code
};

Add a new file feathers-client.js to implement feathers client -

import feathers from "@feathersjs/feathers";
import auth from "@feathersjs/authentication-client";
import feathersVuex from "feathers-vuex";
import socketio from "@feathersjs/socketio-client";
import io from "socket.io-client";
import { iff, discard } from "feathers-hooks-common";

const socket = io("http://localhost:3030", { transports: ["websocket"] });

const feathersClient = feathers()
  .configure(socketio(socket))
  .configure(auth({ storage: window.localStorage }))
  .hooks({
    before: {
      all: [
        iff(
          (context) => ["create", "update", "patch"].includes(context.method),
          discard("__id", "__isTemp")
        ),
      ],
    },
  });

export default feathersClient;

// Setting up feathers-vuex
const {
  makeServicePlugin,
  makeAuthPlugin,
  BaseModel,
  models,
  FeathersVuex,
} = feathersVuex(feathersClient, {
  serverAlias: "api", // optional for working with multiple APIs (this is the default value)
  idField: "id", // Must match the id field in your database table/collection
  whitelist: ["$regex", "$options"],
});

export { makeAuthPlugin, makeServicePlugin, BaseModel, models, FeathersVuex };

You should now be able to run the application without issues..

npm run serve

Router

Not a lot of interesting things here.. We just define a dynamic home to redirect users to dashboard or to the generic home page. Everything else is pretty standard.

Note that we have not implemented any navigation guards - but that is easy enough to do by uncommenting the requireAuth function and using that for the routes that need prior authentication.

import Vue from "vue";

import store from "../store/index";

import VueRouter from "vue-router";
import Home from "../views/Home.vue";

Vue.use(VueRouter);

// function requireAuth(to, from, next) {
//   if (store.state.auth.accessToken) next();
//   else next("/login");
// }

function dynamicHome(to, from, next) {
  // this should be ideally replaced by store.getters["auth/isAuthenticated"]
  // .. in newer versions
  if (store.state.auth.accessToken) next("/dashboard");
  else next();
}

function logout(to, from, next) {
  store.dispatch("auth/logout");
  next("/login");
}

const routes = [
  {
    path: "/",
    name: "home",
    component: Home,
    beforeEnter: dynamicHome,
  },
  {
    path: "/signup",
    name: "signup",
    component: () =>
      import(/* webpackChunkName: "register" */ "../views/Register.vue"),
  },
  {
    path: "/login",
    name: "login",
    component: () =>
      import(/* webpackChunkName: "login" */ "../views/Login.vue"),
  },
  {
    path: "/logout",
    name: "logout",
    beforeEnter: logout,
  },
  {
    path: "/terms",
    name: "Terms",
    component: () =>
      import(/* webpackChunkName: "terms" */ "../views/Terms.vue"),
  },
  {
    path: "/dashboard",
    name: "Dashboard",
    component: () =>
      import(/* webpackChunkName: "dashboard" */ "../views/Dashboard.vue"),
    // beforeEnter: requireAuth
  },
  {
    path: "/contacts",
    name: "Contact",
    component: () => import("../views/Contact.vue"),
  },
  {
    path: "/activities",
    name: "Activity",
    component: () => import("../views/Activity.vue"),
  },
  {
    path: "/contact-us",
    name: "Contact Us",
    component: () =>
      import(/* webpackChunkName: "contact-us" */ "../views/ContactUs.vue"),
  },
  {
    path: "/about",
    name: "About",
    // route level code-splitting
    // this generates a separate chunk (about.[hash].js) for this route
    // which is lazy-loaded when the route is visited.
    component: () =>
      import(/* webpackChunkName: "about" */ "../views/About.vue"),
  },
  {
    // catch all 404
    path: "*",
    component: () => import("../views/NotFound.vue"),
  },
];

const router = new VueRouter({
  mode: "history",
  base: process.env.BASE_URL,
  routes,
});

export default router;

Vuex

Add a new folder called store/services and create users.js.

import feathersClient, {
  makeServicePlugin,
  BaseModel,
} from "../../feathers-client";

class User extends BaseModel {
  constructor(data, options) {
    super(data, options);
  }
  // Required for $FeathersVuex plugin to work after production transpile.
  static modelName = "User";
  // Define default properties here
  static instanceDefaults() {
    return {
      email: "",
      password: "",
      name: "",
    };
  }
}
const servicePath = "users";
const servicePlugin = makeServicePlugin({
  Model: User,
  service: feathersClient.service(servicePath),
  servicePath,
});

// Setup the client-side Feathers hooks.
feathersClient.service(servicePath).hooks({
  before: {
    all: [],
    find: [],
    get: [],
    create: [],
    update: [],
    patch: [],
    remove: [],
  },
  after: {
    all: [],
    find: [],
    get: [],
    create: [],
    update: [],
    patch: [],
    remove: [],
  },
  error: {
    all: [],
    find: [],
    get: [],
    create: [],
    update: [],
    patch: [],
    remove: [],
  },
});

export default servicePlugin;

As you see - this is has the familiar structure of FeathersJS. We can fine tune this and change app behaviour, but will leave it that for now.

Create a similar file for contacts - we will use the name contactsPlugin instead of servicePlugin. Rest remains the same.

We will register these plugins in the store.

import Vue from "vue";
import Vuex from "vuex";

import { FeathersVuex } from "../feathers-client";

import snackbar from "./snackbar";
import pref from "./pref";
import alert from "./alert";

import auth from "./auth";
import servicePlugin from "./services/users";
import contactsPlugin from "./services/contacts";

Vue.use(Vuex);
Vue.use(FeathersVuex);

export default new Vuex.Store({
  namespaced: true,
  name: "global",

  modules: {
    snackbar,
    pref,
    alert,
    auth,
    servicePlugin,
    contactsPlugin,
  },
  plugins: [auth, servicePlugin, contactsPlugin],

  state: {},
  getters: {
    isLoggedIn(state, getters, rootState) {
      return !!rootState.auth.accessToken;
    },
  },
});

You will see a few modules not used by feathers - it is just to make the application more pleasing. You can ignore them.

Views

Let us create the Contact view. This is simple and straight forward - we just render the list component here.

<template>
  <Panel icon="mdi-book-plus" title="Contacts">
    <template slot="toolbar-items"></template>
    <template slot="content">
      <ContactList />
    </template>
  </Panel>
</template>

<script>
import Panel from "../components/layouts/Panel";
import ContactList from "../components/ContactList";

export default {
  components: {
    Panel,
    ContactList
  }
};
</script>

Contact View - List Component

Next, let us create components/ContactList.vue.

<template>
  <PanelListMain>
    <template slot="toolbar-items">
      <span class="subtitle-2">Contact Listspan>
      <v-spacer>v-spacer>
      <v-btn @click="newRecord" small outlined>
        <v-icon small>mdi-plusv-icon>New
      v-btn>
    template>
    <template slot="content">
      <v-row dense>
        <v-col cols="12">
          <v-card flat color="transparent" height="100%" style="overflow:auto">
            <v-card-title>
              <v-spacer>v-spacer>

              <v-text-field
                v-model="srchLastName"
                prepend-icon="mdi-magnify"
                label="Search Last Name"
                single-line
              >v-text-field>
            v-card-title>

            <v-data-table
              :headers="headers"
              :items="contacts"
              hide-default-footer
            >
              <template v-slot:item="props">
                <tr>
                  <td>{{ props.item.first_name }}td>
                  <td>{{ props.item.last_name }}td>
                  <td>{{ props.item.title }}td>
                  <td>{{ props.item.status_cd }}td>
                  <td>{{ props.item.email }}td>
                  <td>{{ props.item.phone }}td>
                  <td>
                    <v-icon color="success" @click="editRecord(props.item)"
                      >mdi-pencilv-icon
                    >
                  td>
                tr>
              template>
            v-data-table>
          v-card>
        v-col>
        
      v-row>

      <ContactEdit
        v-if="detailDialog"
        v-model="detailDialog"
        :currentItem="currentItem"
      />
    template>
  PanelListMain>
template>

<script>
  import { makeFindMixin } from "feathers-vuex";
  import PanelListMain from "./layouts/PanelListMain";

  export default {
    data() {
      return {
        detailDialog: false,
        headers: [
          { text: "First Name", value: "first_name" },
          { text: "Last Name", value: "last_name" },
          { text: "Title", value: "title" },
          { text: "Status", value: "status_cd", sortable: false },
          { text: "Email", value: "email", sortable: false },
          { text: "Phone", value: "phone", sortable: false },
          { text: "Actions", value: "actions", sortable: false },
        ],
        srchLastName: "",
        currentItem: {},
      };
    },

    computed: {
      contactsParams() {
        return { query: this.search };
      },
      search() {
        const srchStr = {};
        if (this.srchLastName) srchStr["last_name"] = this.srchLastName;

        return srchStr;
      },
    },
    mixins: [makeFindMixin({ service: "contacts" })],

    methods: {
      // changePage(page) {
      //   this.fetchContact({
      //     page: page,
      //     query: this.search,
      //   });
      // },

      editRecord(item) {
        this.currentItem = item;
        this.detailDialog = true;
      },

      newRecord() {
        this.currentItem = {};
        this.detailDialog = true;
      },
    },

    components: {
      PanelListMain,
      ContactEdit: () => import("./ContactEdit"),
    },
  };
script>

There’s a lot going on, but we did not quite put in anything special.

To start with, we introduced ..

import { makeFindMixin } from "feathers-vuex";

// ...

mixins: [makeFindMixin({ service: "contacts" })],

The above code imported and used a feathers provided mixin that makes our coding easier and more generic. We have indicated our intent to use the contacts service - this refers to the service file that we created earlier, which also automatically “maps” (not exactly, but bear with me) to the contacts service in the backend Feathers.

We create a computed variable which can be used to pass params to the mixin -

  contactsParams() {
      return { query: this.search };
  },

By doing just this, we have access to the contacts list. This is the list of contacts fetched from the backend and rendered as a table.

We can change search to pass search criteria. User enters search, and we just pass it as a param in a function.

computed: {
  search() {
      const srchStr = {};
      if (this.srchLastName) srchStr["last_name"] = this.srchLastName;
      return srchStr;
  },
}

Again.. let me reiterate it for you.

All we did was to add a service, introduced boilerplate code for feathers-client.js and pulled in the mixin. This resulted in the contacts being pulled from the server / from our database.

In addition to what has been outlined so far -

We can add functionality with simple param changes on client side and by adding hooks/custom services on server - again a lot of functionality with less code
The app has real-time functions - any changes (on server through API calls / by other users) are published to clients (all clients with default configuration) and our browser starts showing those changes

What we did not do -

use REST calls with something like fetch/ Axios
manage variables in components / Vuex
create logic to search - on client and server

That’s a lot of work saved.

Contact Edit

Let’s keep going.

We will add a reference to a new component in ContactList to enable us to edit contacts.

<ContactEdit
  v-if="detailDialog"
  v-model="detailDialog"
  :currentItem="currentItem"
/>

Also, add methods to display this detail component on click of New or Edit buttons.

methods: {
  editRecord(item) {
    this.currentItem = item;
    this.detailDialog = true;
  },

  newRecord() {
    this.currentItem = {};
    this.detailDialog = true;
  },
}

We set the current item and send it off to ContactEdit.

There are multiple, better ways to invoke ContactEdit to create more elegant/succinct code - we just used on of the options.

ContactEdit has some interesting things going on-

<template>
  <v-dialog v-model="showDialog" persistent max-width="1100px">
    <SubPanel>
      <template slot="toolbar-items">
        <span class="subtitle-2">New/Edit Contactspan>
      template>

      <template slot="content" v-if="item">
        <FeathersVuexFormWrapper :item="item" watch>
          <template v-slot="{ clone, save, reset, remove }">
            <v-form ref="form" v-model="validInput">
              <v-card flat>
                <v-card-text>
                  <v-row>
                    <v-col cols="12" md="3">
                      <v-text-field v-model="item['first_name']">
                      v-text-field>
                    v-col>
                    <v-col cols="12" md="3">
                      <v-text-field v-model="item['last_name']" required>
                      v-text-field>
                    v-col>
                    <v-col cols="12" md="3">
                      <v-select
                        :items="['active', 'inactive']"
                        label="Status"
                        v-model="item['status_cd']"
                        required
                      >v-select>
                    v-col>
                  v-row>
                v-card-text>
                <v-card-actions>
                  <v-spacer>v-spacer>
                  <v-btn outlined @click="closeDialog">Cancelv-btn>
                  <v-btn color="primary" @click="saveRecord">
                    Save
                  v-btn>
                v-card-actions>
              v-card>
            v-form>
          template>
        FeathersVuexFormWrapper>
      template>
    SubPanel>
  v-dialog>
template>

<script>
  import { mapMutations } from "vuex";
  import SubPanel from "./layouts/SubPanel";

  import { FeathersVuexFormWrapper } from "feathers-vuex";

  export default {
    data() {
      return {
        validInput: true,
        item: null,
      };
    },
    props: {
      value: Boolean,
      currentItem: {
        type: Object,
        required: true,
      },
    },

    mounted() {
      const { Contact } = this.$FeathersVuex.api;

      const contactModel = new Contact();
      this.item =
        !this.currentItem || !this.currentItem["id"]
          ? contactModel
          : Contact.getFromStore(this.currentItem["id"]);
    },
    computed: {
      showDialog: {
        get() {
          return this.value;
        },
        set(value) {
          this.$emit("input", value);
        },
      },
    },

    components: {
      SubPanel,
    },

    methods: {
      ...mapMutations("snackbar", ["setSnack"]),

      saveRecord() {
        if (this.$refs.form.validate()) {
          if (!this.item["id"]) {
            this.item.save().catch((e) => {
              this.showError(e);
            });
          } else this.item.update();

          this.closeDialog();
        }
      },

      closeDialog() {
        this.showDialog = false;
      },

      showError(e) {
        // you can do other housekeeping here.
        this.setSnack({ message: "Error saving contact.", color: "error" });
        console.error("Error saving record", e);
      },
    },
  };
script>

When the component loads, we specify whether we are creating a new record or editing an existing record.

mounted() {
    const { Contact } = this.$FeathersVuex.api;

    const contactModel = new Contact();
    this.item =
      !this.currentItem || !this.currentItem["id"]
        ? contactModel
        : Contact.getFromStore(this.currentItem["id"]);
},

We fold our form within -

<FeathersVuexFormWrapper :item="item" watch>
  <template v-slot="{ clone, save, reset, remove }"> template>
FeathersVuexFormWrapper>

This code block does quite a few things -

Automatically manage vuex best practices to clone our storage variable (item in our case) when necessary. We also indicated support saving, resetting form and removing records
Feathers client automatically maps the record received from the list to the context of the Contact service (either a new record or find existing record from store)

Finally, we introduce code to save record -

      saveRecord() {
        if (this.$refs.form.validate()) {
          if (!this.item["id"]) {
            this.item.save().catch((e) => {
              this.showError(e);
            });
          } else this.item.update();

          this.closeDialog();
        }
      },

This code block validates form, and invokes save or update methods supported by our feathers-client to send data to our server. Server Feathers knows the operations from the invoked services and carries out those operations on server.

You may also observe that we did not quite use auth here, but it is implied in the background. Feathers figures out that for us. However, you will observe that we have created the auth module (all of two lines), included it as a plugin in the store, and created components for user registration and login.

That is it - you now have a full fledged.. oh wait.

Remember our previous statement? CRM application is not contacts alone - all of us and our neighbour’s dog know that activities make CRM application “whole”.

That said - I don’t want to take away that opportunity of creating a brand new service and Vuex plugin from you. Like the seers of yore, I just point to the direction and you execute all magic, eh?

Finis!

So here we are then.. A complete.. , er.., 50% complete “totally real-world application” built using FeathersJS on server and client

It is time for you to spread your wings and fly to newer heights and into the next telephone pole with this knowledge.

I mentioned earlier that the code used here is available on Github - please don’t forget to star the repository. Those stars are what I count sometimes to go to sleep - more the merrier.

Enjoy.

Learn FeathersJS by Building a Simple CRM App

Wed, 08 Apr 2020 06:30:00 +0000

We have previously seen a simple todo app using FeathersJS(and NeDB).

Feathers makes it really easy to develop an API or a real-time app by providing a super-powered baseline that can be extended quickly to create a useful app. However, the example provided earlier does not provide a set of features anywhere near the real-world experience.

So, here we are talking about all the additional things that Feather could do - only if you let it. This is a FeatherJS + ObjectionJS + Feather-Vuex tutorial through building a totally real-world, simple CRM application called ‘FeatherLight CRM’. We name it thus since all awesome apps deserve their own name and identity.

Our Chosen Ecosystem

First, let us get our basic ecosystem right.

Feathers groups together various components and provides more than one component options to do the same job. So, it is that with flutter in my heart, I choose -

Postgres - possibly the greatest database of our times
Objection ORM - Benefits of an ORM, and knex for DB migration + operations + low-level query builder
Local authentication

Next.. since we love our SPAs and scoff at anything more simple, we choose -

Vue + Vuex
Feathers-Vuex (this is the main reason for choosing Vue - makes it a cool developer experience. Feathers and cool - did you get it?)

Dealing with all this complexity can spur anxiety, so let us divide the tasks into those required for server and client.

This post primarily deals with server-related tasks, i.e, all things FeathersJS. We will see more of Vue in a subsequent post.

Server: Get Started

Getting started on Feathers is a breeze and is similar to our earlier project.

Install CLI if you don’t have feathers on your computer.

npm i -global @feathersjs/cli

Create the project folder and a client and server folders to store your code.

mkdir featherlight-crm
cd featherlight-crm
mkdir client
mkdir server
cd server
feathers g app

Choose the configuration values for FeathersJS server that talked about five seconds back. Also, it will be great if you can make the database available at this time - the generator also tries to check for the database.

Open the project folder in your favourite editor - which should be VSCode by now.

Once the app generation is complete, open ./config/default.json and change the database section to tell knex where migrations need to be stored - both the directories for seed/migrations, and the table in database. This will come in handy in a bit.

"postgres": {
    "client": "pg",
    "connection": "postgres://postgres:@localhost:5432/t_2",
    "migrations": {
      "directory": "../database/migrations",
      "tableName": "knex_migrations"
    },
    "seeds": {
      "directory": "../database/seeds"
    }
  }

Run your server -

npm run dev

This will not only start the server, but also migrate users (created by our generator) to the database. Note that we did not create migrations for users - ideally we should have done that, but we are crazy enough to want a practical demo of what is possible with Feathers out of the box vs. how our changes impact the way we work.

You can check whether server is running by hitting a few sample end-points in your favourite API client - which should be Insomnia.

API	Result
GET: http://localhost:3030	200 OK: Sample feathers HTML
GET: http://localhost:3030/users	401 Unauthorized: Not authenticated yet
POST: http://localhost:3030/users ; input JSON below	200 OK: User created, response JSON with user id
POST: http://localhost:3030/authentication ; input JSON below	200 OK: User logged in, response JSON with JWT

Input messages -

POST: New User

{
  "email": "a1@a.com",
  "password": "a1"
}

POST: Login

{
  "email": "a1@a.com",
  "password": "a1",
  "strategy": "local"
}

That is it - you have your baseline beautiful project ready.

Server: Folder Structure

Before we proceed, we will have “more words” on the setup.

FeathersJS is straightforward and does not believe in magic. The folder structure reflects that. Some of the key folders along with their functions are outlined below.

Folder Name	What it contains?	Function
config	Configuration files for prod & non-prod environments	Provides config values and parameters including server address/port, DB connection strings, auth mechanism, etc.
public	Any files available to the external world	Typical server implementations use some kind of reverse proxy to expose public files to the outside world
src	All source code	Key files: `app`, `authentication`, `knex`, `objection`
src/models	All models	DB models ready to be migrated
src/services	Services are at the heart of Feathers	Individual folders for users and other services. Consists of services and hooks. Hooks also specify routes amongst other things
test	Tests for your app	Automated testing!

We have to pay attention to services in some detail.

Services will have folders created for each new service (well, there are exceptions and weird logic - but this is typical ). Services have a couple of things going for them -

Feathers maps REST services to the services defined here - you will be able to make out the similarities between the methods supplied by default and the REST service types
Services can also be called on websockets and the same service runs happily
Hooks provide a before/after way of plugging in custom logic for the services

We will see much more of this with a practical example below.

Server: Create new functionality

Let us create a string of entities and functions around the entity to enable our super CRM app.

Create contact service

It may be a good idea to stop your feathers service at this time. Now, use feathers generate command to create a new service.

feathers g service

Answer the questions to create a new service called contacts. You can select the same Objection as data source as that chosen while creating the app.

This does some useful things -

create 3 files under src/services/contacts/ - service, hooks and class
create a sample test for contacts
create contacts.model in ./src/models/
update services/index with the new contacts service

If you had the feathers server running, contacts table will get created with the default columns specified in contacts.model. We stopped the service since we don’t want that.

As you can see -

the new structure for contacts is straight-forward and similar to our users example above.
By just running the CLI, you now have the entire contacts service + model setup.

The Art of Models and Migration

Open src/models/contacts.model.js. Add your own fields, and remove logic to migrate tables.

// See https://vincit.github.io/objection.js/#models
// for more of what you can do here.
const { Model } = require("objection");

class contacts extends Model {
  static get tableName() {
    return "contacts";
  }

  static get jsonSchema() {
    return {
      type: "object",
      required: ["last_name"],

      properties: {
        first_name: { type: "string", maxLength: 50 },
        last_name: { type: "string", maxLength: 50 },
        title: { type: "string", maxLength: 25 },
        email: { type: "string", maxLength: 100 },
        phone: { type: "string", maxLength: 25 },
        status_cd: {
          type: "string",
          enum: ["active", "disabled"],
          default: "active",
        },
        address: {
          type: "object",
          properties: {
            street: { type: "string" },
            city: { type: "string" },
            zipCode: { type: "string" },
          },
        },
      },
    };
  }

  $beforeInsert() {
    this.created_at = this.updated_at = new Date().toISOString();
  }

  $beforeUpdate() {
    this.updated_at = new Date().toISOString();
  }
}

module.exports = function (app) {
  // remove the knex table creation code from here

  return contacts;
};

While the default contact.model.js is good for initial migration, it becomes tricky to manage future changes. So, we will take the migration statements away from this file, group it elsewhere, and at the same time - streamline migrations.

First, create a file knexfile.js in project root -

const app = require("./src/app");
module.exports = app.get("postgres");

Next, install knex command line utility globally. This is useful to manage migrations in this project, and in hundreds of other projects that we will created in the next year.

npm i -g knex

You would have already noticed the config folder in the project root. Make modifications to default.json..

// lot of params/code
"postgres": {
    "client": "pg",
    "connection": "postgres://postgres:@localhost:5432/t_2",
    "migrations": {
      "tableName": "knex_migrations"
    }
  }
// ...

The above configuration will set the stage and indicate that a place to store migrations in a DB table called knex_migrations (not created yet).

We are all set. Run knex to create migration files -

knex migrate:make init

This will create a template migration file in ./database/migrations/ folder - something like 20200422152442_init.js.

Cut/paste create table statements from the contacts.models.js to this migration file - with a few changes.

// ./database/migrations/20200422152442_init.js
exports.up = function (knex) {
  return knex.schema.createTable("contacts", (table) => {
    table.increments("id");
    table.timestamp("created_at");
    table.timestamp("updated_at");
    table.string("first_name", 50);
    table.string("last_name", 50);
    table.string("title", 25);
    table.string("email", 100);
    table.string("phone", 25);
    table.string("status_c").defaultTo("active");
  });
};

exports.down = function (knex) {
  return knex.schema.dropTable("contacts");
};

Now, you can take a deep breath and migrate the table to database.

knex migrate:latest

Check in your database to find contacts table.

But then, while still holding on to the breath, you realise a mistake. There has been one of the hardest typo mistakes that can ever be - status_cd is wrongly input as status_c.

No problem, let us change that.

knex migrate:rollback

.. and ta da - the contacts table is gone from the DB.

Re-run migration -

knex migrate:latest

Did you start breathing again? Well, good for you - that was just in time to realise another miss. You never added address - tis’ a good thing we are still learning here and not doing a multi-million dollar project. We can always do this later.

Congratulations on completing the database tasks.

Back to the Server

Start your server again ..

npm run dev

You can start doing your REST calls without writing any code to handle contacts transactions -

1. POST http://localhost:3030/contacts

Input -

{
  "first_name": "abc",
  "last_name": "1"
}

Don’t forget to provide token from the authentication/login call done earlier as a bearer token.

Output -

{
  "id": 1,
  "created_at": "2020-03-22T10:59:03.265Z",
  "updated_at": "2020-03-22T10:59:03.265Z",
  "first_name": "abc",
  "last_name": "1",
  "title": null,
  "email": null,
  "phone": null,
  "status_cd": "active"
}

A new contact called abc 1 is created.

2. GET http://localhost:3030/contacts

Input -

< no input >

Output -

{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "id": 1,
      "created_at": "2020-03-22T10:59:03.265Z",
      "updated_at": "2020-03-22T10:59:03.265Z",
      "first_name": "abc",
      "last_name": "1",
      "title": null,
      "email": null,
      "phone": null,
      "status_cd": "active"
    }
  ]
}

This is the right time to let out a joyous cry - huzzah!

More migrations

You have already seen that feathers generate has already created the contacts model. But, what if you want to change the model?

Changing model will imply changes to -

model
underlying table

Since feathers is just the coordinator here, we will just use the full power of underlying ObjectionJS/knex and migrations as seen previously.

In our case, we demonstrated our careful planning abilities by adding address in our model (yes, this is a mistake. And yes, this is one of the ways of covering up mistakes). So, the model doesn’t need to change.

But, we do have to add address to database. We already have two tables created and are in no mood to rollback a second time. Instead, we add incremental changes to the same table.

Let’s create another migration file -

knex migrate:make contact-address

Change the migration file -

// ./database/migrations/20200422173242_contact-address.js
exports.up = function (knex) {
  return knex.schema.table("contacts", (table) => {
    table.json("address");
  });
};

exports.down = function (knex) {
  knex.schema.table("contacts", function (table) {
    table.dropColumn("address");
  });
};

Run migration -

knex migrate:latest

You will now start seeing an address column against contacts table.

Also, you may have already noticed a table called knex_migrations in your database. That table should have two migration records corresponding to the initial migration and the subsequent incremental migration after doing the above tasks for address.

Knex migrations started shining really bright, didn’t they?

More Entities and Functions

Now that we have walked through an entity and service, and also know how to change them - we can create dozens more with just clicks and copy/paste magic.

Change Users

Previously when you saw how easily we could manage database changes - you were left thinking on how users was not included into this fold. Feathers migrated that table for us, and we don’t quite have any way to control that migration.

The good news - you can start anytime without a care for the past deeds. You just have to create another migration and repeat the above tasks to create additional columns and manually change the users.models.js file. It does not matter whether users was created initially by feathers or created by hand in the backend.

So, let’s do that!

Create migration file -

knex migrate:make user-enhancements

Change the migration file -

exports.up = function (knex) {
  return knex.schema.table("users", (table) => {
    table.string("role_cd", 50);
    table.string("status_cd", 50);
    table.date("start_date");
    table.date("end_date");
  });
};

exports.down = function (knex) {
  return knex.schema.table("users", function (table) {
    table.dropColumn("role_cd");
    table.dropColumn("status_cd");
    table.dropColumn("start_date");
    table.dropColumn("end_date");
  });
};

Run migration -

knex migrate:latest

Add Activities Model/Service

It is time to upgrade our app - a CRM app cannot be as simple as having users and contacts. Everyone knows that it is the activities that complete CRM.

By now, you will probably be scoffing and guffawing at adding a new service.

feathers g service

Name this new service activities, and select all the right options.

Change activities.model.js -

// See https://vincit.github.io/objection.js/#models
// for more of what you can do here.
const { Model } = require("objection");

class activities extends Model {
  static get tableName() {
    return "activities";
  }

  static get jsonSchema() {
    return {
      type: "object",
      required: ["type_cd", "status_cd"],

      properties: {
        text: { type: "string" },
        description: { type: "string", maxLength: 255 },

        type_cd: {
          type: "string",
          enum: ["Task", "Call", "Meeting"],
          default: "Task",
        },
        status_cd: {
          type: "string",
          enum: ["Created", "Planned", "In Progress", "Closed", "Cancelled"],
          default: "Created",
        },
        start_date: { type: "timestamp" },
        end_date: { type: "timestamp" },
        due_date: { type: "timestamp" },
        duration: { type: "integer" },
        contact_id: { type: "integer" },
        user_id: { type: "integer" },
        remarks: { type: "text" },
      },
    };
  }

  $beforeInsert() {
    this.created_at = this.updated_at = new Date().toISOString();
  }

  $beforeUpdate() {
    this.updated_at = new Date().toISOString();
  }
}

module.exports = function () {
  return activities;
};

Create a migration template for activities -

knex migrate:make activities

Change 20200422192555_activities.js (the comparative migration file created for you in database/migrations folder) -

exports.up = function (knex) {
  return knex.schema.createTable("activities", (table) => {
    table.increments("id");
    table.timestamp("created_at");
    table.timestamp("updated_at");
    table.integer("contact_id");
    table.integer("user_id");
    table.string("type_cd", 100);
    table.string("status_cd", 100);
    table.string("description", 255);
    table.timestamp("start_date");
    table.timestamp("end_date");
    table.timestamp("due_date");
    table.integer("duration");
    table.text("remarks");
  });
};

exports.down = function (knex) {
  return knex.schema.dropTable("activities");
};

You perform activities and tasks for a contact. So, one contact can have many activities. Similarly an activity is done by a user. Hence, we can smartly conclude that activities are related to both users and contacts.

We have played things well and already created contact_id, user_id columns in our activities table. We can also establish the relationship at the model level.

Insert the below code block before $beforeInsert() in activities.model.js.


//.. other code

static get relationMappings() {
    const User = require("./users.model");
    const Contact = require("./contacts.model");

    return {
      owner: {
        relation: Model.BelongsToOneRelation,
        modelClass: User,
        join: {
          from: "activities.user_id",
          to: "users.id",
        },
      },
      contact: {
        relation: Model.BelongsToOneRelation,
        modelClass: Contact,
        join: {
          from: "activities.contact_id",
          to: "contacts.id",
        },
      },
    };
  }

  //.. more code

You can see a pattern emerging here, don’t you? Objection and Knex make it quite easy to establish and manage relationships. (In this case, however, note that we did not tell the DB that contact_id or user_id are foreign key fields - that can be easily fixed in the migration files).

You can start performing activity requests.

POST http://localhost:3030/activities

< input and output are the same :) >

{
  "type_cd": "Meeting",
  "status_cd": "Cancelled",
  "contact_id": 1,
  "user_id": 1
}

GET http://localhost:3030/activities

< no input data >

{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "type_cd": "Meeting",
      "status_cd": "Cancelled",
      "start_date": null,
      "end_date": null,
      "due_date": null,
      "description": null,
      "created_at": "2020-03-23T04:39:09.182Z",
      "updated_at": "2020-03-23T04:39:09.182Z",
      "id": 1
    }
  ]
}

Since you already established relationship and storing contact you may also want contact to be fetched along with activity details. We established the relationship by changing activity.model.js but did not tell feathers to get contact details.

That’s quite easy to do and requires two steps.

Step 1: Change activities.service.js

We tell feathers to allow “eager” loading of contact details. Change options value in activity service.

const options = {
  Model: createModel(app),
  paginate: app.get("paginate"),
  whitelist: ["$eager"],
  allowedEager: "[contact]",
};

Step 2: Change activities.hooks.js

We will do more than just query for the related contacts -

Use find hook to $select only some fields to include in the result
Allow feathers to eager load contact - $eager: "contact"
Sort results by created_at (desc) - $sort: { created_at: -1 }
Filter activities by owner if the logged in user is not an admin - if (!isAdmin(context)) query["user_id"] = context.params.user.id;

These changes are more or less self-explanatory - you can just see the super powers of feathers tumbling out one after the other.

const { authenticate } = require("@feathersjs/authentication").hooks;

const isAdmin = (context) => {
  return context.app.settings.appconf.admin_roles.includes(
    context.params.user.role_cd
  );
};

module.exports = {
  before: {
    all: [authenticate("jwt")],

    find: [
      async (context) => {
        const query = {
          $select: [
            "type_cd",
            "status_cd",
            "start_date",
            "end_date",
            "due_date",
            "description",
            "created_at",
            "updated_at",
          ],
          $eager: "contact",
          $sort: { created_at: -1 },
        };

        if (!isAdmin(context)) query["user_id"] = context.params.user.id;

        context.params.query = { ...context.params.query, ...query };
        return context;
      },
    ],
    get: [],
    create: [
      async (context) => {
        // populate user as logged in user by default
        if (!isAdmin(context)) context.data.user_id = context.params.user.id;

        return context;
      },
    ],
    update: [],
    patch: [],
    remove: [],
  },

  after: {
    all: [],
    find: [],
    get: [],
    create: [],
    update: [],
    patch: [],
    remove: [],
  },

  error: {
    all: [],
    find: [],
    get: [],
    create: [],
    update: [],
    patch: [],
    remove: [],
  },
};

If you don’t want to pass context everywhere (e.g. isAdmin(context)), you should totally checkout hooks-common.

After these changes, it is time to get a different response when querying activities -

GET http://localhost:3030/activities

{
  "total": 1,
  "limit": 10,
  "skip": 0,
  "data": [
    {
      "type_cd": "Meeting",
      "status_cd": "Cancelled",
      "start_date": null,
      "end_date": null,
      "due_date": null,
      "description": null,
      "created_at": "2020-03-23T04:39:09.182Z",
      "updated_at": "2020-03-23T04:39:09.182Z",
      "id": 1,
      "contact": {
        "id": 1,
        "created_at": "2020-03-22T10:57:37.957Z",
        "updated_at": "2020-03-22T10:57:37.957Z",
        "first_name": "abc",
        "last_name": "1",
        "title": null,
        "email": null,
        "phone": null,
        "status_cd": "active",
        "address": null
      }
    }
  ]
}

You can create more than one record to test sort order and filter conditions.

Finis

That is it!

We now have the server-side of a totally real-world CRM application ready -

Store users, contacts and activities
Ability to register and login
Secured data access by filtering activities by owner

If you are stuck anywhere, you could always check your code against the featherlight-crm repository.

Excited about this CRM application and can’t wait to start using it? Onwards to the next phase and developing a FeathersJS client application on Vue!

Unlock FeathersJS power with a todo client

Thu, 29 Aug 2019 06:30:00 +0000

Create a simple to-do client using FeathersJS.

We saw a quick tutorial on creating simple FeathersJS API yesterday. Let’s unlock the full power of Feathers by using its client library and consume the API created in the earlier post!

Install and initialize project

We will use plain Javascript and HTML with Feathers client-side library for the purpose of this demonstration.

Create HTML page

Create a simple HTML page to include -

a simple input box to enter new to-do
an element to display to-dos fetched from server

We will also include feathers from CDN.

And, copy over styling and scripts from Bootstrap grid and components.




<html>
  <head>
    <meta content="text/html;charset=utf-8" http-equiv="Content-Type" />
    <meta content="utf-8" http-equiv="encoding" />
    <title>todof!title>
    <link
      rel="stylesheet"
      href="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/css/bootstrap.min.css"
      integrity="sha384-ggOyR0iXCbMQv3Xipma34MD+dH/1fQ784/j6cY/iJTQUOhcWr7x9JvoRxT2MZw1T"
      crossorigin="anonymous"
    />
  head>

  <body>
    <div class="container pt-5">
      <div class="row col-3">
        <h3>Todof Todos!h3>
      div>
      <div class="pt-5">div>
      <div class="row ">
        <div class="input-group col-4">
          <label for="inTodo">label>
          <input
            type="text"
            class="form-control"
            id="inTodo"
            placeholder="New todo"
          />
        div>
        <div class="input-group col-1 ">
          <button onclick="insertTodo()">OKbutton>
        div>
      div>
      <div class="row">div>
      <div class="pt-5 col-4">
        <div id="todosNode">div>
      div>
    div>
    <script
      src="https://code.jquery.com/jquery-3.3.1.slim.min.js"
      integrity="sha384-q8i/X+965DzO0rT7abK41JStQIAqVgRVzpbzo5smXKp4YfRvH+8abtTE1Pi6jizo"
      crossorigin="anonymous"
    >script>
    <script
      src="https://stackpath.bootstrapcdn.com/bootstrap/4.3.1/js/bootstrap.min.js"
      integrity="sha384-JjSmVgyd0p3pXB1rRibZUAYoIIy6OrQ6VrjIEaFf/nJGzIxFDsf4x0xIM+B07jRM"
      crossorigin="anonymous"
    >script>
    <script src="https://unpkg.com/@feathersjs/client@^4.3.0/dist/feathers.js">script>

    <script src="app.js">script>
  body>
html>

I bet you noticed that we imported script from app.js. That is the script doing all the magic and let’s start creating that magic.

Initialize and configure `feathers`

Initialize feathers. Create a socket to establish connection and talk to server.

// app.js
console.log("hello world");

const socket = io();
var client = feathers();
client.configure(feathers.socketio(socket));

Setup authentication

Configure and call authentication service from server to authenticate user.

// app.js
const config = client.get("authentication");

client.configure(feathers.authentication(config));

var token = login();

async function login() {
  const auth = await client.authenticate({
    strategy: "local",
    email: "a@test.com",
    password: "abcde",
  });
  console.log(auth.accessToken);
  return auth.accessToken;
}

We have hard-coded the user id and password for a quick test - typically that should come from a login form.

Just open index.html in a browser and you should be able to see a nice JSON token in the console.

Display to-do’s

Include code to fetch and display to-do’s.

getTodo();

async function getTodo() {
  const todoRecs = await client.service("todo").find();
  this.renderList("todosNode", todoRecs);
}

async function renderList(nodeId, data) {
  document.getElementById(nodeId).innerHTML = "";
  let dataList = "";
  for (var i = 0; i < data.data.length; i++) {
    dataList += "" + data.data[i]["title"] + "
";
  }
  document.getElementById(nodeId).innerHTML = `${dataList}
`;
}

Create to-do

Tie the input box to the flow. Create new to-do when ‘OK’ is clicked.

async function insertTodo() {
  console.log("todo is ", document.getElementById("inTodo").value);
  const todoCreate = await client
    .service("todo")
    .create({ title: document.getElementById("inTodo").value });
  console.log("todo created");
  document.getElementById("inTodo").value = "";
  this.getTodo();
}

End result

Without writing a lot of code, we have -

Created a HTML page that talks to our back-end Feathers server
Fetched to-dos and displayed them on the UI
Insert a to-do record without much fuss

Full code

Find all code on GitHub. Here’s the full Javascript in app.js.

// app.js
console.log("hello world");

const socket = io();

var client = feathers();
const config = client.get("authentication");

client.configure(feathers.socketio(socket));
client.configure(feathers.authentication(config));

var token = login();

getTodo();

async function login() {
  const auth = await client.authenticate({
    strategy: "local",
    email: "a@test.com",
    password: "abcde",
  });
  return auth.accessToken;
}

async function getTodo() {
  const todoRecs = await client.service("todo").find();
  this.renderList("todosNode", todoRecs);
}

async function renderList(nodeId, data) {
  document.getElementById(nodeId).innerHTML = "";
  let dataList = "";
  for (var i = 0; i < data.data.length; i++) {
    dataList += "" + data.data[i]["title"] + "
";
  }
  document.getElementById(nodeId).innerHTML = `${dataList}
`;
}

async function insertTodo() {
  console.log("todo is ", document.getElementById("inTodo").value);
  const todoCreate = await client
    .service("todo")
    .create({ title: document.getElementById("inTodo").value });
  console.log("todo created");
  document.getElementById("inTodo").value = "";
  this.getTodo();
}

Create a simple to-do API with FeathersJS

Wed, 28 Aug 2019 06:30:00 +0000

Create a simple to-do API using FeathersJS v4.

FeathersJS v4 launched yesterday, and I wanted to see what changed. Of course, I wasn’t going to write a post just about v4 - I have not kept up with the Feathers ecosystem. So, let’s refresh our mind and soul by building a quick API and see how the story develops.

We can start with Feathers using their CLI or with just a NPM install. We will use feathers CLI for the purpose of this post because of two reasons -

the CLI is simply awesome
I am lazy - feathersjs CLI saves a lot of typing

Install and initialize project

Install Feathers CLI globally.

npm install -g @feathersjs/cli

Create project.

md todof
cd todof
feathers generate app todof

Select defaults for all questions. After the process completes you should have a new project folder (todof) with all packages installed and with an updated package.json.

Explore the project folder in VSCode.

Start coding an API

Create a new service. A service is an instance of a class and contains all operations for a particular entity.

feathers g service todo

feathers g is short for feathers generate.

The command will -

create a todo folder and a class, hook and service file within the folder (prefixed by todo.)
create todo.model.js in models folder
register newly created modules

Start your server.

npm run dev

This will start a feathers server at port 3030 by default.

Run your new API

Go to Insomnia (or your favourite client).

Create a GET request to http://localhost:3030/todo

You will receive an 401 error if you had accepted all defaults while creating the service.

{
  "name": "NotAuthenticated",
  "message": "Not authenticated",
  "code": 401,
  "className": "not-authenticated",
  "errors": {}
}

Create user and authenticate

Let’s create a user and use that user to authenticate.

Create a POST request to http://localhost:3030/users to create new user

{
  "email": "a@test.com",
  "password": "abcde"
}

Login with the new user. Create a new POST request to http://localhost:3030/authentication
```
{
  "email": "a@test.com",
  "password": "abcde",
  "strategy": "local"
}
```

FeathersJS supports JSON authentication. Due to defaults configured for the service and the app itself, we see a default response from authentication request like so -

{
  "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFjY2VzcyJ9.eyJpYXQiOjE1Njg2OTY3NTMsImV4cCI6MTU2ODc4MzE1MywiYXVkIjoiaHR0cHM6Ly95b3VyZG9tYWluLmNvbSIsImlzcyI6ImZlYXRoZXJzIiwic3ViIjoidFUwTWNwNndFa0xTd1A0ZyIsImp0aSI6IjIxMDViMTVhLTdmMzUtNDA1ZS04NTk2LTQ4MWExNDdiMjNhNCJ9.6JhToJthfiSwtAGXQ7Qwtt4y14ACryvTU0gM9z30AbE",
  "authentication": {
    "strategy": "local"
  },
  "user": {
    "email": "a@test.com",
    "_id": "tU0Mcp6wEkLSwP4g"
  }
}

Copy the access token from the response.

Create/query to-do

We will go back to our to-do GET request and include the token. Submit the request again, and you will see the below response -

{
  "total": 0,
  "limit": 10,
  "skip": 0,
  "data": []
}

Cool..!

Now, create a to-do record, or two. Create a POST request to http://localhost:3030/todo.

{
  "title": "Install feathers",
  "completed": "true"
}

These records will be stored in the database we specified while configuring the service. If you accepted defaults, the database will be NeDB (a local datastore) and the data file will be present in /data/.

Experiment with other services.

Update to-do

Create a new request - PATCH http://localhost:3030/todo/1pRKub3hU6ft7YNE

Note that we used the id received from the earlier GET request in the URL.

Request -

{
  "title": "Rule the universe"
}

Response -

{
  "title": "Rule the universe",
  "completed": "false",
  "_id": "1pRKub3hU6ft7YNE"
}

Query single to-do

Create another request - GET http://localhost:3030/todo/1pRKub3hU6ft7YNE.

This request is very similar to the earlier GET but filters the results by applying the id used in URL.

{
  "title": "Rule the universe",
  "completed": "false",
  "_id": "1pRKub3hU6ft7YNE"
}

Delete to-do

Create yet another request - DELETE http://localhost:3030/todo/1pRKub3hU6ft7YNE

Request -

< no body >

Response -

{
  "title": "Rule the universe",
  "completed": "false",
  "_id": "1pRKub3hU6ft7YNE"
}

Take stock of what you did so far

Looking back - we just used two commands -

feathers g app todof
feathers g service todo

And, generated an awesome app that can support all REST operations for the specified entity!

Isn’t FeathersJS awesome?

But, don’t get teary-eyed yet. Feathers can do a lot more and we will get to those in a while :).

FeathersJS on Techformist

Learn FeathersJS by Building a Simple CRM - Client App

Building the Client Application

Client: Get Started

Router

Vuex

Views

Contact View - List Component

Contact Edit

Finis!

Learn FeathersJS by Building a Simple CRM App

Our Chosen Ecosystem

Server: Get Started

Server: Folder Structure

Server: Create new functionality

Create contact service

The Art of Models and Migration

Back to the Server

More migrations

More Entities and Functions

Change Users

Add Activities Model/Service

Finis

Unlock FeathersJS power with a todo client

Install and initialize project

Create HTML page

Initialize and configure feathers

Setup authentication

Display to-do’s

Create to-do

End result

Full code

Create a simple to-do API with FeathersJS

Install and initialize project

Start coding an API

Run your new API

Create user and authenticate

Create/query to-do

Update to-do

Query single to-do

Delete to-do

Take stock of what you did so far

Initialize and configure `feathers`