mime-types

library3.0.2jsnpmunverified

mime-types is a JavaScript utility library for working with content-types, offering functions to look up MIME types, file extensions, and associated charsets. Currently at stable version `3.0.2`, the package primarily focuses on providing accurate MIME type data sourced from `mime-db`. It differentiates itself from older `mime` modules by explicitly returning `false` for unknown types (rather than a naive fallback), avoiding instance creation (`new Mime()`), and omitting `.define()` functionality. While its core API remains compatible with `mime@1.x`, it's maintained by the `jshttp` organization and generally receives updates driven by new MIME types or minor fixes rather than frequent new features. A key aspect is its `mime-db` dependency; programmatic API changes are considered semver, but updates to the underlying MIME type data itself are not, meaning users needing strict data versioning must manage `mime-db` via package manager overrides.

serialization http-networking

npm install mime-types

github ↗package ↗

INSTALL

IMPORT

SIG · MIME-TYPES

mime-types

serializationjavascriptv3.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

mime

✓ import mime from 'mime-types';

✗ import { lookup, contentType } from 'mime-types';

This package is CommonJS by default. In an ESM module, the entire module exports as a default object. Named destructuring will not work directly.

mime (CommonJS)

✓ const mime = require('mime-types');

This is the primary and most robust way to import in a CommonJS environment.

mime.lookup

✓ import mime from 'mime-types'; const type = mime.lookup('index.html');

✗ const { lookup } = require('mime-types'); // Does not work, mime-types does not export named functions this way.

Functions like `lookup` are properties of the default export object, not named exports from the module itself.

Demonstrates core `mime-types` functionalities: `lookup` for MIME types, `contentType` for full headers, `extension` for default extensions, and `charset` for implied charsets, including handling unknown types.

import mime from 'mime-types'; import path from 'path'; // Look up a MIME type by file extension or path const jsonType = mime.lookup('json'); console.log(`JSON type: ${jsonType}`); // Expected: application/json const markdownType = mime.lookup('.md'); console.log(`Markdown type: ${markdownType}`); // Expected: text/markdown const filePath = '/path/to/document.pdf'; const fileType = mime.lookup(filePath); console.log(`File type for '${filePath}': ${fileType}`); // Expected: application/pdf // Handle unknown types (returns false) const unknownType = mime.lookup('unrecognized'); const fallbackType = unknownType || 'application/octet-stream'; console.log(`Unknown type lookup: ${fallbackType}`); // Expected: application/octet-stream // Create a full Content-Type header const htmlContentType = mime.contentType('text/html'); console.log(`HTML Content-Type: ${htmlContentType}`); // Expected: text/html; charset=utf-8 const jsContentType = mime.contentType(path.extname('app.js')); console.log(`JS Content-Type: ${jsContentType}`); // Expected: application/javascript; charset=utf-8 // Get default extension for a MIME type const binExtension = mime.extension('application/octet-stream'); console.log(`Extension for octet-stream: ${binExtension}`); // Expected: bin // Lookup implied default charset const textCharset = mime.charset('text/plain'); console.log(`Charset for text/plain: ${textCharset}`); // Expected: UTF-8

Debug

Known issues

breakingVersion 3.0.0 of `mime-types` updated its Node.js engine requirement to `>=18`. Running on older Node.js versions may lead to unexpected behavior or failures.

fix

Upgrade your Node.js environment to version 18 or higher.

affects: >=3.0.0

gotcha`mime.lookup()` returns `false` for unrecognized file extensions or types, rather than a generic fallback like `application/octet-stream`. This differs from some other MIME type libraries (e.g., `mime@1.x`) and requires explicit handling.

fix

Always check the return value of `mime.lookup()`. Use a logical OR (`||`) to provide a fallback, e.g., `const type = mime.lookup('unrecognized') || 'application/octet-stream';`.

affects: >=2.0.0

gotchaThe package explicitly states that updates to the underlying MIME type data from `mime-db` are not considered part of `mime-types`'s semver compatibility contract. This means new or changed MIME data can be introduced in minor or patch `mime-types` releases without a major version bump.

fix

If strict control over MIME type data versions is required, you must explicitly pin or override the `mime-db` dependency version in your project's `package.json` using your package manager's specific override syntax.

affects: >=3.0.0

deprecated`mime-types` does not support the `new Mime()` constructor or `.define()` functionality found in older `mime` libraries (e.g., `mime@1.x`). Attempting to use these methods will result in errors.

fix

Avoid using `new Mime()` or `.define()`. If you need to add custom MIME types, contribute them to the upstream `mime-db` project. For runtime overrides, consider libraries that explicitly support definition or manage a custom mapping.

affects: >=2.0.0

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use `require()` in an ECMAScript Module (ESM) file when `package.json` has `"type": "module"` or the file uses `.mjs` extension.

fix

In an ESM file, use `import mime from 'mime-types';`. If you must use `require()`, ensure your file is a CommonJS module (e.g., `.cjs` extension or no `"type": "module"` in `package.json`).

TypeError: Cannot destructure property 'lookup' of 'mime_types__WEBPACK_IMPORTED_MODULE_0___default.a' as it is undefined.

`mime-types` is a CommonJS module that exports a single object. When imported into an ESM context, it becomes the default export. Destructuring named exports will not work.

fix

Import the entire module as a default, then access its properties: `import mime from 'mime-types'; const type = mime.lookup('file.txt');`

Unexpected MIME type 'false' or incorrect application of 'application/octet-stream'

The `mime.lookup()` function explicitly returns `false` for unknown types, which can be overlooked, leading to `false` being used where a string is expected, or an incorrect fallback applied too broadly.

fix

Ensure you handle the `false` return value from `mime.lookup()` explicitly, typically by providing a default fallback like `const type = mime.lookup(filename) || 'application/octet-stream';`.

Upgrade

Version history

3.0.2latest on npm

Audit

Dependencies

mime-dbrequiredProvides the underlying MIME type data that mime-types uses for lookups. The `mime-db` versioning is not strictly tied to `mime-types` semver for data changes, requiring users to pin `mime-db` directly if precise data versions are critical.

Agent activity

18 hits · last 30 days

node

Resources

githubhttps://github.com/jshttp/mime-types ↗

packagehttps://www.npmjs.com/package/mime-types ↗