MIME Type Utility

Common errors

• ReferenceError: require is not defined

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

  cause `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'

  cause 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';`.

Warnings

• breaking Version 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.
• 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';`.
• gotcha The 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.
• 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.

Install

• npm install mime-types npm
• yarn add mime-types yarn
• pnpm add mime-types pnpm

Imports

• mime
  wrong:

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

  correct:

  import mime 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
  wrong:

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

  correct:

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

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

Quickstart

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