README.md.ejs 2.7 KB

1234567891011121314151617181920212223242526272829303132333435363738394041424344454647484950515253545556575859606162636465666768697071727374757677787980818283848586878889
  1. # WebAssembly Feature Detection
  2. A small library to detect which features of WebAssembly are supported.
  3. - ✅ Runs in browsers, Node and Deno
  4. - ✅ Tree-shakable (only bundle the detectors you use)
  5. - ✅ Provided as an ES6, CommonJS and UMD module.
  6. - ✅ CSP compatible
  7. - ✅ All detectors add up to only ~<%= gzippedSize %>B gzipped
  8. ## Installation
  9. ```
  10. npm install -g wasm-feature-detect
  11. ```
  12. ## Usage
  13. ```html
  14. <script type="module">
  15. import { simd } from "wasm-feature-detect";
  16. if (await simd()) {
  17. /* SIMD support */
  18. } else {
  19. /* No SIMD support */
  20. }
  21. </script>
  22. ```
  23. ### Hotlinking from Unpkg
  24. ```html
  25. <script type="module">
  26. import { simd } from "https://unpkg.com/wasm-feature-detect?module";
  27. // ...
  28. </script>
  29. ```
  30. If required, there’s also a UMD version
  31. ```html
  32. <script src="https://unpkg.com/wasm-feature-detect/dist/umd/index.js"></script>
  33. <script>
  34. if (await wasmFeatureDetect.simd()) {
  35. // ...
  36. }
  37. </script>
  38. ```
  39. ## Detectors
  40. All detectors return a `Promise<bool>`.
  41. | Function | Proposal |
  42. | -------- | -------- |
  43. <% for (let detector of detectors) { _%>
  44. | `<%= detector.func %>()` | [<%= detector.name %>](<%= detector.proposal %>) |
  45. <%_ } %>
  46. ## Why are all the tests async?
  47. The _technical_ reason is that some tests might have to be augmented to be asynchronous in the future. For example, Firefox is planning to [make a change][ff coop] that would require a `postMessage` call to detect SABs, which are required for threads.
  48. The _other_ reason is that you _should_ be using `WebAssembly.compile`, `WebAssembly.instantiate`, or their streaming versions `WebAssembly.compileStreaming` and `WebAssembly.instantiateStreaming`, which are all asynchronous. You should already be prepared for asynchronous code when using WebAssembly!
  49. ## Contributing
  50. If you want to contribute a new feature test, all you need to do is create a new folder in `src/detectors` and it will be automatically picked up. The folder may contain a `module.wat` file, which will be compiled using [`wabt.js`](https://github.com/AssemblyScript/wabt.js).
  51. ```wat
  52. ;; Name: <Name of the feature for the README>
  53. ;; Proposal: <Link to the proposal’s explainer/repo>
  54. ;; Features: <Space-separated list of WasmFeatures from wabt.js>
  55. (module
  56. ;; More WAT code here
  57. )
  58. ```
  59. The folder can also contain an optional `index.js` file, whose default export must be an async function. This function can do additional testing in JavaScript and must return a boolean. See the “threads” detector as an example.
  60. It must contain at least one of `module.wat` or `index.js`.
  61. [ff coop]: https://groups.google.com/forum/#!msg/mozilla.dev.platform/IHkBZlHETpA/dwsMNchWEQAJ
  62. [wat2wasm]: https://github.com/webassembly/wabt
  63. ---
  64. License Apache-2.0