Mia service Node.js Library

This library is intended to ease the creation of new services to deploy on Mia-Platform.
Built on Fastify, it takes advantage of Mia-Platform Node.js service launcher lc39.

Getting Started

You can use this module in your projects or, from the DevOps Console, get started quickly and easily with a ready-to-use microservice template. Even in the Mia-Platform Marketplace repository, you can find some examples and templates that using this library.

Setup the local development environment

To develop the service locally you need:

Node.js v12 or later.

To setup node.js, we suggest using nvm, so you can manage multiple versions easily. Once you have installed nvm, you can go inside the directory of the project and simply run nvm install, the .nvmrc file will install and select the correct version if you don’t already have it.

Once you have all the dependency in place, you can launch:

npm i
npm run coverage

These two commands, will install the dependencies and run the tests with the coverage report that you can view as an HTML page in coverage/lcov-report/index.html.

Install module

To install the package with npm:

npm i @mia-platform/custom-plugin-lib --save

To install with Yarn:

yarn add @mia-platform/custom-plugin-lib

Define a Custom Service

You can define a new Custom Service that integrates with the platform simply writing this:

const customService = require('@mia-platform/custom-plugin-lib')()

module.exports = customService(async function helloWorldService(service) {
  service.addRawCustomPlugin('GET', '/hello', function handler(request, reply) {
    request.log.trace('requested myuser')
    // if the user is not logged, this method returns a falsy value
    const user = request.getUserId() || 'World'
    reply.send({
      hello: `${user}!`,
    })
  })
})

The library exports a function which creates the infrastructure ready to accept the definition of routes and decorators. Optionally can take a schema of the required environment variables, you can find the reference here. The function returned, customService, expects an async function to initialize and configure the service.
service is a Fastify instance, that is decorated by the library to help you interact with Mia-Platform resources. You can use service to register any Fastify routes, custom decorations and plugin, see here for a list of currently available plugins.
addRawCustomPlugin is a function that requires the HTTP method, the path of the route and a handler. The handler can also be an async function.
Optionally you can indicate the JSONSchemas to validate the querystring, the parameters, the payload and the response.

To get more info about Custom Services can you look at the related section.

Environment Variables configuration

To works correctly, this library needs some specific environment variables:

USERID_HEADER_KEY
USER_PROPERTIES_HEADER_KEY
GROUPS_HEADER_KEY
CLIENTTYPE_HEADER_KEY
BACKOFFICE_HEADER_KEY
MICROSERVICE_GATEWAY_SERVICE_NAME

When creating a new service from Mia-Platform DevOps Console, they come already defined but you can always change or add them anytime as described in the DevOps console documentation.
In local, the environment variables are defined in this file.

Other variables can be specified by setting your envSchema when calling the plugin.

Examples

You can see an advanced example to see different use cases of the library.

To see other examples of library use you can visit GitHub dependant repository graph and check all packages that depends on it.

To run the examples directly you can move to specific example folder and run:

npm run start:local

This command will launch the service on localhost:3000 with the environment variables defined in this file. Now you can consult the swagger documentation of the service at http://localhost:3000/documentation/.

mia-platform/custom-plugin-lib