tweetnacl-util-js

tweetnacl-util provides four small, dependency-free functions — decodeUTF8, encodeUTF8, decodeBase64, and encodeBase64 — for converting between JavaScript strings and the Uint8Array byte arrays that TweetNaCl.js’s cryptographic functions expect. It was split out of the core TweetNaCl.js library so projects working with NaCl keys, nonces, and ciphertext have a ready encoding layer without writing their own.

The library targets both Node.js and browsers, branching its Base64 implementation between Buffer (Node) and atob/btoa (browsers) at load time. The maintainer’s README candidly recommends the StableLib packages (@stablelib/utf8, @stablelib/base64) or native TextEncoder/TextDecoder for new projects instead, since this package prioritizes simplicity over performance, doesn’t work under React Native, and makes no constant-time guarantees for Base64 decoding.

What You Get

• decodeUTF8/encodeUTF8 for converting strings to and from Uint8Array
• decodeBase64/encodeBase64 with RFC 4648 validation that throws on malformed input
• TypeScript type definitions (nacl-util.d.ts) bundled with the package
• A drop-in nacl.util namespace for backward compatibility with code written against early TweetNaCl.js releases

Common Use Cases

• Converting a TweetNaCl-generated key or nonce (Uint8Array) into a Base64 string for storage or transmission
• Decoding a Base64-encoded ciphertext received over the network back into bytes for nacl.secretbox.open
• Turning a user-supplied password or message string into UTF-8 bytes before hashing or encrypting
• Maintaining legacy browser code that still references the old nacl.util global from TweetNaCl.js’s early releases

Under The Hood

Architecture The entire library is a single UMD module (nacl-util.js) wrapped in an IIFE that detects whether it’s loaded via CommonJS or as a plain <script> tag and exports a util object accordingly; there’s no internal layering beyond that — all four functions are properties on one object literal, with an environment check (typeof atob === 'undefined') branching the Base64 implementation between a Node.js Buffer-based path and a browser atob/btoa-based path at module-load time rather than per call.

Tech Stack Vanilla ES5-style JavaScript with zero runtime dependencies; devDependencies are limited to tape (test runner), browserify (bundling the browser test), and uglify-js (producing the pre-minified nacl-util.min.js via the build script). TypeScript consumers get hand-written definitions in nacl-util.d.ts rather than compiler-generated output, and the package ships both a raw and pre-minified UMD bundle alongside its CommonJS entry point.

Code Quality Tests in test/test.js use tape and cover Base64 round-tripping against RFC 4648 vectors, explicit malformed-input cases asserting decodeBase64 throws, and a UTF-8 round-trip test against unicode strings; a companion browser-test bundle is built via browserify for manual browser verification. Error handling is minimal but present — decodeBase64 validates input against a regex before decoding and throws TypeError, decodeUTF8 throws TypeError on non-string input — but there is no linter, no type-checked source, and CI is limited to a bare .travis.yml with no visible active status.

API Design The public API is extremely small and immediately learnable — four consistently named functions (decode/encodeUTF8, decode/encodeBase64) requiring zero configuration to call, documented tersely in the README. The real friction is that the maintainer explicitly steers users elsewhere: the README’s own “Notice” section recommends StableLib or native TextEncoder/TextDecoder instead, and the package is called out as not working under React Native, making this more a compatibility shim for legacy TweetNaCl.js code than a library to reach for in new projects.