v3.0.0

Major release: standards-compliant v3/v5, new v6/v7, secure random values on React Native without a polyfill, and an ES module build.

Tested on React Native 0.88.1 (iOS and Android, New Architecture, including Android R8) and Expo SDK 58 (development build and Expo Go).

Migrating from 2.x

• v3() and v5() return different values. 2.x produced non-standard UUIDs (#52); 3.x matches RFC 9562, the uuid package and Python. Re-generate any stored v3/v5 UUIDs, or keep 2.x for reading old ones.
• parse() throws TypeError('Invalid UUID') for invalid input instead of returning zero-filled bytes. Call validate() first if input may be invalid. v3()/v5() also throw for an invalid namespace string.
• Deep imports are no longer supported (e.g. react-native-uuid/dist/v4). Import from react-native-uuid instead.
• validate() accepts versions 6-8 and the max UUID (ffffffff-ffff-ffff-ffff-ffffffffffff).
• Node.js 22+ is required.
• React Native: run pod install and rebuild the app to link the native random module.

Changes

Breaking

• v3() and v5() now return RFC 9562 compliant UUIDs that match the uuid npm package and Python's uuid module. Previously the hex text of the hash digest was used as the UUID bytes, so every v3/v5 value differs from 2.x. Re-generate any stored v3/v5 UUIDs. (#52, #18)
• parse() throws TypeError('Invalid UUID') for invalid input instead of returning zero-filled bytes. v3() and v5() throw the same error for an invalid namespace string.
• validate() and version() accept UUID versions 6-8 and the max UUID.
• The package uses an exports map. Deep imports such as react-native-uuid/dist/v4 no longer work; import from react-native-uuid. Internal helpers that were only reachable that way (md5, sha1, bytesToString, etc.) were removed or replaced.
• Build output moved to dist/cjs (CommonJS) and dist/esm (ES modules).
• v4() no longer accepts the legacy string format argument.
• Minimum Node.js version is now 22 (npm 10). Node.js 18 and 20 are end-of-life; CI tests Node.js 22, 24 and 26 and publishes with 26.
• React Native 0.74 or newer is required (declared as an optional peer dependency). React Native apps need pod install and a native rebuild to link the new native random module.

Added

• v6() and v7() (RFC 9562), plus v1ToV6() and v6ToV1(). Output matches the uuid package; v7() is strictly increasing within a process.
• MAX constant, and v3.DNS / v3.URL / v5.DNS / v5.URL properties, matching uuid.
• stringify(), rng() and randomSource() exported from the package entry point.
• Named exports (import {v4} from 'react-native-uuid') alongside the default uuid object, so bundlers can drop unused code.
• ES module build, with type declarations for both CommonJS and ESM consumers.
• Exported types: V1Options, V4Options, V6Options, V7Options, UUIDBuffer, GenerateUUID.
• v3() / v5() accept a plain number array as the name.
• API docs (docs/) regenerated for the public API with descriptions for every function. npm run docs works again (config in typedoc.json).

Changed

• Generators return string when called without buf and the buffer's type when called with one, so as string casts are no longer needed.
• buf accepts number[] or Uint8Array for every generator. Writing past the end of a Uint8Array, or at a negative offset, throws RangeError.
• v4() no longer modifies the options.random array passed in, and throws if it has fewer than 16 bytes.
• Faster: v3()/v5() ~3-4x, parse() ~3.5x, v4() ~1.5x (uses crypto.randomUUID when available) compared with 2.x. Random bytes from crypto.getRandomValues are fetched in 256-byte batches.
• MD5 and SHA-1 rewritten to operate on bytes (verified against RFC 1321 / FIPS 180 vectors and Node.js crypto).

Security

• rng() (used by v1(), v4(), v6() and v7()) uses, in order: crypto.getRandomValues; a bundled native module on React Native (iOS SecRandomCopyBytes, Android SecureRandom), so apps are secure without a polyfill; Math.random only as a last resort.
• npm releases are published from CI with trusted publishing (OIDC) and provenance, without a long-lived npm token.

Fixed

• v1() without options no longer throws "Can't create more than 10M uuids/sec" after ~10,000 calls.
• v1() honors clockseq: 0, msecs: 0 and nsecs: 0 instead of replacing them with defaults.
• v3() / v5() no longer overflow the stack for names larger than ~100 KB.
• V1Options and V4Options fields are optional, so partial options type-check.
• v4() prefers options.random over options.rng, matching uuid.
• The CI publish job now runs on v* tag pushes; previously the workflow never triggered on tags.

Tooling and maintenance

ESLint 10, Jest 30, TypeScript 5.9, TypeDoc 0.28; dual CommonJS/ESM build; package, bundle-size and coverage checks in CI; trusted publishing with provenance. See CHANGELOG.md for the full list.