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.
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.
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 coverageThese 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.
To install the package with npm:
npm i @mia-platform/custom-plugin-lib --saveTo install with Yarn:
yarn add @mia-platform/custom-plugin-libYou 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 theservice. -
serviceis 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. -
addRawCustomPluginis 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.
To works correctly, this library needs some specific environment variables:
USERID_HEADER_KEYUSER_PROPERTIES_HEADER_KEYGROUPS_HEADER_KEYCLIENTTYPE_HEADER_KEYBACKOFFICE_HEADER_KEYMICROSERVICE_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.
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:localThis 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/.