Documentation / v1.9.0

HTTP media types without the guesswork.

content-types-lite provides a curated set of type-safe constants and focused utilities for working with Content-Type headers. It does not infer types from filenames or inspect file contents.

Zero dependenciesESM + CommonJSLiteral TypeScript types

Installation

Install the package

Use your project’s package manager. Node.js 18.17 or newer is required when running in Node; modern browsers and bundlers can use the ESM build.

npm install content-types-lite

Quick start

Start with a constant

Import constants and utilities from the package root for a compact, discoverable API.

TypeScript

import contentTypes, {
  JSON,
  formatContentType,
  isJsonLike,
  matchesMediaType,
  parseContentType,
} from 'content-types-lite'

JSON // 'application/json'
contentTypes.PDF // 'application/pdf'

formatContentType(JSON, { charset: 'utf-8' })
// 'application/json; charset=utf-8'

CommonJS is supported.const { JSON, withCharset } = require('content-types-lite')

Reference

Constants & types

Named constants retain literal types. The frozen default export keeps existing 1.x access patterns intact.

ConstantValueStatus

JSONapplication/jsonCanonical

YAMLapplication/yamlCanonical

MSGPACKapplication/vnd.msgpackCanonical

PROTOBUFapplication/protobufCanonical

Legacy aliases for interoperability

YAML_LEGACY → application/x-yaml
MSGPACK_LEGACY → application/x-msgpack
PROTOBUF_LEGACY → application/x-protobuf
NDJSON → application/x-ndjson

Format

Format header values safely

Formatting normalizes names, quotes values when necessary, and rejects malformed values or control characters.

formatContentType(mediaType, parameters?)→ string

TypeScript

import {
  formatContentType,
  normalizeContentType,
  withCharset,
} from 'content-types-lite/format'

withCharset('text/html')
// 'text/html; charset=utf-8'

formatContentType('text/plain', { title: 'hello world' })
// 'text/plain; title="hello world"'

normalizeContentType('Text/HTML; Charset="utf-8"')
// 'text/html; charset=utf-8'

Parse

Parse strictly

parseContentType returns a normalized, immutable result. Duplicate parameters, malformed quoted strings, and invalid media types return null.

parseContentType(input)→ object | null

getMediaType(input)→ string | null

TypeScript

import {
  getMediaType,
  parseContentType,
} from 'content-types-lite/parse'

parseContentType('text/html; charset=utf-8')
// { type: 'text/html', parameters: { charset: 'utf-8' } }

getMediaType('Text/HTML; Charset=UTF-8')
// 'text/html'

parseContentType('invalid') // null

Match

Match exact types and ranges

Match a header against an exact value, a wildcard media range, or a structured-suffix wildcard.

matchesMediaType(input, pattern)→ boolean

TypeScript

import { matchesMediaType } from 'content-types-lite/match'

matchesMediaType('image/avif', 'image/*') // true
matchesMediaType(
  'application/problem+json',
  'application/*+json',
) // true

Guards

Ask useful questions

Use focused guards instead of repeating parsing and subtype logic throughout your application.

isContentTypeisJsonLikeisXmlLikeisTextualisImageisAudioisVideo

TypeScript

import { isJsonLike, isTextual } from 'content-types-lite/guards'

isJsonLike('application/vnd.api+json') // true
isTextual('application/yaml') // true

Guide

Multipart form data

Let the browser set the header

When sending a FormData body, do not manually set Content-Type: multipart/form-data. fetch or XMLHttpRequest must generate the boundary so it matches the encoded body.

The constant is intended for parsing, server-side generation where a boundary is supplied separately, and integrations that explicitly require the bare media type.

Scope

What this package does not do

This is deliberately not a comprehensive extension database or file-signature detector. It focuses on common HTTP values and correct header handling.

Use it for

Constants, header parsing, formatting, matching, and validation.

Use another tool for

Filename inference, exhaustive MIME databases, and file-content inspection.

NEXT STEPTry the interactive parser