js-nacl: High-level libsodium API

Common errors

• TypeError: nacl is not defined

  cause Attempting to use the `nacl` API object directly without first instantiating it through `nacl_factory.instantiate()`.
  fix Always call `nacl_factory.instantiate((naclInstance) => { /* use naclInstance */ })` to get the `nacl` object. The instantiation is asynchronous.

• TypeError: nacl_factory.instantiate is not a function

  cause The `nacl_factory` object was not correctly loaded or required. In Node.js, often caused by an incorrect `require` path or trying to use ES Modules `import`.
  fix For Node.js, use `const nacl_factory = require('js-nacl/lib/nacl_factory.js');`. For browsers, ensure `<script src="lib/nacl_factory.js">` is correctly placed before your script.

• SecurityError: The operation is not supported.

  cause This error typically occurs in a browser environment when `window.crypto.getRandomValues` is not available or accessible, which is required by `js-nacl`.
  fix Ensure the browser is modern enough to support `window.crypto.getRandomValues` and that the script is running in a secure context (e.g., HTTPS) if the browser enforces it.

Warnings

• breaking The `nacl_factory.instantiate` function's API changed to expect a callback as its first argument, which receives the `nacl` instance.
  Fix: Update calls from `nacl_factory.instantiate()` returning a value to `nacl_factory.instantiate((nacl_instance) => { /* use nacl_instance */ })`.
• breaking The library API was changed from directly providing a `nacl` module to providing `nacl_factory` with an `instantiate` function that returns the `nacl` instance.
  Fix: Migrate code to use `nacl_factory.instantiate()` to obtain the functional `nacl` object instead of importing/accessing `nacl` directly.
• deprecated Functions `crypto_sign_keypair_from_seed` and `crypto_box_keypair_from_seed` were renamed to `crypto_sign_seed_keypair` and `crypto_box_seed_keypair` respectively to align with libsodium naming conventions.
  Fix: Update calls to the new names: `crypto_sign_seed_keypair` and `crypto_box_seed_keypair`. The old names are deprecated aliases and may be removed in future versions.
• gotcha js-nacl is known to have issues and potential data corruption when running on Safari version 5.1.x, especially with Javascript debug mode disabled.
  Fix: Upgrade to Safari 7.0 or a newer version. The library runs correctly on modern versions of Chrome, Firefox, and Safari.
• gotcha Browser usage of js-nacl requires support for the `window.crypto.getRandomValues` API for secure random number generation.
  Fix: Ensure that the target browser environment supports `window.crypto.getRandomValues`. Most modern browsers provide this API.
• gotcha As of version 1.3.2, the Emscripten-compiled code no longer adds a listener to the `uncaughtException` event in Node.js.
  Fix: Applications using `js-nacl` in Node.js should implement their own `uncaughtException` handling if required, as the library no longer provides this default behavior.

Install

• npm install js-nacl npm
• yarn add js-nacl yarn
• pnpm add js-nacl pnpm

Imports

• nacl_factory
  wrong:

  import { nacl_factory } from 'js-nacl';

  correct:

  const nacl_factory = require('js-nacl/lib/nacl_factory.js');

  For Node.js, the module path must point directly to `lib/nacl_factory.js`. It exposes a factory, not the `nacl` instance directly.
• nacl
  wrong:

  const nacl = require('js-nacl');

  correct:

  nacl_factory.instantiate((nacl) => { /* use nacl API */ });

  The core `nacl` API object is provided asynchronously via a callback to `nacl_factory.instantiate()` in both Node.js and browser environments. It's not a direct export or global.
• Browser Global
  wrong:

  import * as nacl from 'js-nacl';

  correct:

  <script src="node_modules/js-nacl/lib/nacl_factory.js"></script>
  <script>
    nacl_factory.instantiate((nacl) => { /* use nacl */ });
  </script>

  In a browser, the library creates a global `nacl_factory` object. ESM imports are not supported for this package.

Quickstart

This quickstart demonstrates how to instantiate the js-nacl library in Node.js, generate cryptographic keys, nonces, and compute a SHA512 hash using the libsodium API.

const nacl_factory = require('js-nacl/lib/nacl_factory.js');

nacl_factory.instantiate((nacl) => {
  if (!nacl) {
    console.error('Failed to instantiate nacl library.');
    return;
  }

  // Generate a random 32-byte key
  const key = nacl.random_bytes(nacl.crypto_box_SECRETKEYBYTES);
  console.log('Generated key (hex):', nacl.to_hex(key));

  // Example: Generate a random nonce
  const nonce = nacl.random_bytes(nacl.crypto_box_NONCEBYTES);
  console.log('Generated nonce (hex):', nacl.to_hex(nonce));

  // Example: Hash a message
  const message = nacl.from_string('Hello, js-nacl!');
  const hash = nacl.crypto_hash(message);
  console.log('Hashed message (hex):', nacl.to_hex(hash));
});