Creating a Feathers Plugin

The easiest way to create a plugin is with the Yeoman generator.

First install the generator

  1. $ npm install -g generator-feathers-plugin

Then in a new directory run: 

  1. $ yo feathers-plugin

This will scaffold out everything that is needed to start writing your plugin.

Output files from generator: 

  1.    create package.json
  2.    create .babelrc
  3.    create .editorconfig
  4.    create .jshintrc
  5.    create .travis.yml
  6.    create src/index.js
  7.    create test/index.test.js
  8.    create README.md
  9.    create LICENSE
  10.    create .gitignore
  11.    create .npmignore

Simple right? We technically could call it a day as we have created a Plugin. However, we probably want to do just a bit more. Generally speaking a Plugin is a Service. The fun part is that a Plugin can contain multiple Services which we will create below. This example is going to build out 2 services. The first will allow us to find members of the Feathers Core Team & the second will allow us to find the best state in the United States.

Verifying our Service

Before we start writing more code we need to see that things are working. 

  1. $ cd example && node app.js
  3. Error: Cannot find module '../lib/index'

Dang! Running the example app resulted in an error and you said to yourself, “The generator must be broken and we should head over to the friendly Slack community to start our debugging journey”. Well, as nice as they may be we can get through this. Let’s take a look at the package.json that came with our generator. Most notably the scripts section. 

  1. "scripts": {
  2.     "prepublish": "npm run compile",
  3.     "publish": "git push origin && git push origin --tags",
  4.     "release:patch": "npm version patch && npm publish",
  5.     "release:minor": "npm version minor && npm publish",
  6.     "release:major": "npm version major && npm publish",
  7.     "compile": "rimraf lib/ && babel -d lib/ src/",
  8.     "watch": "babel --watch -d lib/ src/",
  9.     "jshint": "jshint src/. test/. --config",
  10.     "mocha": "mocha --recursive test/ --compilers js:babel-core/register",
  11.     "test": "npm run compile && npm run jshint && npm run mocha",
  12.     "start": "npm run compile && node example/app"
  13.   }

Back in business. That error message was telling us that we need to build our project. In this case it means babel needs to do it’s thing.
For development you can run watch

  1. $ npm run watch
  3. > creatingPlugin@0.0.0 watch /Users/ajones/git/training/creatingPlugin
  4. > babel --watch -d lib/ src/
  6. src/index.js -> lib/index.js

After that you can run the example app and everything should be good to go. 

  1. $ node app.js
  2. Feathers app started on 127.0.0.1:3030

Expanding our Plugin

Now that we did our verification we can safely change things. For this example we want 2 services to be exposed from our Plugin. Let’s create a services directory within the src folder.

  1. // From the src directory 
  2. $ mkdir services
  3. $ ls 
  4. index.js services

Now let’s create our two services. We will just copy the index.js file. 

  1. $ cp index.js services/core-team.js
  2. $ cp index.js services/best-state.js
  3. $ cd services && ls
  4. best-state.js core-team.js
  6. $ cat best-state.js
  8. if (!global._babelPolyfill) { require('babel-polyfill'); }
  10. import errors from 'feathers-errors';
  11. import makeDebug from 'debug';
  13. const debug = makeDebug('creatingPlugin');
  15. class Service {
  16.   constructor(options = {}) {
  17.     this.options = options;
  18.   }
  20.   find(params) {
  21.     return new Promise((resolve, reject) => {
  22.       // Put some async code here.
  23.       if (!params.query) {
  24.         return reject(new errors.BadRequest());
  25.       }
  27.       resolve([]);
  28.     });
  29.   }
  30. }
  32. export default function init(options) {
  33.   debug('Initializing creatingPlugin plugin');
  34.   return new Service(options);
  35. }
  37. init.Service = Service;

At this point we have index.js, best-state.js and core-team.js with identical content. The next step will be to change index.js so that it is our main file.

Our new index.js

  1. if (!global._babelPolyfill) { require('babel-polyfill'); }
  3. import coreTeam from './services/core-team';
  4. import bestState from './services/best-state';
  6. export default { coreTeam, bestState };

Now we need to actually write the services. We will only be implementing the find action as you can reference the service docs to learn more. Starting with core-team.js we want to find out the names of the members listed in the feathers.js org on github. 

  1. //core-team.js
  2. if (!global._babelPolyfill) { require('babel-polyfill'); }
  4. import errors from 'feathers-errors';
  5. import makeDebug from 'debug';
  7. const debug = makeDebug('creatingPlugin');
  9. class Service {
  10.   constructor(options = {}) {
  11.     this.options = options;
  12.   }
  14.   //We are only changing the find...
  15.   find(params) {
  16.     return Promise.resolve(['Mikey', 'Cory Smith', 'David Luecke', 'Emmanuel Bourmalo', 'Eric Kryski', 
  17.       'Glavin Wiechert', 'Jack Guy', 'Anton Kulakov', 'Marshall Thompson'])
  18.   }
  19. }
  21. export default function init(options) {
  22.   debug('Initializing creatingPlugin plugin');
  23.   return new Service(options);
  24. }
  26. init.Service = Service;

That will now return an array of names when service.find is called. Moving on to the best-state service we can follow the same pattern 

  1. if (!global._babelPolyfill) { require('babel-polyfill'); }
  3. import errors from 'feathers-errors';
  4. import makeDebug from 'debug';
  6. const debug = makeDebug('creatingPlugin');
  8. class Service {
  9.   constructor(options = {}) {
  10.     this.options = options;
  11.   }
  13.   find(params) {
  14.     return Promise.resolve(['Alaska']);
  15.   }
  16. }
  18. export default function init(options) {
  19.   debug('Initializing creatingPlugin plugin');
  20.   return new Service(options);
  21. }
  23. init.Service = Service;

Notice in the above service it return a single item array with the best state listed.

Usage

The easiest way to use our plugin will be within the same app.js file that we were using earlier. Let’s write out some basic usage in that file. 

  1. //app.js
  2. const feathers = require('feathers');
  3. const rest = require('feathers-rest');
  4. const hooks = require('feathers-hooks');
  5. const bodyParser = require('body-parser');
  6. const errorHandler = require('feathers-errors/handler');
  7. const plugin = require('../lib/index');
  9. // Initialize the application
  10. const app = feathers()
  11.   .configure(rest())
  12.   .configure(hooks())
  13.   // Needed for parsing bodies (login)
  14.   .use(bodyParser.json())
  15.   .use(bodyParser.urlencoded({ extended: true }))
  16.   // Initialize your feathers plugin
  17.   .use('/plugin/coreTeam', plugin.coreTeam())
  18.   .use('/plugin/bestState', plugin.bestState())
  19.   .use(errorHandler());
  22. var bestStateService = app.service('/plugin/bestState')
  23. var coreTeamService = app.service('/plugin/coreTeam')
  25. bestStateService.find().then( (result) => {
  26.   console.log(result)
  27. }).catch( error => {
  28.   console.log('Error finding the best state ', error)
  29. })
  31. coreTeamService.find().then( (result) => {
  32.   console.log(result)
  33. }).catch( error => {
  34.   console.log('Error finding the core team ', error)
  35. })
  37. app.listen(3030);
  39. console.log('Feathers app started on 127.0.0.1:3030');
  1. $ node app.js
  3. Feathers app started on 127.0.0.1:3030
  4. [ 'Alaska' ]
  5. [ 'Mikey',
  6.   'Cory Smith',
  7.   'David Luecke',
  8.   'Emmanuel Bourmalo',
  9.   'Eric Kryski',
  10.   'Glavin Wiechert',
  11.   'Jack Guy',
  12.   'Anton Kulakov',
  13.   'Marshall Thompson' ]

Testing

Our generator stubbed out some basic tests. We will remove everything and replace it with the following.

  1. import { expect } from 'chai';
  2. import plugin from '../src';
  4. const bestStateService = plugin.bestState()
  6. describe('bestState', () => {
  7.   it('is Alaska', () => {
  8.     bestStateService.find().then(result => {
  9.       console.log(result)
  10.       expect(result).to.eql(['Alaska']);
  11.       done();
  12.     });
  13.   });
  14. });
  1. $ npm run test

Because this is just a quick sample jshint might fail. You can either fix the syntax or change the test command. 

  2. $ npm run compile && npm run mocha

This should give you the basic idea of creating a Plugin for Feathers.