{"id":11327,"library":"mime-types","title":"MIME Type Utility","description":"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.","status":"active","version":"3.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/jshttp/mime-types","tags":["javascript","mime","types"],"install":[{"cmd":"npm install mime-types","lang":"bash","label":"npm"},{"cmd":"yarn add mime-types","lang":"bash","label":"yarn"},{"cmd":"pnpm add mime-types","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides 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.","package":"mime-db","optional":false}],"imports":[{"note":"This package is CommonJS by default. In an ESM module, the entire module exports as a default object. Named destructuring will not work directly.","wrong":"import { lookup, contentType } from 'mime-types';","symbol":"mime","correct":"import mime from 'mime-types';"},{"note":"This is the primary and most robust way to import in a CommonJS environment.","symbol":"mime (CommonJS)","correct":"const mime = require('mime-types');"},{"note":"Functions like `lookup` are properties of the default export object, not named exports from the module itself.","wrong":"const { lookup } = require('mime-types'); // Does not work, mime-types does not export named functions this way.","symbol":"mime.lookup","correct":"import mime from 'mime-types';\nconst type = mime.lookup('index.html');"}],"quickstart":{"code":"import mime from 'mime-types';\nimport path from 'path';\n\n// Look up a MIME type by file extension or path\nconst jsonType = mime.lookup('json');\nconsole.log(`JSON type: ${jsonType}`); // Expected: application/json\n\nconst markdownType = mime.lookup('.md');\nconsole.log(`Markdown type: ${markdownType}`); // Expected: text/markdown\n\nconst filePath = '/path/to/document.pdf';\nconst fileType = mime.lookup(filePath);\nconsole.log(`File type for '${filePath}': ${fileType}`); // Expected: application/pdf\n\n// Handle unknown types (returns false)\nconst unknownType = mime.lookup('unrecognized');\nconst fallbackType = unknownType || 'application/octet-stream';\nconsole.log(`Unknown type lookup: ${fallbackType}`); // Expected: application/octet-stream\n\n// Create a full Content-Type header\nconst htmlContentType = mime.contentType('text/html');\nconsole.log(`HTML Content-Type: ${htmlContentType}`); // Expected: text/html; charset=utf-8\n\nconst jsContentType = mime.contentType(path.extname('app.js'));\nconsole.log(`JS Content-Type: ${jsContentType}`); // Expected: application/javascript; charset=utf-8\n\n// Get default extension for a MIME type\nconst binExtension = mime.extension('application/octet-stream');\nconsole.log(`Extension for octet-stream: ${binExtension}`); // Expected: bin\n\n// Lookup implied default charset\nconst textCharset = mime.charset('text/plain');\nconsole.log(`Charset for text/plain: ${textCharset}`); // Expected: UTF-8\n","lang":"typescript","description":"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."},"warnings":[{"fix":"Upgrade your Node.js environment to version 18 or higher.","message":"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.","severity":"breaking","affected_versions":">=3.0.0"},{"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';`.","message":"`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.","severity":"gotcha","affected_versions":">=2.0.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=3.0.0"},{"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.","message":"`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.","severity":"deprecated","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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`).","cause":"Attempting to use `require()` in an ECMAScript Module (ESM) file when `package.json` has `\"type\": \"module\"` or the file uses `.mjs` extension.","error":"ReferenceError: require is not defined"},{"fix":"Import the entire module as a default, then access its properties: `import mime from 'mime-types'; const type = mime.lookup('file.txt');`","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.","error":"TypeError: Cannot destructure property 'lookup' of 'mime_types__WEBPACK_IMPORTED_MODULE_0___default.a' as it is undefined."},{"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';`.","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.","error":"Unexpected MIME type 'false' or incorrect application of 'application/octet-stream'"}],"ecosystem":"npm"}