{"id":16238,"library":"text-encoding-utf-8","title":"UTF-8 Text Encoding Polyfill","description":"text-encoding-utf-8 is a partial polyfill for the Web's Encoding Living Standard API, specifically designed to provide UTF-8 encoding and decoding capabilities for environments lacking native `TextEncoder` and `TextDecoder` implementations, such as older versions of Safari on iOS. The current stable version is 1.0.2, last updated over seven years ago. Its key differentiator is its strict focus on UTF-8 only, resulting in a smaller footprint compared to full polyfills like `text-encoding`. While it served a critical role historically, modern browsers and Node.js environments universally support `TextEncoder` and `TextDecoder` natively, rendering this polyfill largely obsolete for new development.","status":"abandoned","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/arv/text-encoding-utf-8","tags":["javascript","encoding","decoding","living standard"],"install":[{"cmd":"npm install text-encoding-utf-8","lang":"bash","label":"npm"},{"cmd":"yarn add text-encoding-utf-8","lang":"bash","label":"yarn"},{"cmd":"pnpm add text-encoding-utf-8","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"While CommonJS `require` might work, the package's age (v1.x, 7+ years old) predates widespread native ESM support in Node.js. For browser environments, `<script src=\"encoding.js\"></script>` makes globals available.","wrong":"const { TextEncoder, TextDecoder } = require('text-encoding-utf-8');","symbol":"TextEncoder","correct":"import { TextEncoder, TextDecoder } from 'text-encoding-utf-8';"},{"note":"A direct require of the package likely returns an object with both `TextEncoder` and `TextDecoder` properties, or it makes them global. Named imports are the most explicit way if using a bundler.","wrong":"const TextDecoder = require('text-encoding-utf-8').TextDecoder;","symbol":"TextDecoder","correct":"import { TextEncoder, TextDecoder } from 'text-encoding-utf-8';"},{"note":"In older environments or when using the provided `encoding.js` script in HTML, importing the package as a side-effect (or loading the script) is intended to make `TextEncoder` and `TextDecoder` available globally.","symbol":"Global Polyfill","correct":"import 'text-encoding-utf-8';"}],"quickstart":{"code":"import { TextEncoder, TextDecoder } from 'text-encoding-utf-8';\n\n// Basic UTF-8 Encoding\nconst encoder = new TextEncoder('utf-8');\nconst originalString = 'Hello, world! 👋';\nconst encodedBytes = encoder.encode(originalString);\n\nconsole.log('Original String:', originalString);\nconsole.log('Encoded Bytes (Uint8Array):', encodedBytes);\n\n// Basic UTF-8 Decoding\nconst decoder = new TextDecoder('utf-8');\nconst decodedString = decoder.decode(encodedBytes);\n\nconsole.log('Decoded String:', decodedString);\n\n// Streaming Decode (example concept - next_chunk needs implementation)\nlet streamDecoder = new TextDecoder('utf-8');\nlet resultString = '';\n\n// Imagine 'chunk1', 'chunk2', etc., are Uint8Arrays from a stream\nconst chunk1 = encoder.encode('This is the first part. ');\nconst chunk2 = encoder.encode('And this is the second part.');\n\nresultString += streamDecoder.decode(chunk1, { stream: true });\nresultString += streamDecoder.decode(chunk2, { stream: true });\nresultString += streamDecoder.decode(); // Finish the stream\n\nconsole.log('Stream Decoded String:', resultString);","lang":"javascript","description":"Demonstrates basic UTF-8 encoding and decoding using TextEncoder and TextDecoder, including a conceptual example of streaming decode."},"warnings":[{"fix":"Ensure that only 'utf-8' or 'UTF-8' are passed as encoding arguments to TextEncoder and TextDecoder constructors. If other encodings are needed, use a comprehensive polyfill or check for native API support.","message":"This polyfill only supports UTF-8. Attempting to use any other encoding (e.g., 'iso-8859-1', 'gbk') will result in an error or unexpected behavior, as it will fall back to UTF-8 without explicit error.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For new projects, avoid this polyfill entirely. For existing projects, consider removing it and relying on native browser/Node.js APIs. Use feature detection (`typeof TextEncoder !== 'undefined'`) if targeting very old environments that lack native support.","message":"The package is effectively unmaintained, with the last publish over seven years ago. Modern browsers (Chrome, Firefox, Edge, Safari) and Node.js environments have native, highly optimized implementations of TextEncoder and TextDecoder. Relying on this polyfill can introduce unnecessary bundle size and potential compatibility issues.","severity":"deprecated","affected_versions":">=1.0.0"},{"fix":"Implement robust feature detection to conditionally load or apply the polyfill only when `TextEncoder` or `TextDecoder` are genuinely missing. For example: `if (typeof TextEncoder === 'undefined') { require('text-encoding-utf-8'); }`.","message":"Using this polyfill in environments that already have native `TextEncoder` and `TextDecoder` can lead to conflicts, unexpected behavior, or simply redundant code execution.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Modify your code to only use 'utf-8' or 'UTF-8' as the encoding string. If other encodings are required, this polyfill is not suitable, and you should use a more comprehensive library or native APIs.","cause":"The `text-encoding-utf-8` polyfill is strictly limited to UTF-8 and does not support other character encodings.","error":"Error: Unknown encoding: 'iso-8859-1'"},{"fix":"Ensure the polyfill script (`encoding.js`) is loaded in HTML, or for Node.js/bundlers, verify the import statement is correct (`import 'text-encoding-utf-8';` for global patching, or `import { TextEncoder } from 'text-encoding-utf-8';` for named imports).","cause":"The `TextEncoder` (or `TextDecoder`) global object was not made available. This can happen if the polyfill script was not properly loaded, or if the import mechanism didn't expose the globals as expected.","error":"ReferenceError: TextEncoder is not defined"}],"ecosystem":"npm"}