2. Tutorials
  3. hapi — Extend Your Server Functionality With Plugins

hapi — Extend Your Server Functionality With Plugins

Within last week’s tutorial, you’ve learned how to get your first hapi server up and running. This guide will continue on that basis and you’ll extend the server’s functionality by adding a plugin that enhances log output. Actually, it’s important to understand hapi’s powerful plugin system, because it allows you to break your application down into smaller, independent modules. However, we’ll get to that in a second.

Before moving on, have a look at other posts within this series, there might be a good catch.

hapi Series Overview

  1. Get Your Server Up and Running
  2. v17 Upgrade Guide (Your Move to async/await)
  3. Become a Better Developer in 2018
  4. Become a Better Developer in 2017
  1. What You’ll Build
  2. Prepare Your Project: Stack & Structure
  3. Environment Variables and Storing Secrets
  4. Set Up MongoDB and Connect With Mongoose
  5. Sending Emails in Node.js
  6. Load the User’s Profile Picture From Gravatar Using Virtuals in Mongoose
  7. Implement a User Profile Editing Screen
  8. Generate a Username in Mongoose Middleware
  9. Displaying Seasons and Episodes for TV Shows with Mongoose Relationship Population
  10. Implementing Pagination for Movies
  11. Implement a Watchlist
  12. Create a Full Text Search with MongoDB
  1. Create a REST API with JSON Endpoints
  2. Update Mongoose Models for JSON Responses
  3. API Pagination for TV Shows
  4. Customize API Endpoints with Query Parameters
  5. Always Throw and Handle API Validation Errors
  6. Advanced API Validation With Custom Errors
  7. Create an API Documentation with Swagger
  8. Customize Your Swagger API Documentation URL
  9. Describe Endpoint Details in Your Swagger API Documentation
  10. 10 Tips on API Testing With Postman
  11. JWT Authentication in Swagger API Documentation
  12. API Versioning with Request Headers
  1. IP-Based Rate Limits (Part 1 of 7)
  2. Rate Limits for Routes (Part 2 of 7)
  3. Dynamic Rate Limits (Part 3 of 7)
  4. Render a “Rate Limit Exceeded” View (Part 4 of 7)
  5. Show “Rate Limit Exceeded” Error on Login (Part 5 of 7)
  6. Disable Rate Limiting (Part 6 of 7)
  7. Rate Limiter Refactoring & Cleanup (Part 7 of 7)
  1. API Login With Username and Password to Generate a JWT
  2. JWT Authentication and Private API Endpoints
  3. Refresh Tokens With JWT Authentication
  4. Create a JWT Utility
  5. JWT Refresh Token for Multiple Devices
  6. Check Refresh Token in Authentication Strategy
  7. Rate Limit Your Refresh Token API Endpoint
  8. How to Revoke a JWT
  9. Invalidate JWTs With Blacklists
  10. JWT Logout (Part 1/2)
  11. JWT “Immediate” Logout (Part 2/2)
  12. A Better Place to Invalidate Tokens
  13. How to Switch the JWT Signing Algorithm
  14. Roll Your Own Refresh Token Authentication Scheme
  15. JWT Claims 101
  16. Use JWT With Asymmetric Signatures (RS256 & Co.)
  17. Encrypt the JWT Payload (The Simple Way)
  18. Increase JWT Security Beyond the Signature
  19. Unsigned JSON Web Tokens (Unsecured JWS)
  20. JWK and JWKS Overview
  21. Provide a JWKS API Endpoint
  22. Create a JWK from a Shared Secret
  23. JWT Verification via JWKS API Endpoint
  24. What is JOSE in JWT
  25. Encrypt a JWT (the JWE Way)
  26. Authenticate Encrypted JWTs (JWE)
  27. Encrypted and Signed JWT (Nested JWT)
  28. Bringing Back JWT Decoding and Authentication
  29. Bringing Back JWT Claims in the JWT Payload
  1. How to Run Separate Frontend and Backend Servers Within a Single Project
  2. How to Use Server Labels
  3. How to Correctly Stop Your Server and Close Existing Connections
  1. Basic Authentication With Username and Password
  2. Authentication and Remember Me Using Cookies
  3. How to Set a Default Authentication Strategy
  4. Define Multiple Authentication Strategies for a Route
  5. Restrict User Access With Scopes
  6. Show „Insufficient Scope“ View for Routes With Restricted Access
  7. Access Restriction With Dynamic and Advanced Scopes
  8. hapi - How to Fix „unknown authentication strategy“
  9. Authenticate with GitHub And Remember the Login
  10. Authenticate with GitLab And Remember the User
  11. How to Combine Bell With Another Authentication Strategy
  12. Custom OAuth Bell Strategy to Connect With any Server
  13. Redirect to Previous Page After Login
  14. How to Implement a Complete Sign Up Flow With Email and Password
  15. How to Implement a Complete Login Flow
  16. Implement a Password-Reset Flow
  1. Views in hapi 9 (and above)
  2. How to Render and Reply Views
  3. How to Reply and Render Pug Views (Using Pug 2.0)
  4. How to Create a Dynamic Handlebars Layout Template
  5. Create and Use Handlebars Partial Views
  6. Create and Use Custom Handlebars Helpers
  7. Specify a Different Handlebars Layout for a Specific View
  8. How to Create Jade-Like Layout Blocks in Handlebars
  9. Use Vue.js Mustache Tags in Handlebars Templates
  10. How to Use Multiple Handlebars Layouts
  1. Route Handling and Drive Traffic to Your Server
  2. How to Serve Static Files (Images, JS, CSS, etc.)
  3. How to Use Query Parameters
  4. Optional Path Parameters
  5. Multi-Segment/Wildcard Path Parameters
  6. Ignore Trailing Slashes on Route Paths
  7. How to Fix “Unsupported Media Type”
  1. How to Access and Handle Request Payload
  2. Access Request Headers
  3. How to Manage Cookies and HTTP States Across Requests
  4. Detect and Get the Client IP Address
  5. How to Upload Files
  6. Quick Access to Logged In User in Route Handlers
  7. How to Fix “handler method did not return a value, a promise, or throw an error”
  8. How to Fix “X must return an error, a takeover response, or a continue signal”
  1. How to Reply a JSON Response
  2. How to Set Response Status Code
  3. How to Handle 404 Responses for Missing Routes
  1. Query Parameter Validation With Joi
  2. Path Parameter Validation With Joi
  3. Request Payload Validation With Joi
  4. Validate Query and Path Parameters, Payload and Headers All at Once on Your Routes
  5. Validate Request Headers With Joi
  6. Reply Custom View for Failed Validations
  7. Handle Failed Validations and Show Errors Details at Inputs
  8. How to Fix AssertionError, Cannot validate HEAD or GET requests
  1. Add CSRF Protection on Forms and API Endpoints
  1. Report Errors to Sentry
  2. Don’t Report Errors to Sentry in Development Mode
  3. Logging Fundamentals
  4. Log to Console With Good
  5. Log to File With Good
  1. Getting Started With Testing Using Lab and Code
  2. Run Tests with Assertions using Code
  3. Test Route Handlers by Injecting Requests
  4. Inject Request Payload, Headers and Parameters While Testing Route Handlers
  1. Zero-Downtime Deployments Using PM2

Make Use of hapi’s Plugin System

hapi ships with an extensive and powerful plugin system right away. Actually, it’s an unwritten best practice to break your application into isolated chunks of functionality and reusable utilities. Optimally, you can break down your application into individual plugins and the hapi server instances just provides the required configuration.

Add Console Output as a Plugin

Process monitoring can be an essential part of your application to listen on server events to identify the data flow within your application and individual states. Further, it can be used to provide proper console logs. There’s a process monitoring plugin for hapi, called good, and you’ll use it to listen in server events. Additionally, you’ll use a reporter plugin —good-console— to output data for selected events to the console.

Starting Point

As a basis for the upcoming examples, create a simple hapi server listening on localhost with port 3000.

var Hapi = require('hapi')

// create new server instance
var server = new Hapi.Server()

// add server’s connection information
server.connection({  
  host: 'localhost',
  port: 3000
})

That’s the starting point and you’ll extend that server by adding a plugin as described in the following paragraph.

Load a Plugin to Your Server Instance

The hapi server instance provides a register(server, options, next) method that excepts either a single plugin or a list of plugins. The method signature for register() outlines the server instance itself and as a second parameter, an options object. Of course, each plugin requires its own options and has a different schema. Just have a look at the plugin’s documentation to know what options you need to provide.

Generally, you can easily add a plugin like this:

// shortcut to register a plugin to hapi’s server instance
server.register(require('my-plugin'))

Further, you’ve the ability to add a callback function as the last parameter for the server.register() method. However, if your plugin doesn’t require any options, you can just pass it to hapi’s server and extend its default functionality.

In a later tutorial, we’ll go in detail on how to create your own custom plugin. For now, we’ll use the existing good plugin from hapi’s ecosystem and register it to the server. Besides good, we’ll define good-console as a reporter within the good plugin’s options.

The snippet above showed you how to easily register a plugin to your hapi server instance. There are situations where your plugin needs application specific configuration or options and you want them to pass during the plugin registration phase. Actually, that’s also available using the register() method by passing an object that provides two fields: register and options.

The following code block illustrates the registration of the good plugin within the server.register({…}) method. 

var Good = require('good')

// register plugins to server instance
server.register({  
  register: Good,
  options: {
    reporters: [{
      reporter: require('good-console'),
      events: {
        response: '*',
        log: '*'
      }
    }]
  }
})

As you can see, if you want to pass further options to your plugin, use the method shown in the code above. The good plugin requires and receives further options and we define good-console as the console output for the server events of response and log. That means, using the server.log method will trigger the log event and good outputs the provided data to the command line.

At this point, you may ask yourself: it’s recommended to break down the application code into plugins, is there a way to register multiple plugins at once to avoid having lots of server.register statements? In short: yep, hapi got your back!

Load Multiple Plugins at the Same Time to Your Server

Actually, hapi allows you to load either one or many plugins at the same time using the register() method. Of course, you can use the ways as already described above to add a plugin. the following code block outlines the three ways to import plugins into hapi’s server instance.

var Good = require('good')

// register multiple plugins at once to server instance
server.register([  
  {
    register: require('good'),
    options: {
      reporters: [ {
        reporter: require('good-console'),
        events: { log: '*', response: '*' }
      } ]
    }
  },
  // register plugin without options #1
  {
    register: require('my-plugin')
  },
  // register plugin without options #2
  require('another-plugin')
])

Please note that you need to provide a list of plugins for the server.register() method to add multiple at the same time. Within the list, you can either define an object having at least the register field defined and optionally providing options. Further, you can just pass the plain plugin by requiring it right away.

Impact of Good Plugin to the Server

Up to this point, you’ve learned how to register the good plugin to your server. Let’s explore the changes when applying the plugin for use. The example code for this tutorial is available on GitHub and we recommend to check it out on your own.

In the following, you’ll see the difference between the console outputs with and without using the good plugin.

Before

// start hapi server
server.start(function (err) {  
  console.log('Server running at: ' + server.info.uri)
})

Console output:

$ node server.js
Server running at: http://localhost:3000

After

// start hapi server
server.start(function (err) {  
  server.log('info', 'Server running at: ' + server.info.uri)
})

Console output:

$ node server.js
160411/102456.564, [log,info], data: Server running at: http://localhost:3000

Leveraging good allows you to keep track of fine grained information and especially the output importance. Using just console.log(msg) won’t put any priority to the information, but using server.log('info', msg) or server.log('error', msg) indicates directly the difference between each of the log messages.

That’s just the tip of the logging iceberg and actually it’s not the priority of this post. The important take away is to understand how you register plugins to hapi.

Outlook

This tutorial guided you through the required knowledge to import existing or custom plugins. You’ve learned how to register one or many plugins to your hapi server instance and besides that, how to pass plugin specific options during registration phase.

We’ve mentioned at the beginning of this post, that it’s best practice to create custom plugins for the functionality of your application. Within the next post, you’ll learn how to create your own custom plugin to extend the server’s functionality.

If you feel there’s anything missing in this guide, please let us know in the comments below or send us a tweet @futurestud_io

Enjoy coding & make it rock!

Additional Resources

Marcus Pöhls

Marcus is a fullstack JS developer. He’s passionate about the hapi framework for Node.js and loves to build web apps and APIs. Creator of Futureflix and the “learn hapi” learning path.

Explore the Library

Find interesting tutorials and solutions for your problems.

Android

Node.js

Server

Miscellaneous