2. Tutorials
  3. hapi — Create Your Own Custom Plugin

hapi — Create Your Own Custom Plugin

This guide continues on extending your server’s functionality with the help of plugins. Within the previous tutorial, you’ve learned how to register a plugin to your hapi server instance and with that increase the servers feature set. Also, we’ve described hapi’s efficient plugin system and the unwritten best practice to split your application logic into various small, isolated modules.

Now it’s time to learn how to write your own plugin that adds your desired functionality to hapi. Due to the extensiveness of this hapi series, have a look at the series outline below to find other interesting guides.

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

Write a Plugin

Based on the fact that it’s recommended to extend your servers functionality using plugins, there should be a convenient way to write your own, custom one. Essentially, a plugin is an object with a register property that returns a function with the signature function (server, options, next). Further, the register function has an attributes object that contains meta data about your plugin to provide some extra data for hapi. The attributes can be something like name and version.

var myplugin = {  
  register: function (server, options, next) {
    // add functionality -> we’ll do that in the section below

    // call next() to signal hapi that your plugin has done the job
    next()
  }
}

myplugin.register.attributes = {  
  name: 'myplugin',
  version: '1.0.0'
}

module.exports = myplugin

We’ve mentioned that the register function of your plugin takes three arguments server, options and next. Let’s review each of them: server is the reference instance to your server that you’re going to extend (like adding route handlers to render views or reply in other formats) or just use it to call server methods. The options object contains plugin specific configuration that is required to run your plugin appropriately.

At last, you have to call next to signal hapi that you’ve registered or configured the desired functionality and your plugin is done. You can also call asynchronous methods while registering your plugin. Just use the next function at the right spot, like within the callback or promise.

Up to this point, you’ve seen the basics of how to write a custom plugin. Let’s make things more approachable and add a route handler within our custom plugin.

Add Functionality Within Your Custom Plugin

Within the getting started tutorial of this hapi series, we’ve created a basic hapi server that sends a Hello Future Studio! message when calling the default / route. The code below illustrates the mentioned server code:

var Hapi = require('hapi')

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

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

// add “hello world” route
server.route({  
  method: 'GET',
  path: '/',
  handler: function (request, reply) {
    reply('Hello Future Studio!')
  }
})

// start your server
server.start(function (err) {  
  if (err) {
    throw err
  }

  console.log('Server running at: ' + server.info.uri)
})

In the following, you’ll refactor the shown code above and create your own plugin that registers the route handler and responds with the Hello Future Studio! message. Alright, let’s get going.

First, create a file called base-route.js that will add a GET route at path / and replies with the given message.

base-route.js

var baseRoutes = {  
  register: function (server, options, next) {
    // add “hello world” route
    server.route({
      method: 'GET',
      path: '/',
      handler: function (request, reply) {
        reply('Hello Future Studio!')
      }
    })

    next()
  }
}

baseRoutes.register.attributes = {  
  name: 'base-routes',
  version: '1.0.0'
}

module.exports = baseRoutes

As you can see, we’re extending the server instance by registering the route. Of course, you could enhance the route’s handler method with additional functionality. For now, let’s just focus on the refactoring part and create your first plugin. Because the server.route() method is a synchronous operation, we can add the next call right after the route registration.

Within the servers.js file, you need to remove the previously defined route registration and register the newly created plugin. If you need to recap on how to load plugins to your hapi server, have a look at the linked tutorial.

server.js

var Hapi = require('hapi')

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

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

// register plugins to server instance
server.register({  
  register: require('./base-route')
})

// start your server
server.start(function (err) {  
  if (err) {
    throw err
  }

  console.log('Server running at: ' + server.info.uri)
})

Within the snippet above, you can see the call of server.register() to add your plugin to the hapi server instance and with that, add the handler to respond any GET requests on route path /. We aren’t using any plugin options, that’s why we don’t pass them during the register phase.

To check if everything went smooth, start your server instance and open the browser or use curl to call localhost:3000. You should receive the Hello Future Studio! message.

Outlook

This tutorial walked you through the fundamentals on how to create your custom hapi plugin. You’ve also created your own plugin that registers a route handler to respond a request with a message. Use this basis and extend your plugins to provide the desired functionality and extend the server capabilities.

Within the next guide, you’ll get a grasp on how to render and serve beautiful views.

If you’ve any question, please let us know in the comments below or reach out at Twitter, @futurestud_io.

Enjoy coding & make it rock!

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