file-type

file-type is a JavaScript library that determines the true type of binary data by inspecting its magic number (the signature bytes at the start of a file) rather than trusting a filename extension or a client-supplied MIME type. It returns the canonical extension and MIME type for hundreds of formats spanning images, audio, video, archives, documents, and fonts.

Built on a streaming tokenizer, it works across Node.js and the browser and can read from files, Uint8Array/ArrayBuffer buffers, Blobs, and web ReadableStreams. Because it only needs the leading bytes of a file, it can identify large or remote files without downloading them in full, making it a common building block for secure upload validation and content pipelines.

What You Get

• Detection from files, buffers, Blobs, web ReadableStreams, and custom tokenizers via a small set of fileTypeFrom* functions.
• Support for hundreds of binary formats across images, audio, video, archives, documents, and fonts, each mapped to its canonical extension and MIME type.
• Streaming detection that only reads the leading bytes, so large or remote files can be identified without loading them entirely.
• First-class TypeScript definitions plus exported supportedExtensions and supportedMimeTypes sets.
• A customDetectors hook and reusable FileTypeParser class for extending detection to formats not built in.

Common Use Cases

• Validating file uploads on a server by verifying the real type instead of trusting the extension or client MIME header.
• Routing or transcoding media by detecting whether incoming bytes are an image, audio, video, or archive.
• Inspecting remote files over HTTP range requests or S3 without downloading the whole object.
• Enforcing allow-lists of accepted formats in content pipelines and asset-processing jobs.

Under The Hood

Architecture Detection is organized around a streaming tokenizer abstraction. The fileTypeFrom* entry points in source/index.js normalize their input (file path, Uint8Array/ArrayBuffer, Blob, or web ReadableStream) into an strtok3 tokenizer, then hand it to a FileTypeParser whose parse method walks an ordered ladder of magic-number checks, reading only as many leading bytes as each signature requires. More involved container formats (PNG, ZIP, EBML/Matroska, ASF) live in dedicated modules under source/detectors/, keeping the main dispatch readable, and source/supported.js centralizes the extension and MIME tables exported as supportedExtensions and supportedMimeTypes.

Tech Stack The package is authored as pure ESM ("type": "module") targeting Node.js >= 22, with no build step for consumers beyond its TypeScript definitions. It depends on a small, focused tokenizer stack — strtok3, token-types, @tokenizer/inflate, and uint8array-extras — rather than pulling in heavy runtime dependencies. Development uses ava for tests, xo for linting, tsd for type-definition testing, and esbuild.

Code Quality Quality is a clear strength. The repository ships an exceptionally large test.js (roughly 280KB) exercised against a fixture/ directory of real sample files, so detection is validated against genuine binaries rather than hand-crafted byte stubs. Linting is enforced with xo and the public type surface is checked with tsd via source/index.test-d.ts. Naming is consistent and descriptive (fileTypeFromBuffer, fileTypeFromStream), and functions return undefined on no match rather than throwing, giving predictable control flow.

API Design The public API is small, orthogonal, and ergonomic: a family of fileTypeFrom{Buffer,File,Stream,Blob,Tokenizer} functions that each resolve to {ext, mime} or undefined, plus a fileTypeStream helper and a FileTypeParser class for advanced reuse. Extensibility is handled cleanly through a customDetectors option, and full TypeScript types plus a thorough README with copy-paste examples mean most users are productive after a single import.