Merge pull request #910 from alexcrichton/fix-text-encoder-edge

Fix polyfill of `TextEncoder` and `TextDecoder`

guide/src/SUMMARY.md

@@ -38,6 +38,7 @@
   - [Command Line Interface](./reference/cli.md)
   - [Optimizing for Size](./reference/optimize-size.md)
   - [Supported Rust Targets](./reference/rust-targets.md)
+  - [Supported Browsers](./reference/browser-support.md)
   - [Supported Types](./reference/types.md)
     - [Imported JavaScript Types](./reference/types/imported-js-types.md)
     - [Exported Rust Types](./reference/types/exported-rust-types.md)

guide/src/reference/browser-support.md

@@ -0,0 +1,61 @@
+# Supported Browsers
+
+The output of `wasm-bindgn` includes a JS file, and as a result it's good to
+know what browsers that file is expected to be used in! By default the output
+uses ES modules which isn't implemented in all browsers today, but when using a
+bundler (like Webpack) you should be able to produce output suitable for all
+browsers.
+
+Firefox, Chrome, Safari, and Edge browsers are all supported by
+`wasm-bindgen`. If you find a problem in one of these browsers please [report
+it] as we'd like to fix the bug! If you find a bug in another browser we would
+also like to be aware of it!
+
+## Caveats
+
+* **IE 11** - `wasm-bindgen` by default requires support for
+  `WebAssembly`, but no version of IE currently supports `WebAssembly`. You can
+  support IE by [compiling wasm files to JS using `wasm2js`][w2js] (you can [see
+  an example of doing this too](../examples/wasm2js.html)). Note
+  that at this time no bundler will do this by default, but we'd love to
+  document plugins which do this if you are aware of one!
+
+* **Edge** - the `TextEncoder` and `TextDecoder` APIs are not currently
+  available in Edge which `wasm-bindgen` uses to encode/decode strings between
+  JS and Rust. You can polyfill this with at least one of two strategies:
+
+  1. If using a bundler, you can likely configure the bundler to polyfill these
+     types by default. For example if you're using Webpack you can use the
+     [`ProvidePlugin` interface][wpp] like so after also adding
+     [`text-encoding`] to your `package.json`
+
+     ```js
+     const webpack = require('webpack');
+
+     module.exports = {
+         plugins: [
+             new webpack.ProvidePlugin({
+               TextDecoder: ['text-encoding', 'TextDecoder'],
+               TextEncoder: ['text-encoding', 'TextEncoder']
+             })
+         ]
+
+         // ... other configuration options
+     };
+     ```
+
+  2. If you're not using a bundler you can also include support manually by
+     adding a `<script>` tag which defines the `TextEncoder` and `TextDecoder`
+     globals. [This StackOverflow question][soq] has some example usage and MDN
+     has a [`TextEncoder` polyfill implementation][mdntepi] to get you started
+     as well.
+
+If you find other incompatibilities please report them to us! We'd love to
+either keep this list up-to-date or fix the underlying bugs :)
+
+[report it]: https://github.com/rustwasm/wasm-bindgen/issues/new
+[w2js]: https://github.com/WebAssembly/binaryen
+[wpp]: https://webpack.js.org/plugins/provide-plugin/
+[`text-encoding`]: https://www.npmjs.com/package/text-encoding
+[soq]: https://stackoverflow.com/questions/40662142/polyfill-for-textdecoder/46549188#46549188
+[mdntepi]: https://developer.mozilla.org/en-US/docs/Web/API/TextEncoder#Polyfill