2. Tutorials
  3. hapi — How to Serve Static Files (Images, JS, CSS, etc.)

hapi — How to Serve Static Files (Images, JS, CSS, etc.)

Within the previous tutorial, you learned how to add routes to your application and handle requests with their related responses. When building web applications, the need to serve files arises quickly. And with that, you also need routes to respond requests with file resources. If you’re serving HTML views to your client, you might want to display images or provide JavaScript files to enhance the client side functionality.

This guide walks you through the setup of hapi to serve static files like images, JavaScript files, compressed archives (.zip, .tar, etc.).

Before diving into the details, have a look at the series outline and find posts that match your interests and needs.

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. 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. 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

Prepare Your Server

Hapi doesn’t ship with functionality to serve static files by default. That keeps the actual framework footprint small and you can add this feature easily by using the inert plugin. We also have tutorials that guide you through the extension hapi’s functionality using plugins and how to create your own custom hapi plugin.

Once you registered the inert plugin to your hapi server instance, it adds new handler methods to serve files and directories and also decorates the reply object with a file method to serve file resources.

hapi v17

const Hapi = require('hapi')

// create new server instance
const server = new Hapi.Server({  
  host: 'localhost',
  port: 3000
})

async function liftOff () {  
  await server.register({
    plugin: require('inert')
  })

  await server.start()
  console.log('Server started at: ' + server.info.uri)
}

liftOff()

hapi v16

var Hapi = require('hapi')

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

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

server.register({  
  register: require('inert')
}, function(err) {
  if (err) throw err

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

The snippet above just illustrates how to prepare your hapi server to serve static files from disk. Within the following sections, you’ll learn how to send files as response and serve files from a directory.

Send Any File (Images, JS, etc.)

When using HTML views, you probably want to define specific CSS or JS files that can be requested from your server. You may consume some of your 3rd party dependencies from CDN’s and others are shipped with your project locally. If you want to serve a specific file via a given route, define the filename including file extension as a route path. Afterwards, you can utilize the reply.file() method to serve the requested file from local disk.

In the following example, we’ve reduced the exemplary code snippet to just represent the route definition. The most interesting part is the handler function that responds the request using the reply.file() function and serves the mylocaljavascript.js file from the given file location on your server’s disc.

hapi v17

server.route({  
  method: 'GET',
  path: '/mylocaljavascript.js',
  handler: (request, h) => {
    // h.file() expects the file path as parameter
    return h.file('../path/to/my/localjavascript.js')
  }
})

hapi v16

server.route({  
  method: 'GET',
  path: '/mylocaljavascript.js',
  handler: function (request, reply) {
    // reply.file() expects the file path as parameter
    reply.file('../path/to/my/localjavascript.js')
  }
})

As already mentioned earlier, the reply.file() method expects the local file’s path as a parameter. Afterwards, hapi creates the response and returns the requested file (if found).

Serve Files From a Directory

With the help of inert, you can serve all files located in a selected directory. Using path parameters for a route definition, you’re able to just define a single route that serves a given type of requests. The following example defines a route that serves JS files for requests that come in at /js/<file>.

Actually, the path parameter name doesn’t matter. Using the asterisk extension does not restrict the file depth and allows you to make use of files located in subfolders. In case you only want to support root level files,remove the asterisk from the path.

server.route({  
  method: 'GET',
  path: '/js/{file*}',
  handler: {
    directory: { 
      path: 'public/js'
    }
  }
})

The directory handler simplifies the route configuration and you just need to provide the correct path to the local JS files on your server’s disk. Once your server receives a request to serve a specific JS file, inert looks up the defined path to find the requested file. If available, the file gets served as a response for the current request. If the file isn’t available at the specified location, your server responds with a 404 Not Found.

By default, inert doesn’t list the directory contents. If a file wasn’t found, you’ll receive a 404. Using the listing: true option besides the path property for a directory handler, you can define that any request to /js is able to list the contents of /public/js directory.

server.route({  
  method: 'GET',
  path: '/js/{file*}',
  handler: {
    directory: { 
      path: 'public/js',
      listing: true
    }
  }
})

The route snippet above allows users list the contents of your public/js folder. The listing property is false by default.

The directory handler has further options, like:

  • showHidden: that determines if hidden files can be served
  • redirectToSlash: determines that requests without trailing slash get redirected to the “with slash pendant”, which is useful for the resolution of relative paths
  • lookupCompressed: tells the file processor to search for the requested file in compressed .gz version
  • etagMethod: defines the method to calculate the ETag header. Please find more details about the directory options within the inert GitHub repository.

Outlook

That’s the foundation you need to serve various types of files for incoming requests. You’ve learned how to prepare and add the capabilities to respond with file resources using the inert plugin. Furthermore, you know that there are multiple options to respond file requests using either the reply.file() method or just define the path to a directory providing the actual files.

The next tutorial shifts direction to authentication and how to implement a cookie-based authentication and remember the users.

We appreciate feedback and love to help you if there’s a question on your mind. Let us know in the comments or on twitter @futurestud_io.

Make it rock & enjoy coding!

Additional Resources

  • inert — static file and directory handler plugin for hapi

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