Documentation / v1.9.0

Small API.
Clear contracts.

Constants and helpers for the MIME work application code does every day. Typed, dependency-free, and deliberately curated.

Get started

Installation

Install with any current JavaScript package manager. Node.js 20 or newer is supported.

$npm install mime-types-lite

ES modulesCommonJSBrowsersTypeScript

Get started

Quick start

Import only the surface you need, or use the immutable MIME object for dynamic access.

example.ts

import { MIME, fromExtension, matchesMimeType } from 'mime-types-lite';

MIME.JSON; // 'application/json'
fromExtension('reports/annual.pdf'); // 'application/pdf'
matchesMimeType('image/png', 'image/*'); // true

Constants

Import tree-shakeable named constants, use the immutable MIME object, or keep the backward-compatible default export.

MIME: Readonly<Record<MimeTypeKey, MimeType>>

Constants.ts

import mimeTypesLite, { JSON, MIME } from 'mime-types-lite';

JSON;              // 'application/json'
MIME.PDF;          // 'application/pdf'
mimeTypesLite.PNG; // 'image/png'

Lookup

fromExtension

Find a curated media type from an extension, filename, Windows path, or URL. Query strings and fragments are ignored.

fromExtension(value: string): MimeType | undefined

fromExtension.ts

fromExtension('.json');
// 'application/json'

fromExtension('C:\files\photo.JPEG');
// 'image/jpeg'

fromExtension('https://example.com/app.js?v=2');
// 'text/javascript'

Note

Lookup uses the filename only. It does not inspect file bytes.

Lookup

extensionsFor

Return every known extension for a media type without leading dots. Content-Type parameters are normalized first.

extensionsFor(value: string): readonly KnownExtension[]

extensionsFor.ts

extensionsFor('image/jpeg');
// ['jpg', 'jpeg', 'jpe']

extensionsFor('text/html; charset=utf-8');
// ['html', 'htm']

Validation

normalizeMimeType

Remove parameters, trim whitespace, lowercase the value, and validate MIME syntax. Invalid input returns undefined.

normalizeMimeType(value: unknown): MimeTypeString | undefined

normalizeMimeType.ts

normalizeMimeType(' Application/JSON; charset=utf-8 ');
// 'application/json'

normalizeMimeType('not a MIME type');
// undefined

Validation

Validation helpers

Validate syntax, check the curated set, or extract a recognized top-level media category.

Validation helpers.ts

isMimeType('application/problem+json'); // true
isKnownMimeType('application/json; charset=utf-8'); // true
mimeCategory('image/svg+xml'); // 'image'

Validation

matchesMimeType

Match a Content-Type value against an exact media type, a category wildcard, or the universal wildcard.

matchesMimeType(value: unknown, pattern: MimeTypePattern | string): boolean

matchesMimeType.ts

matchesMimeType('image/avif', 'image/*'); // true
matchesMimeType('application/json; charset=utf-8', 'application/json'); // true
matchesMimeType('text/plain', 'image/*'); // false

Note

This helper does not parse weighted HTTP Accept headers.

Types

TypeScript types

Literal unions provide precise types for keys, known values, extensions, categories, and patterns.

TypeScript types.ts

import type {
  KnownExtension,
  MimeCategory,
  MimeType,
  MimeTypeKey,
  MimeTypePattern,
  MimeTypeString,
} from 'mime-types-lite';

Guides

Standards & legacy values

Preferred constants follow current registrations and specifications. Historic values remain available through LEGACY_MIME.

FormatPreferredLegacy

JavaScripttext/javascriptapplication/javascript

YAMLapplication/yamlapplication/x-yaml

Iconimage/vnd.microsoft.iconimage/x-icon

GraphQL responseapplication/graphql-response+jsonapplication/graphql

Guides

Security boundary

Do not trust the label alone

A filename extension, browser File.type, or HTTP Content-Type header can be attacker-controlled.

For untrusted uploads, also inspect file signatures, enforce size limits, store files safely, and process them with hardened tooling.

Read the security policy