content-disposition vs content-type vs http-errors vs mime vs mime-types vs type-is
HTTP Header and MIME Type Utilities for Node.js
Search packages..
content-dispositioncontent-typehttp-errorsmimemime-typestype-isSimilar Packages:

HTTP Header and MIME Type Utilities for Node.js

These packages provide focused utilities for working with HTTP headers, MIME types, and error responses in Node.js applications. content-disposition and content-type parse and format specific HTTP headers. http-errors creates standard HTTP error objects with appropriate status codes and messages. mime and mime-types handle MIME type lookups and extensions, while type-is checks request content types against expected values. Together, they form a foundational toolkit for building robust HTTP servers and middleware.

Npm Package Weekly Downloads Trend

3 Years

Github Stars Ranking

Stat Detail

Package
Downloads
Stars
Size
Issues
Publish
License
content-disposition90,884,79323819.2 kB154 months agoMIT
content-type014310.5 kB63 years agoMIT
http-errors01,55519.1 kB164 months agoMIT
mime02,352161 kB16 months agoMIT
mime-types01,45422.9 kB204 months agoMIT
type-is022721.3 kB13a year agoMIT

HTTP Header and MIME Type Utilities: A Practical Guide for Node.js Developers

When building HTTP servers or middleware in Node.js, you'll frequently encounter tasks like parsing headers, validating content types, generating proper error responses, and mapping file extensions to MIME types. The six packages in this comparison (content-disposition, content-type, http-errors, mime, mime-types, and type-is) each solve specific problems in this space with minimal, focused APIs. Let's explore how they work together and when to use each one.

📥 Content-Disposition: Safe File Downloads

The content-disposition package handles the Content-Disposition header, which tells browsers how to handle responses — particularly for file downloads.

Why not DIY? Manually constructing this header is risky because filenames can contain characters that break header parsing or enable response splitting attacks.

// Using content-disposition
const contentDisposition = require('content-disposition');

// Safe filename handling with proper encoding
const header = contentDisposition('résumé.pdf');
// Returns: 'inline; filename="resume.pdf"; filename*=UTF-8\'\'r%C3%A9sum%C3%A9.pdf'

// For attachments (downloads)
const attachmentHeader = contentDisposition('report.xlsx', { type: 'attachment' });

Without this package, you'd need to implement RFC 6266 compliance yourself, including UTF-8 encoding for international filenames and proper escaping.

🏷️ Content-Type: Parsing Media Types Correctly

The content-type package parses and formats Content-Type headers according to RFC 7231.

Why not DIY? Content-Type headers can include parameters (like charset=utf-8) and have subtle parsing rules around case sensitivity and whitespace.

// Using content-type
const contentType = require('content-type');

// Parsing a header
const parsed = contentType.parse('text/html; charset=utf-8');
// Returns: { type: 'text/html', parameters: { charset: 'utf-8' } }

// Formatting back to a string
const formatted = contentType.format(parsed);
// Returns: 'text/html; charset=utf-8'

// Works with request objects too
const reqType = contentType.parse(req);

Manual parsing would require handling edge cases like quoted parameters, multiple parameters, and ensuring the main type is normalized to lowercase.

❌ HTTP-Errors: Standard Error Objects

The http-errors package creates HTTP error objects with proper status codes, messages, and properties.

Why not DIY? Creating consistent error objects that work well with frameworks like Express requires setting multiple properties correctly.

// Using http-errors
const createError = require('http-errors');

// Creating specific errors
const notFound = createError(404, 'User not found');
const badRequest = createError.BadRequest('Invalid email format');
const unauthorized = createError.Unauthorized();

// Errors have proper properties
console.log(notFound.status); // 404
console.log(notFound.expose); // true (safe to show to users)

Without this, you'd manually set statusCode, status, expose, and other properties that Express and other middleware expect.

📁 MIME vs MIME-Types: Two Approaches to Type Lookup

Both mime and mime-types handle MIME type lookups, but with different scopes.

MIME Package (Full-Featured)

// Using mime
const mime = require('mime');

// Extension to type
const type = mime.getType('file.txt'); // 'text/plain'

// Type to extension
const ext = mime.getExtension('text/html'); // 'html'

// Custom types
mime.define({ 'application/custom': ['custom'] });

MIME-Types Package (Lightweight)

// Using mime-types
const mime = require('mime-types');

// Extension to type only
const type = mime.lookup('file.txt'); // 'text/plain'

// No reverse lookup available
// mime.extension('text/html') doesn't exist

// Get charset for a type
const charset = mime.charset('text/html'); // 'UTF-8'

Choose mime if you need bidirectional lookups or custom type definitions. Choose mime-types if you only need extension-to-type mapping and want a smaller dependency.

🔍 Type-Is: Content Type Validation

The type-is package checks if a request's Content-Type matches expected values.

Why not DIY? Content-Type validation needs to handle wildcards, specific types, and arrays of acceptable types while ignoring parameters.

// Using type-is
const typeis = require('type-is');

// Check against single type
if (typeis(req, 'application/json')) {
  // Handle JSON
}

// Check against array of types
if (typeis(req, ['json', 'urlencoded'])) {
  // Handle form data or JSON
}

// Wildcard support
if (typeis(req, 'application/*')) {
  // Handle any application type
}

// Get the actual matching type
const match = typeis(req, ['json', 'html']);
// Returns 'json', 'html', or false

Manual checking would require parsing the Content-Type header first and then implementing matching logic for wildcards and aliases.

🧩 How They Work Together

These packages are designed to complement each other in typical server scenarios:

// Example: File download endpoint
const express = require('express');
const createError = require('http-errors');
const contentDisposition = require('content-disposition');
const mime = require('mime');

app.get('/download/:filename', (req, res, next) => {
  const { filename } = req.params;
  
  // Validate file exists (simplified)
  if (!fileExists(filename)) {
    return next(createError.NotFound('File not found'));
  }
  
  // Set proper Content-Type
  const contentType = mime.getType(filename) || 'application/octet-stream';
  res.setHeader('Content-Type', contentType);
  
  // Set safe Content-Disposition
  res.setHeader('Content-Disposition', contentDisposition(filename));
  
  // Send file
  res.sendFile(filename);
});

// Example: API endpoint with validation
const typeis = require('type-is');
const createError = require('http-errors');

app.post('/api/users', (req, res, next) => {
  // Validate content type
  if (!typeis(req, ['json'])) {
    return next(createError.UnsupportedMediaType('Only JSON accepted'));
  }
  
  // Process JSON body
  // ...
});

⚠️ Common Pitfalls to Avoid

Don't Mix MIME Packages Unnecessarily

If you're already using mime, there's no need to also install mime-types. The mime package includes everything mime-types provides plus additional functionality.

Always Use content-disposition for Downloads

Never construct Content-Disposition headers manually:

// ❌ Dangerous - vulnerable to response splitting
res.setHeader('Content-Disposition', `attachment; filename="${userFilename}"`);

// ✅ Safe - properly escaped and encoded
res.setHeader('Content-Disposition', contentDisposition(userFilename));

Use http-errors Consistently

Mixing manual error objects with http-errors can lead to inconsistent behavior in error-handling middleware:

// ❌ Inconsistent
if (!user) {
  const err = new Error('Not found');
  err.statusCode = 404;
  next(err);
}

// ✅ Consistent
if (!user) {
  next(createError.NotFound('User not found'));
}

📊 When to Use Which Package

ScenarioRecommended Package(s)
Serving file downloadscontent-disposition + mime
Parsing request Content-Typecontent-type + type-is
Creating API error responseshttp-errors
Static file servermime-types (lighter) or mime (full-featured)
Validating request body formattype-is
Generating Content-Type headersmime

💡 Final Recommendation

These packages follow the Unix philosophy of doing one thing well. Rather than building monolithic utilities, they provide composable, focused tools that handle the tricky details of HTTP standards correctly.

  • Use content-disposition whenever you're setting that header — the security benefits alone justify the dependency.
  • Use content-type for parsing/formatting Content-Type headers — it handles RFC compliance so you don't have to.
  • Use http-errors for all error creation — it ensures consistency across your application.
  • Choose between mime and mime-types based on whether you need bidirectional lookups.
  • Use type-is for content type validation — it's much more reliable than manual string matching.

By using these specialized packages, you avoid common security vulnerabilities, ensure standards compliance, and write more maintainable code that clearly expresses its intent.

How to Choose: content-disposition vs content-type vs http-errors vs mime vs mime-types vs type-is

  • content-disposition:

    Choose content-disposition when you need to safely generate or parse the Content-Disposition header for file downloads. It properly handles filename encoding for special characters and prevents response splitting attacks by escaping newlines. This is essential for any application serving user-uploaded files or generating downloadable content.

  • content-type:

    Choose content-type when you need to parse or format Content-Type headers according to RFC 7231. It correctly handles media types with parameters (like charset) and provides normalized access to type and subtype. Use this instead of manual string parsing to avoid common pitfalls with parameter parsing and case sensitivity.

  • http-errors:

    Choose http-errors when you need to create HTTP error objects that follow standard conventions. It provides named constructors for all HTTP status codes (like createError.NotFound()) and ensures errors have proper status codes, message properties, and expose settings. This is crucial for consistent error handling in Express.js applications and custom middleware.

  • mime:

    Choose mime when you need a comprehensive MIME type database with both type-to-extension and extension-to-type lookups. It includes a large built-in database and supports custom type definitions. Use this over mime-types if you need extension lookups or want a single package that handles both directions of MIME type resolution.

  • mime-types:

    Choose mime-types when you only need extension-to-MIME-type lookups and want a lighter dependency. It's essentially the lookup functionality extracted from the mime package but without extension-to-type support. This is ideal for static file servers that map file extensions to Content-Type headers without needing reverse lookups.

  • type-is:

    Choose type-is when you need to check if an incoming request's Content-Type matches expected values. It supports wildcards (like application/*), specific types, and arrays of acceptable types. This is commonly used in middleware to validate request bodies before processing, ensuring your handlers only receive appropriately formatted data.

Similar Npm Packages to content-type

content-type is a Node.js module that provides utilities for parsing and formatting HTTP Content-Type headers. It simplifies the process of handling content types in web applications, allowing developers to easily work with different media types and ensure that their applications can correctly interpret and respond to various content formats. This package is particularly useful in scenarios where content negotiation is required, making it easier to manage the types of data exchanged between clients and servers.

While content-type is a valuable tool, there are several alternatives in the Node.js ecosystem that serve related purposes. Here are a few noteworthy options:

  • content-disposition is a module that helps manage the Content-Disposition HTTP header, which is used to specify how content should be handled by the browser. This is particularly useful for file downloads, as it allows developers to suggest a filename for the downloaded file. If your application needs to handle file downloads and manage how content is presented to users, content-disposition is an excellent choice.
  • http-errors is a module that facilitates the creation of HTTP error objects. It allows developers to easily generate standard HTTP error responses with appropriate status codes and messages. While not directly related to content types, http-errors is often used in conjunction with content-type handling to ensure that error responses are correctly formatted and convey meaningful information to clients.
  • mime is a library that provides a way to map file extensions to their corresponding MIME types. This is useful for serving files with the correct content type and ensuring that clients can properly interpret the data being sent. If you need to work with file types and want to ensure that your application serves the correct MIME types, mime is a solid option.
  • mime-types is another library that offers similar functionality to mime, providing an extensive mapping of file extensions to MIME types. It also allows for easy retrieval of content types based on file extensions, making it a great choice for applications that need to handle various file types and ensure proper content negotiation.
  • type-is is a module that helps determine the content type of a request based on the Content-Type header. It is particularly useful in middleware scenarios where you need to check the type of incoming data and respond accordingly. If your application requires robust content type checking and handling, type-is can be an effective tool.

For a comprehensive comparison of these packages, check out the following link: Comparing content-disposition vs content-type vs http-errors vs mime vs mime-types vs type-is.

Similar Npm Packages to http-errors

http-errors is a popular npm package designed to create HTTP error objects for use in Node.js applications. It provides a simple way to generate standardized error responses, making it easier to handle errors in web applications. The package allows developers to create errors with specific HTTP status codes, which can be particularly useful for building RESTful APIs. By using http-errors, developers can ensure that their applications return consistent and meaningful error messages to clients.

While http-errors is a solid choice for error handling, there are several alternatives that offer similar functionality:

  • boom is a powerful error handling library that provides a rich set of features for creating and managing HTTP errors. It allows developers to create errors with customizable status codes, payloads, and messages. boom is particularly popular in the Hapi.js framework but can be used in any Node.js application. Its flexibility and extensive features make it a great choice for developers looking for a comprehensive error handling solution.

  • create-error is a lightweight library that simplifies the process of creating custom error types in JavaScript. It allows developers to define their own error classes with specific names and messages, making it easy to manage different types of errors in applications. While it doesn’t specifically focus on HTTP errors, it can be used alongside other libraries to create a robust error handling strategy.

  • http-status is a simple utility that provides a mapping of HTTP status codes to their respective messages. While it doesn’t create error objects directly, it can be used in conjunction with other error handling libraries to provide meaningful status codes and messages in error responses. It’s a handy tool for developers who want to ensure their applications return the correct HTTP status codes.

  • http-status-codes is another library that offers a comprehensive set of HTTP status codes and their corresponding messages. Similar to http-status, it provides a way to access standard HTTP status codes in a more readable format. This library is useful for developers who want to maintain clarity and consistency in their error handling without the overhead of a more complex library.

To explore how these packages compare, visit the following link: Comparing boom vs create-error vs http-errors vs http-status vs http-status-codes.

Similar Npm Packages to mime

mime is a popular npm package used for parsing and generating MIME types in Node.js applications. It provides a straightforward way to work with media types, allowing developers to easily determine the content type of a file based on its extension or vice versa. This functionality is essential for web applications that need to handle various file types correctly, ensuring that the right content type is served to clients.

While mime is a reliable choice for handling MIME types, there are several alternatives in the npm ecosystem that offer similar functionalities. Here are a few noteworthy options:

  • content-type is a lightweight library that focuses on parsing and formatting Content-Type headers. It provides a simple API for working with content types, making it easy to extract and manipulate media type information from HTTP headers. If your primary need is to handle Content-Type headers in HTTP requests and responses, content-type is a great choice.
  • file-type is a library that detects the file type of a Buffer or a Uint8Array based on its magic numbers. Unlike mime, which relies on file extensions, file-type inspects the actual content of the file to determine its type. This can be particularly useful for applications that need to validate or handle files without relying solely on their extensions.
  • mime-db is a comprehensive database of MIME types and their associated file extensions. It provides a JSON representation of MIME types, which can be useful for applications that need to reference a wide range of media types. While it doesn't provide the same parsing and generation capabilities as mime, it can be a valuable resource for looking up MIME type information.
  • mime-types is another popular library for working with MIME types in Node.js. It offers similar functionality to mime, allowing developers to look up the MIME type of a file based on its extension and vice versa. mime-types is a solid alternative for those who need a straightforward solution for handling MIME types in their applications.

To explore how these packages compare, visit the following link: Comparing content-type vs file-type vs mime vs mime-db vs mime-types.

Similar Npm Packages to mime-types

mime-types is a popular npm package that provides utilities for working with MIME types in Node.js applications. It allows developers to easily retrieve the MIME type associated with a file extension, or vice versa, making it a valuable tool for handling file uploads, serving static files, and ensuring proper content types in HTTP responses. While mime-types is widely used, there are several alternatives available in the npm ecosystem that offer similar functionality. Here are a few notable options:

  • content-type is a lightweight library that focuses on parsing and formatting Content-Type headers. It allows developers to easily manipulate Content-Type strings, making it useful for applications that need to handle HTTP headers. If your primary goal is to work with Content-Type headers rather than file extensions, content-type is a great choice.
  • file-type is a library that detects the file type of a Buffer or a Uint8Array. Unlike mime-types, which relies on file extensions, file-type analyzes the actual content of the file to determine its type. This makes it particularly useful for applications that need to validate or process files based on their content rather than their names.
  • mime is another widely used package that provides a comprehensive mapping of MIME types to file extensions and vice versa. It offers similar functionality to mime-types, but with a different API and additional features. If you're looking for a more extensive set of MIME types and a slightly different approach, mime may be worth considering.
  • mime-db is a database of MIME types and their associated file extensions. It serves as a reference for developers who need to look up MIME types and is often used in conjunction with other libraries like mime and mime-types. If you need a comprehensive list of MIME types for reference purposes, mime-db can be a valuable resource.
  • mime-lookup is a simple library that provides a straightforward way to look up MIME types based on file extensions. It is similar to mime-types but with a more minimalistic approach. If you're looking for a lightweight solution for MIME type lookups, mime-lookup may fit your needs.

To compare these packages, check out the following link: Comparing content-type vs file-type vs mime vs mime-db vs mime-lookup vs mime-types.

README for content-disposition

content-disposition

NPM Version NPM Downloads Node.js Version Build Status Test Coverage

Create and parse HTTP Content-Disposition header

Installation

$ npm install content-disposition

API

const contentDisposition = require('content-disposition')

contentDisposition(filename, options)

Create an attachment Content-Disposition header value using the given file name, if supplied. The filename is optional and if no file name is desired, but you want to specify options, set filename to undefined.

res.setHeader('Content-Disposition', contentDisposition('∫ maths.pdf'))

note HTTP headers are of the ISO-8859-1 character set. If you are writing this header through a means different from setHeader in Node.js, you'll want to specify the 'binary' encoding in Node.js.

Options

contentDisposition accepts these properties in the options object.

fallback

If the filename option is outside ISO-8859-1, then the file name is actually stored in a supplemental field for clients that support Unicode file names and a ISO-8859-1 version of the file name is automatically generated.

This specifies the ISO-8859-1 file name to override the automatic generation or disables the generation all together, defaults to true.

  • A string will specify the ISO-8859-1 file name to use in place of automatic generation.
  • false will disable including a ISO-8859-1 file name and only include the Unicode version (unless the file name is already ISO-8859-1).
  • true will enable automatic generation if the file name is outside ISO-8859-1.

If the filename option is ISO-8859-1 and this option is specified and has a different value, then the filename option is encoded in the extended field and this set as the fallback field, even though they are both ISO-8859-1.

type

Specifies the disposition type, defaults to "attachment". This can also be "inline", or any other value (all values except inline are treated like attachment, but can convey additional information if both parties agree to it). The type is normalized to lower-case.

contentDisposition.parse(string)

const disposition = contentDisposition.parse('attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt')

Parse a Content-Disposition header string. This automatically handles extended ("Unicode") parameters by decoding them and providing them under the standard parameter name. This will return an object with the following properties (examples are shown for the string 'attachment; filename="EURO rates.txt"; filename*=UTF-8\'\'%e2%82%ac%20rates.txt'):

  • type: The disposition type (always lower case). Example: 'attachment'

  • parameters: An object of the parameters in the disposition (name of parameter always lower case and extended versions replace non-extended versions). Example: {filename: "€ rates.txt"}

Examples

Send a file for download

const contentDisposition = require('content-disposition')
const destroy = require('destroy')
const fs = require('fs')
const http = require('http')
const onFinished = require('on-finished')

const filePath = '/path/to/public/plans.pdf'

http.createServer(function onRequest (req, res) {
  // set headers
  res.setHeader('Content-Type', 'application/pdf')
  res.setHeader('Content-Disposition', contentDisposition(filePath))

  // send file
  const stream = fs.createReadStream(filePath)
  stream.pipe(res)
  onFinished(res, function () {
    destroy(stream)
  })
})

Testing

$ npm test

References

License

MIT

npm-compare.com is an independent website designed to help developers choose the most suitable npm packages. We are not affiliated with npm, Inc, the official website for the npm registry. Note that npm is a registered trademark of npm, Inc. Please share your feedback via our GitHub repository. For more details, please refer to our Terms & Privacy.