|
| 1 | +# base64 [](https://travis-ci.org/mathiasbynens/base64) [](https://coveralls.io/r/mathiasbynens/base64) |
| 2 | + |
| 3 | +_base64_ is a robust base64 encoder/decoder that is fully compatible with [`atob()` and `btoa()`](https://html.spec.whatwg.org/multipage/webappapis.html#atob), written in JavaScript. The base64-encoding and -decoding algorithms it uses are fully [RFC 4648](https://tools.ietf.org/html/rfc4648#section-4) compliant. |
| 4 | + |
| 5 | +## Installation |
| 6 | + |
| 7 | +Via [npm](https://www.npmjs.com/): |
| 8 | + |
| 9 | +```bash |
| 10 | +npm install base-64 |
| 11 | +``` |
| 12 | + |
| 13 | +In a browser: |
| 14 | + |
| 15 | +```html |
| 16 | +<script src="base64.js"></script> |
| 17 | +``` |
| 18 | + |
| 19 | +In [Narwhal](http://narwhaljs.org/), [Node.js](https://nodejs.org/), and [RingoJS](http://ringojs.org/): |
| 20 | + |
| 21 | +```js |
| 22 | +var base64 = require('base-64'); |
| 23 | +``` |
| 24 | + |
| 25 | +In [Rhino](http://www.mozilla.org/rhino/): |
| 26 | + |
| 27 | +```js |
| 28 | +load('base64.js'); |
| 29 | +``` |
| 30 | + |
| 31 | +Using an AMD loader like [RequireJS](http://requirejs.org/): |
| 32 | + |
| 33 | +```js |
| 34 | +require( |
| 35 | + { |
| 36 | + 'paths': { |
| 37 | + 'base64': 'path/to/base64' |
| 38 | + } |
| 39 | + }, |
| 40 | + ['base64'], |
| 41 | + function(base64) { |
| 42 | + console.log(base64); |
| 43 | + } |
| 44 | +); |
| 45 | +``` |
| 46 | + |
| 47 | +## API |
| 48 | + |
| 49 | +### `base64.version` |
| 50 | + |
| 51 | +A string representing the semantic version number. |
| 52 | + |
| 53 | +### `base64.encode(input)` |
| 54 | + |
| 55 | +This function takes a byte string (the `input` parameter) and encodes it according to base64. The input data must be in the form of a string containing only characters in the range from U+0000 to U+00FF, each representing a binary byte with values `0x00` to `0xFF`. The `base64.encode()` function is designed to be fully compatible with [`btoa()` as described in the HTML Standard](https://html.spec.whatwg.org/multipage/webappapis.html#dom-windowbase64-btoa). |
| 56 | + |
| 57 | +```js |
| 58 | +var encodedData = base64.encode(input); |
| 59 | +``` |
| 60 | + |
| 61 | +To base64-encode any Unicode string, [encode it as UTF-8 first](https://github.com/mathiasbynens/utf8.js#utf8encodestring): |
| 62 | + |
| 63 | +```js |
| 64 | +var base64 = require('base-64'); |
| 65 | +var utf8 = require('utf8'); |
| 66 | + |
| 67 | +var text = 'foo © bar 𝌆 baz'; |
| 68 | +var bytes = utf8.encode(text); |
| 69 | +var encoded = base64.encode(bytes); |
| 70 | +console.log(encoded); |
| 71 | +// → 'Zm9vIMKpIGJhciDwnYyGIGJheg==' |
| 72 | +``` |
| 73 | + |
| 74 | +### `base64.decode(input)` |
| 75 | + |
| 76 | +This function takes a base64-encoded string (the `input` parameter) and decodes it. The return value is in the form of a string containing only characters in the range from U+0000 to U+00FF, each representing a binary byte with values `0x00` to `0xFF`. The `base64.decode()` function is designed to be fully compatible with [`atob()` as described in the HTML Standard](https://html.spec.whatwg.org/multipage/webappapis.html#dom-windowbase64-atob). |
| 77 | + |
| 78 | +```js |
| 79 | +var decodedData = base64.decode(encodedData); |
| 80 | +``` |
| 81 | + |
| 82 | +To base64-decode UTF-8-encoded data back into a Unicode string, [UTF-8-decode it](https://github.com/mathiasbynens/utf8.js#utf8decodebytestring) after base64-decoding it: |
| 83 | + |
| 84 | +```js |
| 85 | +var encoded = 'Zm9vIMKpIGJhciDwnYyGIGJheg=='; |
| 86 | +var bytes = base64.decode(encoded); |
| 87 | +var text = utf8.decode(bytes); |
| 88 | +console.log(text); |
| 89 | +// → 'foo © bar 𝌆 baz' |
| 90 | +``` |
| 91 | + |
| 92 | +## Support |
| 93 | + |
| 94 | +_base64_ is designed to work in at least Node.js v0.10.0, Narwhal 0.3.2, RingoJS 0.8-0.9, PhantomJS 1.9.0, Rhino 1.7RC4, as well as old and modern versions of Chrome, Firefox, Safari, Opera, and Internet Explorer. |
| 95 | + |
| 96 | +## Unit tests & code coverage |
| 97 | + |
| 98 | +After cloning this repository, run `npm install` to install the dependencies needed for development and testing. You may want to install Istanbul _globally_ using `npm install istanbul -g`. |
| 99 | + |
| 100 | +Once that’s done, you can run the unit tests in Node using `npm test` or `node tests/tests.js`. To run the tests in Rhino, Ringo, Narwhal, and web browsers as well, use `grunt test`. |
| 101 | + |
| 102 | +To generate the code coverage report, use `grunt cover`. |
| 103 | + |
| 104 | +## Author |
| 105 | + |
| 106 | +| [](https://twitter.com/mathias "Follow @mathias on Twitter") | |
| 107 | +|---| |
| 108 | +| [Mathias Bynens](https://mathiasbynens.be/) | |
| 109 | + |
| 110 | +## License |
| 111 | + |
| 112 | +_base64_ is available under the [MIT](https://mths.be/mit) license. |
0 commit comments