MIME Format Lookup

2.0.2 · active · verified Wed Apr 22

The `mime-format` library provides a utility for disambiguating the base format of HTTP response bodies based on their `Content-Type` header. It aims to resolve ambiguities, especially between `text/*` and `application/*` types, by maintaining an internal database of textual content types served under `application/*` (e.g., `application/json` is classified as `text`). The current stable version is 2.0.2, with releases appearing to be on an as-needed basis, indicated by the significant gap between v0.2.0 and v2.0.0. Key differentiators include its explicit handling of `application/*` types that are textual in nature, and its ability to guess or mark content types as unknown if they are not in its database, providing granular control over content interpretation.

Common errors

```
TypeError: mimeFormat.lookup is not a function
```
cause Attempting to destructure `lookup` from the module when it's a default export of an object or function, or incorrectly importing in an ESM context.

fix For CommonJS: `const mimeFormat = require('mime-format');`. For ESM: `import mimeFormat from 'mime-format';`. Then access the method as `mimeFormat.lookup(...)`.
```
SyntaxError: Cannot use import statement outside a module
```
cause Using `import` syntax in a CommonJS module (e.g., a `.js` file without `"type": "module"` in `package.json` or a `.cjs` file).

fix Either configure your Node.js project for ES modules by setting `"type": "module"` in `package.json` (and use `.mjs` or `.js` files), or switch to `require()` syntax: `const mimeFormat = require('mime-format');`.
```
(No explicit error, but incorrect classification) Received 'format: "raw"' or 'unknown: true' for a seemingly standard content type.
```
cause The `Content-Type` string might contain unusual parameters, be a non-standard but commonly used type not present in the library's internal database, or be subtly malformed.

fix Double-check the exact `Content-Type` string being passed. If it's valid but not recognized, `mime-format` will resort to guessing or marking as unknown, which is its intended behavior for unlisted types. Consider contributing to the library's database for widely used missing types.

Warnings

breaking The package underwent significant breaking changes between v0.x (e.g., v0.2.0 from 2017) and v2.x (released in 2024). Users migrating from older versions should review the API for changes, as the provided release notes are minimal for this major version bump.
Fix: Consult the GitHub repository's commit history or `package.json` for details on API changes if migrating from pre-v1.0 or v1.x versions.
gotcha When the `Content-Type` is not in the internal database, the module attempts to guess the format, returning `guessed: true`. If guessing fails, `unknown: true` and `format: 'raw'` are returned. Relying on an exact format without checking these flags can lead to unexpected handling of obscure or custom MIME types.
Fix: Always check the `guessed` and `unknown` flags in the returned object, and implement fallback logic for unlisted or custom content types.
gotcha The `format` property, especially for `type: 'text'`, indicates the syntax (e.g., 'json', 'xml'). However, for some types, or when a specific text syntax isn't detected, it might return 'raw', which the documentation notes can be redundant for most cases. Primarily rely on the `type` property for general classification.
Fix: Prioritize the `type` property for broad content categorization. Use `format` only when a specific textual syntax (like 'json', 'xml') is relevant and expected.
gotcha Passing non-string values to the `lookup` method for the `contentType` argument will result in them being typecast to `String`. While this prevents immediate errors, it can lead to incorrect or unexpected format detection if the string representation is not a valid `Content-Type` header.
Fix: Ensure that the `contentType` argument passed to `mimeFormat.lookup()` is always a valid string representing an HTTP `Content-Type` header.

Install

npm install mime-format npm
yarn add mime-format yarn
pnpm add mime-format pnpm

Imports

mimeFormat
wrong:
```
import { lookup } from 'mime-format';
```
correct:
```
import mimeFormat from 'mime-format';
```
The library is a CommonJS module that exports a default object/function, typically imported as `mimeFormat` in ESM. The `lookup` method is accessed directly on this imported object.
mimeFormat
```
const mimeFormat = require('mime-format');
```
This is the standard CommonJS import pattern, as shown in the package's documentation. The package's `package.json` specifies `"type": "commonjs"`.

lookup

wrong:

import { lookup } from 'mime-format'; lookup('application/json');

correct:

import mimeFormat from 'mime-format'; mimeFormat.lookup('application/json');

The `lookup` function is a method of the default exported `mimeFormat` object, not a named export itself.

Quickstart

This quickstart demonstrates how to use `mime-format` to identify the base type, specific format, and charset from various `Content-Type` headers, including known types and those requiring guessing.

const mimeFormat = require('mime-format');

// Look up a common XML content type with charset
const xmlResult = mimeFormat.lookup('application/xml; charset=gBk');
console.log('XML result:', xmlResult);
/*
Output:
{
  "type": "text",
  "format": "xml",
  "charset": "gBk"
}
*/

// Example for a JSON content type, which it classifies as 'text'
const jsonResult = mimeFormat.lookup('application/json');
console.log('JSON result:', jsonResult);
/*
Output:
{
  "type": "text",
  "format": "json"
}
*/

// Example for an unknown content type, demonstrating 'guessed' or 'unknown'
const unknownResult = mimeFormat.lookup('application/x-custom-format');
console.log('Unknown result:', unknownResult);
/*
Output (may vary slightly based on internal logic):
{
  "type": "application",
  "format": "raw",
  "guessed": true
}
*/

view raw JSON →