Skip to content

Commit 6f4c8ff

Browse files
committed
doc: clarify encoding bundle versions
1 parent 3bddbfa commit 6f4c8ff

File tree

1 file changed

+22
-12
lines changed

1 file changed

+22
-12
lines changed

README.md

Lines changed: 22 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -100,29 +100,39 @@ _These are only provided as a compatibility layer, prefer hardened APIs instead
100100

101101
### Lite version
102102

103-
If you don't need support for legacy multi-byte encodings, you can use the lite import:
104-
```js
105-
import { TextDecoder, TextEncoder } from '@exodus/bytes/encoding-lite.js'
106-
import { TextDecoderStream, TextEncoderStream } from '@exodus/bytes/encoding-lite.js' // Requires Streams
107-
```
103+
Alternate exports exist that can help reduce bundle size:
104+
105+
* `@exodus/bytes/encoding-browser.js` - resolves to a tiny import in browser bundles, preferring native `TextDecoder` / `TextEncoder`.
106+
For non-browsers (Node.js, React Native), loads a full implementation.
108107

109-
This reduces the bundle size 9x:\
110-
from 94 KiB gzipped for `@exodus/bytes/encoding.js` to 10 KiB gzipped for `@exodus/bytes/encoding-lite.js`.\
111-
(For comparison, `text-encoding` and `iconv-lite` are each over 195 KiB gzipped):
108+
* `@exodus/bytes/encoding-lite.js` - if you don't need support for legacy multi-byte encodings.
112109

110+
Reduces the bundle size 9x, while still keeping `utf-8`, `utf-16le`, `utf-16be` and all single-byte encodings specified by the spec.
111+
The only difference is support for legacy multi-byte encodings.
112+
113+
See [the list of encodings](https://encoding.spec.whatwg.org/#names-and-labels).
114+
115+
This can be useful for example in React Native global TextDecoder polyfill,
116+
if you are sure that you don't need legacy multi-byte encodings support.
117+
118+
119+
Bundle size comparison:
113120
| import | size |
114121
| - | - |
115122
| `@exodus/bytes/encoding-browser.js` | <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/encoding-browser.js?style=flat-square)</sub> |
116123
| `@exodus/bytes/encoding-lite.js` | <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/encoding-lite.js?style=flat-square)</sub> |
117124
| `@exodus/bytes/encoding.js` | <sub>![](https://img.shields.io/bundlejs/size/@exodus/bytes/encoding.js?style=flat-square)</sub> |
118125
| `text-encoding` | <sub>![](https://img.shields.io/bundlejs/size/text-encoding?style=flat-square)</sub> |
119-
| `iconv-lite` | <sub>![](https://img.shields.io/bundlejs/size/iconv-lite?style=flat-square)</sub> |
126+
| `iconv-lite` | <sub>![](https://img.shields.io/bundlejs/size/iconv-lite/lib/index.js?style=flat-square)</sub> |
120127
| `whatwg-encoding` | <sub>![](https://img.shields.io/bundlejs/size/whatwg-encoding?style=flat-square)</sub> |
121128

122-
It still supports `utf-8`, `utf-16le`, `utf-16be` and all single-byte encodings specified by the spec,
123-
the only difference is support for legacy multi-byte encodings.
129+
In general:
130+
131+
1. Libraries are advised to use single-purpose hardened `@exodus/bytes/utf8.js` / `@exodus/bytes/utf16.js` APIs for Unicode or
132+
global `TextDecoder` for the remaining WHATWG encodings
124133

125-
See [the list of encodings](https://encoding.spec.whatwg.org/#names-and-labels).
134+
2. Applications (including React Native apps) are advised to load either `@exodus/bytes/encoding-lite.js` or `@exodus/bytes/encoding.js`
135+
(depending on whether legacy multi-byte support is needed) and use that a a global polyfill.
126136

127137
## API
128138

0 commit comments

Comments
 (0)