mrmime

mrmime is a minimal npm package built for one job: turning a file extension or filename into its MIME type as fast and as cheaply as possible. Instead of shipping the full breadth of the IANA/Apache/nginx MIME registries with all their vendor and experimental prefixes, it pre-generates a single flat lookup table from the mime-db project at build time, strips anything under x- or vnd. namespaces, and resolves conflicting entries by preferring the more authoritative source and the shorter MIME string. The result ships as a ~2.8kB gzipped module with a single lookup() function and an exported mimes dictionary that consumers can extend or override directly.

Because the dictionary is baked in ahead of time, there is no runtime dependency on mime-db itself, no file I/O, and no parsing overhead beyond a lowercase/trim and a single object-property lookup. The package ships CommonJS, native ESM, and TypeScript type definitions from one source, plus a companion Deno module, making it a drop-in replacement for heavier MIME libraries (like mime or mime-types) in size- and performance-sensitive contexts such as static file servers, bundlers, and upload handlers.

What You Get

• A lookup(extension) function that accepts a bare extension, a dotted extension, or a full filename/filepath and returns the matching MIME type or undefined
• An exported mimes plain object dictionary that can be read, extended, or overridden directly by the consumer at runtime
• Prebuilt CommonJS (index.js), native ESM (index.mjs), and TypeScript declaration (index.d.ts) outputs generated from one source
• A dedicated Deno module (deno/mod.ts) with no build step required
• A build-time generator (bin/index.ts) that regenerates the dictionary from the latest mime-db release, so the shipped table stays in sync with upstream IANA/Apache/nginx data

Common Use Cases

• Setting the correct Content-Type response header in a static file server or dev middleware based on the requested file’s extension
• Determining an asset’s MIME type during bundling or asset-pipeline processing (e.g. deciding how to inline or transform a file)
• Validating or classifying uploaded file extensions in an upload handler before accepting or rejecting a file
• Generating manifest or directory-listing metadata (e.g. static site generators, file browsers) that needs a MIME type per file

Under The Hood

Architecture mrmime keeps a strict split between a build-time generator and a runtime module. bin/index.ts reads the mime-db package, discards experimental and vendor-prefixed MIME types, and resolves any extension that maps to more than one MIME type by preferring the higher-authority source (IANA over Apache over nginx) and, as a tiebreaker, the shorter MIME string; the resulting flat object is written directly into src/$index.ts. That generated file, plus a small lookup() function performing a lowercase/trim and single object-property access, is the entire runtime surface — there are no classes, no I/O, and no dependency on mime-db once the dictionary has been generated. Nothing in the shipped module can break if the generation strategy changes, since the two are fully decoupled.

Tech Stack The project is authored in TypeScript and compiled with tsm (an esbuild-based TypeScript runner) into CommonJS (index.js), native ESM (index.mjs), and a hand-written index.d.ts, with a parallel deno/mod.ts maintained for Deno consumers. It has zero runtime dependencies; mime-db is a devDependency used only by the generator script. Testing runs on uvu, a lightweight, assertion-based test runner, and a separate bench/ directory benchmarks lookup() against the mime and mime-lite packages for load time and ops/sec. The repo uses a pnpm workspace and a GitHub Actions CI workflow that installs, builds, and runs the test suite on Node 18.

Code Quality The test suite in test/index.ts exercises lookup() across its main input shapes — uppercase extensions, leading-dot extensions, bare filenames, full filepaths (including Windows-style paths), non-string input, and surrounding whitespace — plus a smaller suite asserting the shape of the exported mimes object. Type safety comes from a hand-written .d.ts rather than compiler-checked exports, and there is no linter or formatter configuration in the repository, so style consistency relies on convention rather than tooling. Error handling is minimal by design: lookup() has no failure path beyond returning undefined for an unmatched or invalid extension.

What Makes It Unique Rather than competing with fuller-featured MIME libraries on API surface, mrmime narrows the problem to extension-to-MIME lookup only, then optimizes that one operation for size and speed: a deterministic, authority-ranked conflict-resolution pass at generation time keeps the runtime dictionary small and unambiguous, and the lack of any runtime dependency or parsing step keeps lookups to a single property access. The tradeoff is explicit in its own documentation — it intentionally implements a fraction of what larger MIME packages offer in exchange for a much smaller footprint and faster cold-start.