whatwg-mimetype 5.x

Complete instructions

Verified against whatwg-mimetype@5.0.0 on 2026-09-08. 6 of 6 examples executed.

whatwg-mimetype

Scope and version

This skill targets whatwg-mimetype ^5.0.0, which requires Node.js >=20. The package root exports exactly the named APIs MIMEType and computedMIMEType.

In v5, MIMEType is a named export rather than the older default-export shape. Raw parsing and serialization APIs from older versions were removed.

Parsing and serialization

Constructing a MIME type parses the string and throws an Error if parsing fails. MIMEType.parse(string) performs the same kind of parsing but returns null on failure.

A parsed instance exposes:

• mutable type
• mutable subtype
• getter-only essence, which is type/subtype
• mutable parameters
• toString() for serialization

Parsing and serialization normalize the type, subtype, and parameter names according to the MIME type rules. Parameter values are not generally lowercased: for example, a parameter value of D remains D, while a quoted value such as "utf-8" is serialized without unnecessary quotes.

import assert from "node:assert/strict";
import { MIMEType } from "whatwg-mimetype";

const mimeType = new MIMEType('Text/HTML;Charset="utf-8"');

assert.equal(mimeType.toString(), "text/html;charset=utf-8");
assert.equal(mimeType.type, "text");
assert.equal(mimeType.subtype, "html");
assert.equal(mimeType.essence, "text/html");
assert.equal(mimeType.parameters.get("charset"), "utf-8");

assert.equal(MIMEType.parse("not a MIME type"), null);
assert.throws(() => new MIMEType("not a MIME type"), Error);

Do not use the v4-style default import. Use the v5 named import:

import assert from "node:assert/strict";
import { MIMEType } from "whatwg-mimetype";

const mimeType = new MIMEType("text/plain");
mimeType.type = "application";
mimeType.subtype = "json";

assert.equal(mimeType.essence, "application/json");
assert.equal(mimeType.toString(), "application/json");

type and subtype are validated when changed. essence is getter-only; update type or subtype instead of assigning to essence.

Parameters

mimeType.parameters is a MIME-specific Map-like object, not a package-root MIMETypeParameters export. Parameter names are handled case-insensitively and normalized to lowercase. Parameter values preserve their parsed spelling. It supports the documented get, set, and iteration usage.

import assert from "node:assert/strict";
import { MIMEType } from "whatwg-mimetype";

const mimeType = new MIMEType("x/x;a=b;c=D;E=\"F\"");

const entries = [...mimeType.parameters];
assert.deepEqual(entries, [
  ["a", "b"],
  ["c", "D"],
  ["e", "F"],
]);

mimeType.parameters.set("Q", "X");
assert.equal(mimeType.parameters.get("q"), "X");
assert.equal(mimeType.toString(), "x/x;a=b;c=D;e=F;q=X");

Classification helpers

MIMEType provides isHTML(), isXML(), and isJavaScript({ prohibitParameters }). These helpers are documented as speculative and may change in a future major; avoid treating them as a permanently stable compatibility contract.

import assert from "node:assert/strict";
import { MIMEType } from "whatwg-mimetype";

const html = new MIMEType('Text/HTML;Charset="utf-8"');
assert.equal(html.isHTML(), true);
assert.equal(html.isXML(), false);

const xml = new MIMEType("application/xml");
assert.equal(xml.isXML(), true);

const javascript = new MIMEType("text/javascript");
assert.equal(javascript.isJavaScript({ prohibitParameters: false }), true);

Computing a MIME type from bytes

computedMIMEType(resource, options) is a plain library API. resource must be a Uint8Array; the result is a MIMEType.

Supported options are contentTypeHeader, providedType, noSniff (default false), and isSupported (default () => true). The function can sniff resource bytes. A PNG signature is computed as image/png without a header. An image/gif content-type header does not override that PNG result, while a text/html header does produce text/html in the documented example.

import assert from "node:assert/strict";
import { computedMIMEType, MIMEType } from "whatwg-mimetype";

const pngBytes = new Uint8Array([
  0x89, 0x50, 0x4e, 0x47,
  0x0d, 0x0a, 0x1a, 0x0a,
]);

assert.equal(computedMIMEType(pngBytes).essence, "image/png");
assert.equal(
  computedMIMEType(pngBytes, { contentTypeHeader: "image/gif" }).essence,
  "image/png",
);
assert.equal(
  computedMIMEType(pngBytes, { contentTypeHeader: "text/html" }).essence,
  "text/html",
);
assert.ok(computedMIMEType(pngBytes) instanceof MIMEType);

The options are passed to the computation as an options object; do not pass a string as the second argument.

import assert from "node:assert/strict";
import { computedMIMEType, MIMEType } from "whatwg-mimetype";

const resource = new Uint8Array();
const result = computedMIMEType(resource, {
  contentTypeHeader: "text/plain",
  providedType: "text/plain",
  noSniff: false,
  isSupported: () => true,
});

assert.ok(result instanceof MIMEType);

What this skill does not cover

This skill does not cover MIME sniffing cases beyond the documented PNG examples, the detailed validation rules for every possible type or parameter value, or the exact behavior of each computedMIMEType option combination. It also does not cover removed v4 raw parsing/serialization APIs, package development scripts, or any runner, CLI, build step, or framework integration; the package exposes a plain programmatic API instead.