mime

mime is a dependency-free JavaScript library that maps file extensions to MIME types and back, covering the full mime-db type registry (800+ types, 1,000+ extensions) plus additional IANA-registered types not present in mime-db. It ships built-in TypeScript definitions, so consumers no longer need a separate @types/mime package, and targets modern ES2020+ runtimes with native ESM support.

Beyond the default frozen mime singleton, the library exposes a Mime class for building custom, mutable type maps — useful for registering proprietary extensions or excluding types you don’t need. A companion mime/lite export trims out the long tail of unofficial x-*, vnd.*, and prs.* types for smaller bundles, and a bundled CLI (mime <file> / mime -r <type>) exposes the same lookups from the command line.

What You Get

• Full mime-db type coverage (800+ MIME types, 1,000+ extensions) via mime.getType() and mime.getExtension()
• A mime/lite variant stripped of unofficial x-*/vnd.*/prs.* types for smaller bundles
• Built-in TypeScript declarations — no separate @types/mime package needed
• A custom Mime class constructor for building your own mutable type maps with define()
• A zero-dependency, tree-shakeable ESM build with a small footprint
• A bundled mime CLI for extension/type lookups from the shell

Common Use Cases

• Setting the correct Content-Type header when serving static files or file uploads
• Validating uploaded file extensions against expected MIME types
• Inferring file type from an uploaded filename in a Node.js or edge API handler
• Mapping MIME types back to a default extension when writing downloaded files

Under The Hood

Architecture

The library is a small, single-purpose module built around one core abstraction: src/Mime.ts defines a Mime class holding three private maps (extensionToType, typeToExtension, typeToExtensions) populated by a define() method. src/index.ts composes the public default export by instantiating Mime with the generated types/standard.ts and types/other.ts tables and freezing the result via _freeze() so consumers can’t mutate the shared singleton; src/index_lite.ts builds the same way but omits the other (non-standard) table for a smaller footprint. src/mime_cli.ts is a thin wrapper around the same getType/getExtension calls, exposed as a binary through bin/cli.js. There are no layers, no dependency injection, and no external data fetching at runtime — everything a consumer calls resolves against the in-memory maps built once at import time, so any change to the Mime class’s internal map structure would ripple through getType, getExtension, getAllExtensions, and the CLI simultaneously.

Tech Stack

Written in TypeScript (target ES2020, Node16 module resolution) and compiled to ESM-only JavaScript via tsc; there are no runtime dependencies at all. The types/standard.ts and types/other.ts data files are not hand-maintained — scripts/build.ts regenerates them by fetching the upstream mime-db JSON database, resolving type/extension conflicts with the mime-score package (preferring the higher-scoring entry per RFC 6838 facet rules), and writing the results back out through Prettier. Tooling is minimal and modern: TypeScript’s own compiler for builds, Prettier for formatting/linting (no ESLint despite a checked-in .eslintrc.cjs), and release-please for changelog/version automation on release.

Code Quality

Tests run via Node’s built-in node:test runner (test/mime.test.js, test/vendor.test.js) with a small shared test_util.js helper for table-driven assertions, plus a separate test/exports_test.sh that exercises the package’s export map directly. Coverage includes case-insensitivity, path/extension edge cases, Unicode whitespace in filenames, charset-parameter stripping, and both success and CLI subprocess paths — a comprehensive test suite for a library this size. TypeScript is run in strict mode, private class fields (#extensionToType) are used to genuinely encapsulate state rather than relying on convention, and CI (Mime CI GitHub Actions workflow) runs the full test suite across Node 18/20/22/24 on every push.

What Makes It Unique

Rather than hand-curating its MIME type tables, mime treats mime-db as an upstream data source and layers a build-time conflict-resolution pass (mime-score) on top of it, automatically demoting lower-priority types when multiple MIME types claim the same extension instead of letting the last one silently win. Pairing a frozen, dependency-free default export with an escape hatch — a mutable Mime class consumers can instantiate and define() themselves — gives it both a safe, tree-shakeable default and a documented path to customization, which is an uncommon combination among comparable extension-mapping libraries.