2. Tutorials
  3. hapi — How to Upload Files

hapi — How to Upload Files

Web application development with hapi allows you to build with rapid speed. Many boilerplates exist and provide the fundamental structure with functionality for user handling, view template management and more. That means you can jumpstart right into the nitty gritty development of your application.

And of course in these social times, you need the handling of files in your app! Every user on your platform wants to upload their preferred profile picture or any kind of file based resources.

This tutorial shows you how to handle file uploads with hapi.

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

Upload File and Additional Data

Usually, you’re not just sending a file and that’s it. You want to allow additional data besides the file within the request payload. That’s totally fine, hapi got your back and allows that without any problems.

Let’s take the description from the previous paragraph and allow profile updates including a new avatar for the user. What you want is a (POST or PUT) route for profile updates. Also, you want to define how payload will be handled for the route, especially requests including a file. Take a look at the following code snippet and you’ll get further descriptions below.

hapi v17

server.route({  
  method: 'PUT',
  path: '/profile',
  config: {
    handler: (request, h) => {
      const payload = request.payload

      console.log(payload)

      return 'Received your data'
    },
    payload: {
      maxBytes: 209715200,
      output: 'file',
      parse: true
    }
  }
})

hapi v16

server.route({  
  method: 'PUT',
  path: '/profile',
  config: {
    handler: function (request, reply) {
      const payload = request.payload

      console.log(payload)

      reply('Received your data')
    },
    payload: {
      maxBytes: 209715200,
      output: 'file',
      parse: true
    }
  }
})

The route’s handler simply accesses and logs the incoming data within the request’s payload and replies with “Received your data“. More interesting is the config.payload object, containing the maxBytes, output and parse properties.

With maxBytes you define the maximum payload size in bytes that your hapi server allows to handle and keep in memory. This value defaults to 1048576, which is 1 MB.

The output controls whether you keep the file in memory, a temporary file or receive the file as a stream:

  • data: the complete file is in memory as a buffer
  • file: write the incoming file in a temporary one before doing further work
  • stream: file is available as a stream

The parse property determines if the incoming payload gets parsed (true, default) or presented raw (false).

Assuming that we do an exemplary PUT request to the route from above with values for username and avatar, you’d expect the following console output.

{ username: 'marcus',
  avatar: { 
    filename: 'marcus_avatar.jpg',
    path: '/var/folders/cq/143/T/146-20-dab',
    headers: { 
      'content-disposition': 'form-data; name="avatar"; filename="marcus_avatar.jpg"',
      'content-type': 'image/jpeg'
    },
    bytes: 82521
  }
}

You can see that there are two properties within the request payload: username and avatar. The chosen file output for the avatar writes the picture in a temporary file first and you can now do further processing using the file’s path and original filename.

Depending on your use case, you might want to copy and rename the file to a specific location or upload to a cloud storage like Amazon S3.

We’ve mentioned the data value for config.payload.output that keeps the complete file in memory, available as a buffer:

hapi v17

server.route({  
  method: 'POST',
  path: '/profile-data',
  config: {
    handler: (request, reply) => {
      console.log(request.payload)
    },
    payload: {
      output: 'data',
    }
  }
})

hapi v16

server.route({  
  method: 'POST',
  path: '/profile-data',
  config: {
    handler: function (request, reply) {
      console.log(request.payload)
      reply()
    },
    payload: {
      output: 'data',
    }
  }
})

Notice that the value for config.payload.output is set to data which will keep the complete file in memory! This configuration is not suitable for uploads containing large files. If you don’t plan to allow files larger than one megabyte, you can skip the maxBytes configuration. The request payload gets parsed by default.

Sending a sample request to /profile-data and logging the parsed request payload results in this output:

{ username: 'marcus',
  pictures: <Buffer ff d8 ff ... > }

In comparison to the temporary file, you don’t need to read the file again from your server’s file system, but instead make use of its buffer right from memory.

As mentioned above, you want to keep the memory impact low and also don’t store every uploaded file in a temporary one. That’s where you should leverage streams. If you want to go this route, read the next section!

Upload Data and File As Stream

When working with files of large size, you should depend on streams as the upload output. Of course you can choose stream for any file size and not just larger ones. If you want a stream, you get it! The following code snippet outlines the configuration to tell hapi you want a read stream of the uploaded file.

The stream configuration only applies to files, further information within the request payload are available as usual within the parsed object.

hapi v17

server.route({  
  method: 'POST',
  path: '/upload-stream',
  config: {
    handler: (request, h) {
      const payload = request.payload

      console.log(payload)

      return 'I have a stream'
    },
    payload: {
      output: 'stream',
      parse: true
    }
  }
})

hapi v16

server.route({  
  method: 'POST',
  path: '/upload-stream',
  config: {
    handler: function (request, reply) {
      const payload = request.payload

      console.log(payload)

      reply('I have a stream')
    },
    payload: {
      output: 'stream',
      parse: true
    }
  }
})

The route handler at path /upload-stream logs the request payload and replies a simple text „I have a stream“. The interesting part is the config.payload object that specifies the payload handling. You need to define output: 'stream' and hapi provides incoming files as a stream. Take a look at the console log for an exemplary request payload containing a username as string and avatar as JPG:

{ username: 'marcus',
  avatar:
   Readable {
     _readableState:
      ReadableState {
      …
     _encoding: 'utf8',
     hapi:
      { filename: 'marcus_avatar.jpg',
        headers: [Object] } } }

I’ve shortened the output above to show the interesting parts. At first the two fields that came in from client side: username and avatar. And second, please notice the hapi object on avatar that contains the filename and headers properties. The hapi property is only available for file streams from multipart/form-data uploads.

Now that you’ve the avatar available as a stream, you can use it as simply as:

payload.avatar.pipe(anotherStream)

Pipe the data into another stream and do your desired processing.

Up to this point, you’ve learned how to handle file uploads where a single file is either available in memory, in a temporary file or as a stream. If you want to upload multiple files simultaneously, the next section is for you!

Upload Multiple Files

At this point, you already know how to handle a single incoming file within the request payload using hapi. There are already use cases in your head that would require the option to upload multiple files from a client. And of course hapi got you covered for this situation.

Actually, there’s no difference in the route configuration for a single or multiple files. The only difference is the property that hapi will provide the request payload. When sending multiple files using the same key, hapi will provide a list that contains the individual files.

Depending on the output defined on your route in config.payload, you’ll either receive the files as buffers, temporary ones or streams. The defined output is applied to all the incoming files.

The following parsed object illustrates a sample request containing the username property and three pictures where each picture is stored in a temporary file:

{ username: 'marcus',
  pictures:
   [ { filename: 'Bildschirmfoto 2015-12-18 um 15.11.50.png',
       path: '/var/folders/rq/q_m4_21j3lqf1lw48fqttx_80000gn/T/1487606162810-29302-4f33a879f7284deb',
       headers: [Object],
       bytes: 127331 },
     { filename: 'Bildschirmfoto 2016-01-09 um 16.03.00.png',
       path: '/var/folders/rq/q_m4_21j3lqf1lw48fqttx_80000gn/T/1487606162821-29302-c4441f06b0d68939',
       headers: [Object],
       bytes: 167728 },
     { filename: 'Bildschirmfoto 2015-12-18 um 14.54.43.png',
       path: '/var/folders/rq/q_m4_21j3lqf1lw48fqttx_80000gn/T/1487606162811-29302-40c773ae9e63e73e',
       headers: [Object],
       bytes: 157733 } ] }

The option used in the code snippet above is output: 'file' which makes each individual picture from the pictures array available in a temporary file. In case you’d want each picture as a stream (output: 'stream'), the entries within the pictures array would be Readable streams, ready for further processing. The same holds true for output: 'data' where you’d receive a buffer for each picture.

Outlook

In this tutorial, you’ve learned the details about file uploads in hapi and available output options. Depending on your use case, you need to decide between files completely in memory, a temporary file or as a stream. Choose what fits you best and benefit from the simplicity hapi provides for the file uploads.

We’re happy to hear your thoughts and comments. Please don’t hesitate to use the comments below or find us on Twitter @futurestud_io. Let us know what you think!

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