2. Tutorials
  3. hapi — Increase Development Speed With Errors in the Browser or as JSON Response

hapi — Increase Development Speed With Errors in the Browser or as JSON Response

Developer tools are a minefield. We’re so picky about the tools we use and require a high quality or don’t even consider them. You have an ingrained workflow if you’re like me, you behave like a robot when starting your programming.

Being open and willing to improve your developer life is an essential skill. There’s always room for improvement and another shortcut to learn. In hapi, you’ve certainly seen the „fuzzy“ default Internal Server Error for bad implementations. You have to look at the command line to get a grasp on the actual issue.

We’ve developed hapi-dev-errors to skip the command line lookup. You’ll increase your productivity by using this elegant and expressive error view in the browser:

Better error details with hapi-dev-errors

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

Installation

Install hapi-dev-errors with NPM and save the plugin as a project dependency.

# NPM v4 and below
# you’re using NPM shortcuts to (i)nstall and (-S)ave the module as a dependency
npm i -S hapi-dev-errors

# NPM v5 users, please this way
npm i hapi-dev-errors

If you’re more into the Yarn package manager, you can use it as well.

Usage

There’s one important thing: hapi-dev-errors is turned off by default.

You need to explicitly activate it by using the showErrors option and passing a value that evaluates to a boolean true. Our recommendation is to activate the plugin based on your NODE_ENV environment variable. Make sure to not activate it in production.

await server.register({  
  plugin: require('hapi-dev-errors'),
  options: {
    showErrors: process.env.NODE_ENV !== 'production'
  }
})

In production environments, hapi uses its default error handling. In case you’re changing the behavior for developer errors with HTTP status code 500, hapi-dev-errors won’t interfere. The request will is passed through without touching it.

Plugin Registration Options

At this point, there are three options that can adjust the plugin’s behavior.

  • showErrors: (boolean), default: false — activate the plugin by passing a “truthy” value when registering the plugin
  • useYouch: (boolean), default: false — use Youch to handle and display the error instead of using hapi-dev-error’s default handling
  • template: (string), no default — pass the template name that you want to render with reply.view(template, errorData)
await server.register({  
    plugin: require('hapi-dev-errors'),
    options: {
        showErrors: process.env.NODE_ENV !== 'production',
        useYouch: true,
        template: 'my-error-template'
    }
})

// do the heavy lifting :)

All three options apply to requests that don’t have the Accept header set to application/json. If you’re developing your API with hapi, make sure to set the Accept: application/json HTTP header and you’ll receive a JSON object with error details.

In case you’re activating all three options at the same time, hapi-dev-errors prioritizes the error handling as follows:

  1. JSON
  2. template
  3. Youch
  4. default error handling

JSON is always the first choice. Your custom template comes next and you can delegate the error handling to Youch if you wish.

Pretty Error Handling

The following pictures illustrate the different views and responses to handle errors.

default hapi-dev-errors template hapi-dev-errors default template

hapi-dev-errors using Youch use Youch as error handler

You can also benefit from a custom view template that matches the layout of your web app.

hapi-dev-errors custom view template use a custom view template

In the following section, you’ll find all properties that are available in your custom view.

Before moving on to custom error templates, let’s look at the JSON response from hapi-dev-errors.

hapi-dev-errors JSON response Prefer JSON? No problem.

Use Your Custom Error Template

hapi-dev-errors supports the template option while registering the plugin. Provide a template name to use your personal error template and not the default one shipped with hapi-dev-errors. In case you pass a string value for the template name, the view will be rendered with reply.view(template, errorData).code(500).

Available properties to use in your custom error view:

  • title: error title like Internal Server Error
  • statusCode: HTTP response status code (always 500)
  • message: error message, like Uncaught error: reply.view(...).test is not a function
  • method: HTTP request method, like GET
  • url: URL request path, like /signup
  • headers: HTTP request headers object, in key-value format GET
  • payload: HTTP request payload, only available for HTTP methods other than GET, in key-value format
  • stacktrace: error stacktrace

Depending on the rendering engine, make use of view helper functions or JavaScript snippets to manipulate the data to your needs.

Do You Want a Feature?

Do you miss a feature? Please use the GitHub issues to create your feature request with a short description of your desired addition to this plugin.

Did you find an issue with the plugin itself, please use the GitHub issues as well :)

Outlook

Improve your development flow by showing error details for bad implementations directly in the browser. Besides a nice looking web view, you can get extensive error details as a JSON response by using the Accept: application/json HTTP header.

We appreciate your feedback and would love if you leave us a comment below or tweet on Twitter @futurestud_io.

Make it rock & enjoy coding!

Mentioned Resources

  • hapi-dev-errors to return better error details and skip the look at command line to catch the issue
  • Youch — pretty error reporting in Node.js

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