or run

npx @tessl/cli init
Log in

Version

Tile

Overview

Evals

Files

docs

index.md
tile.json

tessl/npm-mime-types

The ultimate javascript content-type utility for MIME type lookups, extensions mapping, and charset detection.

Workspace
tessl
Visibility
Public
Created
Last updated
Describes
npmpkg:npm/mime-types@3.0.x

To install, run

npx @tessl/cli install tessl/npm-mime-types@3.0.0

index.mddocs/

mime-types

The ultimate javascript content-type utility for MIME type lookups, extensions mapping, and charset detection. It provides comprehensive MIME type functionality without fallbacks, returning false for unrecognized types to enable explicit error handling.

Package Information

  • Package Name: mime-types
  • Package Type: npm
  • Language: JavaScript (Node.js)
  • Installation: npm install mime-types

Core Imports

const mime = require('mime-types');

For ES modules:

import mime from 'mime-types';

Individual function imports:

const { lookup, contentType, extension, charset } = require('mime-types');

Basic Usage

const mime = require('mime-types');

// Look up MIME type from file extension
const type = mime.lookup('json'); // 'application/json'
const htmlType = mime.lookup('file.html'); // 'text/html'

// Create content-type header with charset
const header = mime.contentType('json'); // 'application/json; charset=utf-8'

// Get file extension from MIME type
const ext = mime.extension('text/html'); // 'html'

// Get default charset for a MIME type
const charset = mime.charset('text/html'); // 'UTF-8'

// Access lookup maps directly
const jsonType = mime.types['json']; // 'application/json'
const htmlExts = mime.extensions['text/html']; // ['html', 'htm']

Capabilities

MIME Type Lookup

Look up the MIME type for a file path, extension, or filename.

/**
 * Lookup the MIME type for a file path/extension
 * @param {string} path - File path, extension, or filename
 * @returns {string|false} MIME type or false if not found
 */
function lookup(path);

Usage Examples:

mime.lookup('json'); // 'application/json'
mime.lookup('.md'); // 'text/markdown'
mime.lookup('file.html'); // 'text/html'
mime.lookup('folder/file.js'); // 'application/javascript'
mime.lookup('folder/.htaccess'); // false
mime.lookup('unknown-extension'); // false

Content-Type Header Generation

Create a full Content-Type header with appropriate charset from a MIME type or extension.

/**
 * Create a full Content-Type header given a MIME type or extension
 * @param {string} str - MIME type or file extension
 * @returns {string|false} Full content-type header or false if invalid
 */
function contentType(str);

Usage Examples:

// From extension
mime.contentType('markdown'); // 'text/x-markdown; charset=utf-8'
mime.contentType('file.json'); // 'application/json; charset=utf-8'

// From MIME type
mime.contentType('text/html'); // 'text/html; charset=utf-8'

// Preserves existing charset
mime.contentType('text/html; charset=iso-8859-1'); // 'text/html; charset=iso-8859-1'

// From full path extension
const path = require('path');
mime.contentType(path.extname('/path/to/file.json')); // 'application/json; charset=utf-8'

// Invalid input
mime.contentType('unknown'); // false

Extension Lookup

Get the default file extension for a MIME type.

/**
 * Get the default extension for a MIME type
 * @param {string} type - MIME type
 * @returns {string|false} File extension or false if not found
 */
function extension(type);

Usage Examples:

mime.extension('application/octet-stream'); // 'bin'
mime.extension('text/html'); // 'html'
mime.extension('application/json'); // 'json'
mime.extension('image/png'); // 'png'
mime.extension('unknown/type'); // false

Charset Detection

Get the default charset for a MIME type.

/**
 * Get the default charset for a MIME type
 * @param {string} type - MIME type
 * @returns {string|false} Charset or false if no default charset
 */
function charset(type);

Usage Examples:

mime.charset('text/html'); // 'UTF-8'
mime.charset('application/json'); // 'UTF-8'
mime.charset('text/markdown'); // 'UTF-8'
mime.charset('application/javascript'); // 'UTF-8'

// Text types default to UTF-8
mime.charset('text/x-custom'); // 'UTF-8'

// Binary types have no default charset
mime.charset('application/octet-stream'); // false
mime.charset('image/png'); // false

// Unknown types return false
mime.charset('unknown/type'); // false

Type Maps

Direct access to extension-to-type and type-to-extensions mappings.

/**
 * Map of file extensions to MIME types
 * @type {Object<string, string>}
 */
const types;

/**
 * Map of MIME types to arrays of file extensions
 * @type {Object<string, string[]>}
 */
const extensions;

Usage Examples:

// Extension to MIME type lookup
mime.types['json']; // 'application/json'
mime.types['html']; // 'text/html'
mime.types['js']; // 'application/javascript'

// MIME type to extensions lookup
mime.extensions['text/html']; // ['html', 'htm']
mime.extensions['application/javascript']; // ['js', 'mjs']
mime.extensions['image/jpeg']; // ['jpeg', 'jpg']

// Check if extension exists
if (mime.types['pdf']) {
  console.log('PDF MIME type:', mime.types['pdf']); // 'application/pdf'
}

Legacy Compatibility

Compatibility object for legacy charset lookup patterns.

/**
 * Legacy compatibility object with lookup method
 * @type {Object}
 */
const charsets;

Usage:

// Legacy charset lookup (same as charset function)  
mime.charsets.lookup('text/html'); // 'UTF-8'

Extension Conflicts Debugging

Internal array for tracking extension-to-type mapping changes during MIME score resolution.

/**
 * Array tracking extension conflicts between legacy and new type resolution
 * @type {Array<[string, string, string]>}
 * @private
 * @deprecated This is a temporary debugging tool and may be removed in future versions
 */
const _extensionConflicts;

Usage:

// Access conflicts that occurred during type resolution
const conflicts = mime._extensionConflicts;
// Each conflict is [extension, legacyType, newType]
// Example: ['m4a', 'audio/mp4', 'audio/x-m4a']

// Mainly used for development and debugging
console.log('Extension conflicts:', conflicts.length);
conflicts.forEach(([ext, legacy, current]) => {
  console.log(`Extension .${ext}: ${legacy} -> ${current}`);
});

Error Handling

All functions return false for invalid input instead of throwing errors:

// Invalid input types
mime.lookup(null); // false
mime.lookup({}); // false
mime.lookup(42); // false
mime.lookup(''); // false

mime.contentType(undefined); // false
mime.extension(true); // false
mime.charset([]); // false

// Unknown extensions/types
mime.lookup('unknown-ext'); // false
mime.extension('unknown/type'); // false

Type Resolution

mime-types uses a sophisticated scoring system to resolve conflicts when multiple MIME types map to the same extension:

  • Prefers official IANA types over other sources
  • Uses mime-score algorithm for consistent type selection
  • Avoids application/octet-stream when more specific types are available
  • Shorter MIME type names are preferred when scores are equal

API Behavior

  • Case Insensitive: Extension and MIME type lookups are case-insensitive
  • Path Handling: Full file paths are supported (extension is extracted)
  • Dot Handling: Extensions work with or without leading dots
  • No Fallbacks: Returns false for unrecognized input rather than guessing
  • Charset Detection: Text types default to UTF-8, binary types return false
  • Thread Safe: All operations are stateless and thread-safe