{"id":12327,"library":"utf8","title":"UTF-8 Encoder/Decoder for JavaScript","description":"The `utf8.js` package, currently at its stable version 3.0.0 (last updated in late 2017), provides a comprehensively tested and robust JavaScript implementation for encoding and decoding UTF-8 strings. It distinguishes itself by strictly adhering to the Encoding Standard, ensuring precise handling of all scalar Unicode code point values. A core aspect of its design is strict error handling: the library explicitly throws an `Error` when attempting to encode non-scalar values (such as lone surrogates) or when encountering malformed UTF-8 data during decoding. This approach prioritizes data integrity over silent error correction. For developers requiring the ability to encode or decode non-scalar values, the related `WTF-8` library is recommended. Given its foundational utility and mature status, the project is considered to be in maintenance mode, receiving updates primarily for critical issues rather than frequent feature additions.","status":"maintenance","version":"3.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/mathiasbynens/utf8.js","tags":["javascript","charset","encoding","unicode","utf8"],"install":[{"cmd":"npm install utf8","lang":"bash","label":"npm"},{"cmd":"yarn add utf8","lang":"bash","label":"yarn"},{"cmd":"pnpm add utf8","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"This package (v3.0.0) is primarily a CommonJS module. Direct ES module imports are not officially supported and will require a bundler or dynamic import for compatibility.","wrong":"import utf8 from 'utf8';","symbol":"utf8","correct":"const utf8 = require('utf8');"},{"note":"When included directly in a browser via a <script> tag, the library exposes a global `utf8` object on the `window`.","symbol":"global utf8 object","correct":"<!-- In browser -->\n<script src=\"utf8.js\"></script>\n<script>\n  const encoded = utf8.encode('Hello');\n</script>"},{"note":"The `encode` method is accessed as a property of the main `utf8` object.","wrong":"const { encode } = require('utf8'); // Not a named export","symbol":"utf8.encode","correct":"const utf8 = require('utf8');\nconst encodedString = utf8.encode('Hello, world! 😊');"}],"quickstart":{"code":"const utf8 = require('utf8');\n\n// Example 1: Encoding a basic string\nconst originalString1 = 'Hello, world! 👋';\nconst encodedString1 = utf8.encode(originalString1);\nconsole.log(`Original: '${originalString1}'`);\nconsole.log(`Encoded:  '${encodedString1}'`);\nconst decodedString1 = utf8.decode(encodedString1);\nconsole.log(`Decoded:  '${decodedString1}'`);\n\n// Example 2: Encoding a string with a multi-byte Unicode character\n// U+1F60A SMILING FACE WITH SMILING EYES\nconst originalString2 = 'Smiling face: \\uD83D\\uDE0A'; \nconst encodedString2 = utf8.encode(originalString2);\nconsole.log(`\\nOriginal: '${originalString2}'`);\nconsole.log(`Encoded:  '${encodedString2}'`);\nconst decodedString2 = utf8.decode(encodedString2);\nconsole.log(`Decoded:  '${decodedString2}'`);\n\n// Example 3: Demonstrate version access\nconsole.log(`\\nutf8.js version: ${utf8.version}`);","lang":"javascript","description":"This quickstart demonstrates how to encode and decode UTF-8 strings, including those with multi-byte Unicode characters, and how to check the library's version."},"warnings":[{"fix":"Ensure input strings are 'well-formed' Unicode. Pre-process strings to remove or replace lone surrogates (e.g., with `U+FFFD` replacement character) before calling `utf8.encode()`. For scenarios requiring encoding of non-scalar values, consider using the `WTF-8` library.","message":"The `utf8.encode()` method will throw an `Error` if the input JavaScript string contains a non-scalar value, specifically a lone surrogate (a `U+D800` to `U+DFFF` code point not part of a valid surrogate pair). This strict behavior is by design, adhering to the Encoding Standard for proper UTF-8.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Verify the source of the input `byteString` to ensure it is correctly encoded as UTF-8. Implement robust error handling using `try...catch` blocks around `utf8.decode()` calls to gracefully manage potentially malformed input, or pre-validate the input if possible.","message":"The `utf8.decode()` method will throw an `Error` when it detects malformed UTF-8 byte sequences in the input `byteString`. This strictness prevents silent data corruption that can occur with lenient decoders.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Validate and sanitize input strings to ensure they are well-formed Unicode before passing them to `utf8.encode()`. You can replace lone surrogates or use `String.prototype.toWellFormed()` (if targeting environments that support it) or related libraries.","cause":"Attempting to encode a JavaScript string containing an unpaired (lone) surrogate character (e.g., `\\uD800` without a trailing `\\uDC00` to `\\uDFFF`).","error":"Error: A lone surrogate code point was found."},{"fix":"Check the origin and integrity of the byte string being decoded. Ensure it has been correctly encoded as UTF-8. Wrap `utf8.decode()` calls in a `try...catch` block to handle invalid input gracefully, e.g., by logging the error and using a fallback or replacement.","cause":"The input string provided to `utf8.decode()` contains byte sequences that do not conform to valid UTF-8 encoding rules.","error":"Error: Malformed UTF-8 data."},{"fix":"For Node.js, ensure you use `const utf8 = require('utf8');` in CommonJS modules (`.js` files where `\"type\": \"module\"` is not set or in `.cjs` files). If working in an ES module environment (`.mjs` files or `\"type\": \"module\"` in `package.json`), you may need to use dynamic `import('utf8')` or rely on a bundler like Webpack or Rollup to handle the CommonJS dependency.","cause":"This package is a CommonJS module. Using `require()` in an ES module context or `import` in a CommonJS context will lead to module resolution errors.","error":"TypeError: require is not a function (in ES module context) or SyntaxError: Cannot use import statement outside a module (in CJS context)"}],"ecosystem":"npm"}