[6a3a178] | 1 | <!--
|
---|
| 2 | -- This file is auto-generated from src/README_js.md. Changes should be made there.
|
---|
| 3 | -->
|
---|
| 4 | # Mime
|
---|
| 5 |
|
---|
| 6 | A comprehensive, compact MIME type module.
|
---|
| 7 |
|
---|
| 8 | [![Build Status](https://travis-ci.org/broofa/mime.svg?branch=master)](https://travis-ci.org/broofa/mime)
|
---|
| 9 |
|
---|
| 10 | ## Version 2 Notes
|
---|
| 11 |
|
---|
| 12 | Version 2 is a breaking change from 1.x as the semver implies. Specifically:
|
---|
| 13 |
|
---|
| 14 | * `lookup()` renamed to `getType()`
|
---|
| 15 | * `extension()` renamed to `getExtension()`
|
---|
| 16 | * `charset()` and `load()` methods have been removed
|
---|
| 17 |
|
---|
| 18 | If you prefer the legacy version of this module please `npm install mime@^1`. Version 1 docs may be found [here](https://github.com/broofa/mime/tree/v1.4.0).
|
---|
| 19 |
|
---|
| 20 | ## Install
|
---|
| 21 |
|
---|
| 22 | ### NPM
|
---|
| 23 | ```
|
---|
| 24 | npm install mime
|
---|
| 25 | ```
|
---|
| 26 |
|
---|
| 27 | ### Browser
|
---|
| 28 |
|
---|
| 29 | It is recommended that you use a bundler such as
|
---|
| 30 | [webpack](https://webpack.github.io/) or [browserify](http://browserify.org/) to
|
---|
| 31 | package your code. However, browser-ready versions are available via wzrd.in.
|
---|
| 32 | E.g. For the full version:
|
---|
| 33 |
|
---|
| 34 | <script src="https://wzrd.in/standalone/mime@latest"></script>
|
---|
| 35 | <script>
|
---|
| 36 | mime.getType(...); // etc.
|
---|
| 37 | </script>
|
---|
| 38 |
|
---|
| 39 | Or, for the `mime/lite` version:
|
---|
| 40 |
|
---|
| 41 | <script src="https://wzrd.in/standalone/mime%2flite@latest"></script>
|
---|
| 42 | <script>
|
---|
| 43 | mimelite.getType(...); // (Note `mimelite` here)
|
---|
| 44 | </script>
|
---|
| 45 |
|
---|
| 46 | ## Quick Start
|
---|
| 47 |
|
---|
| 48 | For the full version (800+ MIME types, 1,000+ extensions):
|
---|
| 49 |
|
---|
| 50 | ```javascript
|
---|
| 51 | const mime = require('mime');
|
---|
| 52 |
|
---|
| 53 | mime.getType('txt'); // ⇨ 'text/plain'
|
---|
| 54 | mime.getExtension('text/plain'); // ⇨ 'txt'
|
---|
| 55 | ```
|
---|
| 56 |
|
---|
| 57 | See [Mime API](#mime-api) below for API details.
|
---|
| 58 |
|
---|
| 59 | ## Lite Version
|
---|
| 60 |
|
---|
| 61 | There is also a "lite" version of this module that omits vendor-specific
|
---|
| 62 | (`*/vnd.*`) and experimental (`*/x-*`) types. It weighs in at ~2.5KB, compared
|
---|
| 63 | to 8KB for the full version. To load the lite version:
|
---|
| 64 |
|
---|
| 65 | ```javascript
|
---|
| 66 | const mime = require('mime/lite');
|
---|
| 67 | ```
|
---|
| 68 |
|
---|
| 69 | ## Mime .vs. mime-types .vs. mime-db modules
|
---|
| 70 |
|
---|
| 71 | For those of you wondering about the difference between these [popular] NPM modules,
|
---|
| 72 | here's a brief rundown ...
|
---|
| 73 |
|
---|
| 74 | [`mime-db`](https://github.com/jshttp/mime-db) is "the source of
|
---|
| 75 | truth" for MIME type information. It is not an API. Rather, it is a canonical
|
---|
| 76 | dataset of mime type definitions pulled from IANA, Apache, NGINX, and custom mappings
|
---|
| 77 | submitted by the Node.js community.
|
---|
| 78 |
|
---|
| 79 | [`mime-types`](https://github.com/jshttp/mime-types) is a thin
|
---|
| 80 | wrapper around mime-db that provides an API drop-in compatible(ish) with `mime @ < v1.3.6` API.
|
---|
| 81 |
|
---|
| 82 | `mime` is, as of v2, a self-contained module bundled with a pre-optimized version
|
---|
| 83 | of the `mime-db` dataset. It provides a simplified API with the following characteristics:
|
---|
| 84 |
|
---|
| 85 | * Intelligently resolved type conflicts (See [mime-score](https://github.com/broofa/mime-score) for details)
|
---|
| 86 | * Method naming consistent with industry best-practices
|
---|
| 87 | * Compact footprint. E.g. The minified+compressed sizes of the various modules:
|
---|
| 88 |
|
---|
| 89 | Module | Size
|
---|
| 90 | --- | ---
|
---|
| 91 | `mime-db` | 18 KB
|
---|
| 92 | `mime-types` | same as mime-db
|
---|
| 93 | `mime` | 8 KB
|
---|
| 94 | `mime/lite` | 2 KB
|
---|
| 95 |
|
---|
| 96 | ## Mime API
|
---|
| 97 |
|
---|
| 98 | Both `require('mime')` and `require('mime/lite')` return instances of the MIME
|
---|
| 99 | class, documented below.
|
---|
| 100 |
|
---|
| 101 | Note: Inputs to this API are case-insensitive. Outputs (returned values) will
|
---|
| 102 | be lowercase.
|
---|
| 103 |
|
---|
| 104 | ### new Mime(typeMap, ... more maps)
|
---|
| 105 |
|
---|
| 106 | Most users of this module will not need to create Mime instances directly.
|
---|
| 107 | However if you would like to create custom mappings, you may do so as follows
|
---|
| 108 | ...
|
---|
| 109 |
|
---|
| 110 | ```javascript
|
---|
| 111 | // Require Mime class
|
---|
| 112 | const Mime = require('mime/Mime');
|
---|
| 113 |
|
---|
| 114 | // Define mime type -> extensions map
|
---|
| 115 | const typeMap = {
|
---|
| 116 | 'text/abc': ['abc', 'alpha', 'bet'],
|
---|
| 117 | 'text/def': ['leppard']
|
---|
| 118 | };
|
---|
| 119 |
|
---|
| 120 | // Create and use Mime instance
|
---|
| 121 | const myMime = new Mime(typeMap);
|
---|
| 122 | myMime.getType('abc'); // ⇨ 'text/abc'
|
---|
| 123 | myMime.getExtension('text/def'); // ⇨ 'leppard'
|
---|
| 124 | ```
|
---|
| 125 |
|
---|
| 126 | If more than one map argument is provided, each map is `define()`ed (see below), in order.
|
---|
| 127 |
|
---|
| 128 | ### mime.getType(pathOrExtension)
|
---|
| 129 |
|
---|
| 130 | Get mime type for the given path or extension. E.g.
|
---|
| 131 |
|
---|
| 132 | ```javascript
|
---|
| 133 | mime.getType('js'); // ⇨ 'application/javascript'
|
---|
| 134 | mime.getType('json'); // ⇨ 'application/json'
|
---|
| 135 |
|
---|
| 136 | mime.getType('txt'); // ⇨ 'text/plain'
|
---|
| 137 | mime.getType('dir/text.txt'); // ⇨ 'text/plain'
|
---|
| 138 | mime.getType('dir\\text.txt'); // ⇨ 'text/plain'
|
---|
| 139 | mime.getType('.text.txt'); // ⇨ 'text/plain'
|
---|
| 140 | mime.getType('.txt'); // ⇨ 'text/plain'
|
---|
| 141 | ```
|
---|
| 142 |
|
---|
| 143 | `null` is returned in cases where an extension is not detected or recognized
|
---|
| 144 |
|
---|
| 145 | ```javascript
|
---|
| 146 | mime.getType('foo/txt'); // ⇨ null
|
---|
| 147 | mime.getType('bogus_type'); // ⇨ null
|
---|
| 148 | ```
|
---|
| 149 |
|
---|
| 150 | ### mime.getExtension(type)
|
---|
| 151 | Get extension for the given mime type. Charset options (often included in
|
---|
| 152 | Content-Type headers) are ignored.
|
---|
| 153 |
|
---|
| 154 | ```javascript
|
---|
| 155 | mime.getExtension('text/plain'); // ⇨ 'txt'
|
---|
| 156 | mime.getExtension('application/json'); // ⇨ 'json'
|
---|
| 157 | mime.getExtension('text/html; charset=utf8'); // ⇨ 'html'
|
---|
| 158 | ```
|
---|
| 159 |
|
---|
| 160 | ### mime.define(typeMap[, force = false])
|
---|
| 161 |
|
---|
| 162 | Define [more] type mappings.
|
---|
| 163 |
|
---|
| 164 | `typeMap` is a map of type -> extensions, as documented in `new Mime`, above.
|
---|
| 165 |
|
---|
| 166 | By default this method will throw an error if you try to map a type to an
|
---|
| 167 | extension that is already assigned to another type. Passing `true` for the
|
---|
| 168 | `force` argument will suppress this behavior (overriding any previous mapping).
|
---|
| 169 |
|
---|
| 170 | ```javascript
|
---|
| 171 | mime.define({'text/x-abc': ['abc', 'abcd']});
|
---|
| 172 |
|
---|
| 173 | mime.getType('abcd'); // ⇨ 'text/x-abc'
|
---|
| 174 | mime.getExtension('text/x-abc') // ⇨ 'abc'
|
---|
| 175 | ```
|
---|
| 176 |
|
---|
| 177 | ## Command Line
|
---|
| 178 |
|
---|
| 179 | mime [path_or_extension]
|
---|
| 180 |
|
---|
| 181 | E.g.
|
---|
| 182 |
|
---|
| 183 | > mime scripts/jquery.js
|
---|
| 184 | application/javascript
|
---|
| 185 |
|
---|
| 186 | ----
|
---|
| 187 | Markdown generated from [src/README_js.md](src/README_js.md) by [![RunMD Logo](http://i.imgur.com/h0FVyzU.png)](https://github.com/broofa/runmd) |
---|