sindresorhus/file-type

Detect the file type of a Buffer/Uint8Array/ArrayBuffer

Summary

file-type is a JavaScript library that detects the type of a file by inspecting its magic number from a Uint8Array, file path, stream, or Blob. It returns an object with the file extension and MIME type for a wide range of binary formats, from PNG and JPEG to MP4, MP3, ZIP, PDF, and dozens more. The README is explicit that detection is best-effort based on binary signatures and does not guarantee that a file is actually valid or well-formed.

What it is useful for

The library is useful when an application receives binary data and needs to determine its actual type rather than trusting filenames or HTTP-declared MIME types. Typical scenarios include validating user uploads, routing files to format-specific processing pipelines, or normalizing data before storage. Because detection operates on buffers and streams, it can be applied to remote data (e.g. via fetch), in-browser Blob or File objects, and even remote storage such as S3 using a tokenizer-based integration.

The package targets binary formats only and explicitly excludes text-based formats like .txt, .csv, or .svg. The supported list is broad: common image, video, audio, archive, font, document, and executable types are included. For formats that ship separately or are non-binary by nature, the customDetectors option allows registering plugins — for example @file-type/xml for XML-based formats, or @file-type/av for improved audio/video differentiation. The mpegOffsetTolerance option lets detection handle slight sync offsets in malformed MPEG audio files.

How engineers can use it

The project must be ESM. Install with npm install file-type, then import the relevant function. The simplest entry point from a file path:

import {fileTypeFromFile} from 'file-type';
console.log(await fileTypeFromFile('Unicorn.png'));
//=> {ext: 'png', mime: 'image/png'}

fileTypeFromBuffer accepts a Uint8Array or ArrayBuffer. fileTypeFromStream accepts a web ReadableStream; Node.js stream.Readable instances can be converted with Readable.toWeb(). fileTypeFromBlob works with Blob and File objects in the browser.

For cases where reading the entire file is wasteful, fileTypeFromTokenizer reads only the minimum bytes required, and integrates with packages like @tokenizer/http (HTTP range requests) or @tokenizer/s3 (S3 objects). fileTypeStream can be inserted into a stream pipeline and buffers a configurable sample (default 4100 bytes) before detection.

Documented limitations worth keeping in mind: detection is best-effort, not a proof of validity, and robustness against malformed input is best-effort too. When handling untrusted files on a server, the README recommends enforcing size limits and running detection in a worker thread with a timeout. Custom detector instances are not safe for concurrent use, so a new FileTypeParser should be created per call when concurrency is needed.