2. Tutorials
  3. hapi — How to Run Separate Frontend and Backend Servers Within a Single Project

hapi — How to Run Separate Frontend and Backend Servers Within a Single Project

Building web apps require you to build a frontend for user interaction and a backend for data processing. Often, you’ll put both ends into one project and define routes which render web views.

At some point, you’ll want to add an API for mobile apps or third-party integrations. And with that, you need to expose additional API routes using HTTP verbs to create, read, update or delete documents. Now the project and complexity kind of messed up, because you’re exposing web routes and API routes from within the same server and need to handle them internally in complete separation.

Using hapi as your framework of choice offers the capability to create and run separate server connections from within one project. That means you can create the frontend server, add only the frontend routes, and register additional plugins. The same holds true for the API server.

We’ll guide you through the setup of multiple servers within one hapi project and show you how to configure each server separately.

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. 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. Extend Your Server Functionality With Plugins
  2. Create Your Own Custom Plugin
  3. How to Register Plugins for a Selected Server Instance
  4. hapi Plugin for Client Geo Location (by Future Studio 🚀)
  5. Increase Development Speed With Errors in the Browser or as JSON Response
  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

Why Should I Do That?

Actually, the split servers for frontend and API is just a preference, not a recommendation. We think it’s a good structure to separate the logic for frontend and backend. Often, the frontend uses different strategies for authentication than the backend. You’re possibly using a cookie based strategy within your frontend and a token based strategy for the API.

This way, you still have both *ends within your project. You can keep working on both sides when necessary and the context switch is likely smaller than two completely separated projects. Additionally, this approach reduces the complexity of two independent, isolated projects and deployments. Small scale setups will reuse core functionality within the backend to process data before returning the response via API or within a rendered view.

Start Multiple Hapi Servers Within One Project

You need a hapi server instance to define multiple incoming connections where the server should listen for requests. The following code shows the basic server definition including the two connection configurations to listen on ports 3000 and 3001 for requests.

Precisely, there is only one actual hapi server integrating two logical servers. The method to configure a server connection returns a server object. This server object for a given connection configuration can be customized with specific routes, plugins, functionality, and many more. 

var hapi = require('hapi');  
var port = 3000;  
var _ = require('lodash');

// Create hapi server instance
var server = new hapi.Server();

// add connection parameters
server.connection({  
    host: 'localhost',
    port: process.env.PORT || port
});

server.connection({  
    host: 'localhost',
    port: process.env.PORT + 1 || port + 1
});

// Start the server
server.start(function () {  
    // Log to the console the host and port info
    _.forEach(server.connections, function(connection) {
        console.log('Server started at: ' + connection.info.uri);
    });
});

If you want to run this code example above, initialize a new node project with npm init and install the hapi and lodash packages: 

mkdir hapi-multiple-servers && cd hapi-multiple-servers  
npm install hapi lodash  
nano index.js

Now copy and paste the contents above into your index.js file and save it. Ready to rumble? Start the server and you’ll see the logs that your server started on ports 3000 and 3001.

$ node index.js
Server started at: http://0.0.0.0:3000  
Server started at: http://0.0.0.0:3001

Within the code snippet above, we create a new hapi server instance with new hapi.Server() and add two connection configurations for incoming requests. Both connections listen on localhost and different ports. We use lodash to simplify the iteration through the server connections and just log the uri information for each connection.

Frontend and Backend Server in One Project

The example above shows you how to define multiple connection configurations where your server will be listening for requests. Now we will add different routes, register plugins and define a template engine for the split server connections.

Hapi’s server.connection([options]) method returns a server object with the new connection configuration defined. The options object is cloned deeply so you’re not gonna override them with definitions for other connections. Make sure you only use values that can be cloned deeply.

Let’s jump into the code. We’re going to explain the parts of frontend and backend below the snippet.

var hapi = require('hapi');  
var _ = require('lodash');  
var port = 3000;

// Create hapi server instance
var server = new hapi.Server();


/**
 * Frontend Server configuration
 **/

// add frontend connection parameters
var frontend = server.connection({  
    host: 'localhost',
    port: process.env.PORT || port,
    labels: 'frontend'
});

// add routes
frontend.route({  
    method: 'GET',
    path: '/',
    handler: function (request, reply) {
        return reply('Hello without HTML view');
    }
});

// register hapi-auth-cookie plugin
frontend.register(require('hapi-auth-cookie'), function (err) {  
    if (err) {
        throw err;
    }

    frontend.auth.strategy('session', 'cookie', {
        password: 'secretpassword',
        cookie: 'cookie-name',
        redirectTo: '/login',
        isSecure: false
    });
});

frontend.register(require('vision'), function (err) {  
    if (err) {
        throw err;
    }

    // register view template engine
    server.views({
        engines: {
            html: require('handlebars')
        }
    });
});

/**
 * Backend Server configuration
 **/

// add frontend connection parameters
var backend = server.connection({  
    host: 'localhost',
    port: process.env.PORT + 1 || port + 1,
    labels: 'backend'
});


// add backend-only route
backend.route({  
    method: 'GET',
    path: '/status',
    handler: function (request, reply) {
        return reply('ok');
    }
});

// register hapi-auth-jwt plugin only for backend
backend.register({  
    register: require('hapi-auth-jwt')
}, function (err) {
    if (err) {
        throw err;
    }

    backend.auth.strategy('token', 'jwt', {
        key: 'supersecretkey',
        validateFunc: function (decodedToken, callback) {
          console.log('jwt validate function')
        }
    });
});


// Start the server
server.start(function () {  
    // Log to the console the host and port info
    _.forEach(server.connections, function(connection) {
        console.log('Server started at: ' + connection.info.uri);
    });
});

We’ve tried to squeeze the snippet as much as we could to keep it understandable. Even though it’s kind of extensive, it show the capabilities defining multiple server connections.

First, we create a hapi server instance and afterwards add the connection settings for the frontend. Since the hapi connection method returns a new server object, we can do further configurations as we desire. We register handlebars as our template engine, add a route to the index / and register the hapi-auth-cookie plugin for the server. Since we only use cookies within the frontend, there is no need to also drag it into the backend.

For the backend, we configure a port offset of 1 respective the frontend to avoid the EADDRINUSE error. It’s not possible to listen on the same UDP/TCP ports for different servers. Afterwards, we add a single route /status and register the hapi-auth-jwt plugin. There is no need to configure a template engine, because we won’t render any views and respond in plain text or JSON.

That’s it, you just need to install the plugins and afterwards replace the content of your index.js file (if you created it before). Starting the server will log the same messages as before with the difference, that you’ve a clear split between your frontend and backend server.

npm install vision hapi-auth-jwt hapi-auth-cookie

$ node index.js
Server started at: http://localhost:3000  
Server started at: http://localhost:3001

There Is a Dark Side

You can’t deploy changes to either frontend or backend without accepting a downtime for both. Internally, hapi handles the logical frontend and backend servers encapsulated within an overall server object. When starting the node process to kick off the hapi server, it automatically boots up the frontend and backend. Making changes to either of them will result in a restart of the overall hapi server and implies a downtime for both.

Conclusion

This articles shows you how to set up two servers within a single hapi project. Of course you can add further connection configurations to spin up more servers and listen on additional ports for incoming requests.

Defining two servers for different tasks allows you to slim down the functionality of either of them. You can focus on just the needed functionality, plugins, and routes for each of them and implement just what’s required.

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