Isomorphic.js Utilities

Common errors

• TypeError: Cannot read properties of undefined (reading 'isBrowser') or TypeError: Cannot read properties of null (reading 'isBrowser')

  cause The internal `yjs` dependency, which provides environment detection functions like `isBrowser` and `isNode`, failed to load or initialize correctly.
  fix Ensure `yjs` is correctly installed as a direct dependency (`npm install yjs` or `yarn add yjs`). Check for any module resolution issues if you're using a custom build setup.

• Error: require() of ES Module CJS_MODULE from CommonJS module JS_FILE not supported. Did you mean to import CJS_MODULE?

  cause Attempting to `require()` an ESM-only package or a package that has explicit `exports` that prevent CJS `require` paths, particularly relevant after v0.2.0 and v0.2.3.
  fix Switch to ESM import syntax: `import { functionName } from 'isomorphic.js';`. Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` files).

• TypeError: isomorphic.randomBytes is not a function

  cause Incorrectly importing the `randomBytes` function, possibly through a default import or a CommonJS `require` that doesn't destructure correctly.
  fix Use a named ESM import: `import { randomBytes } from 'isomorphic.js';` or for CommonJS: `const { randomBytes } = require('isomorphic.js');`.

Warnings

• breaking Version 0.2.0 introduced 'conditional exports' via `package.json` `exports` field. This can cause issues with older build tools or Node.js versions that do not fully support this feature, potentially leading to import resolution errors.
  Fix: Ensure your Node.js environment is v12.19.0+ or v14.13.0+ for full `exports` map support. Update your bundler (e.g., Webpack, Rollup) to a version compatible with modern package exports.
• breaking Version 0.2.3 further refined module resolution by adding the `module` field and additional `exports` configurations. While improving ESM compatibility, this could alter resolution paths for some CJS consumers, especially when coupled with specific bundler configurations.
  Fix: Verify your import statements against the package's `package.json` `exports` map. For CommonJS, `require('isomorphic.js')` should still work, but mixed CJS/ESM projects might need explicit `"type": "module"` or `.mjs` extensions.
• gotcha The library has a direct runtime dependency on `yjs`. If `yjs` is not correctly installed or resolvable in your environment, `isomorphic.js` will fail to load or execute correctly, particularly for environment detection features like `isBrowser` and `isNode`.
  Fix: Ensure `yjs` is listed in your project's `dependencies` and properly installed via `npm install yjs` or `yarn add yjs`.
• gotcha The `encrypt` and `decrypt` functions, while provided for isomorphic crypto, are highly simplified in their public API. For production use, you must implement robust key management, secure random IV generation, and potentially authenticated encryption modes (e.g., AES-GCM) beyond what these functions might directly abstract. The example provided uses a dummy key.
  Fix: Do not use the `encrypt` and `decrypt` functions with insecure or hardcoded keys in production. Consult cryptographic best practices for key derivation, key storage, and secure encryption schemes. Consider a higher-level crypto library if advanced features like key management and secure defaults are needed out-of-the-box.

Install

• npm install isomorphic.js npm
• yarn add isomorphic.js yarn
• pnpm add isomorphic.js pnpm

Imports

• randomBytes
  wrong:

  const randomBytes = require('isomorphic.js').randomBytes;

  correct:

  import { randomBytes } from 'isomorphic.js';

  ESM named import is preferred. CommonJS `require` still works but ESM is best practice for modern projects, especially with Node.js support for `exports`.
• isBrowser
  wrong:

  import isomorphic from 'isomorphic.js'; const isBrowser = isomorphic.isBrowser;

  correct:

  import { isBrowser, isNode } from 'isomorphic.js';

  The library primarily uses named exports for its utility functions. Attempting a default import will likely result in `undefined` or an empty object.
• encrypt
  wrong:

  const { encrypt } = require('isomorphic.js/lib');

  correct:

  import { encrypt, decrypt } from 'isomorphic.js';

  All public APIs are exported directly from the main package entry point. Direct imports from internal `lib` paths are not supported and may break.

Quickstart

Demonstrates environment detection, random byte generation, and basic (though simplified for security) encryption/decryption using the isomorphic API.

import { isBrowser, isNode, randomBytes, encrypt, decrypt } from 'isomorphic.js';

async function runIsomorphicExample() {
  if (isBrowser) {
    console.log('Running in a browser environment.');
  } else if (isNode) {
    console.log('Running in a Node.js environment.');
  } else {
    console.log('Running in an unknown environment.');
  }

  // Generate 16 random bytes
  const randomBuffer = randomBytes(16);
  console.log('Generated random bytes:', randomBuffer.toString('hex'));

  // Example of cryptographic operations (using a dummy key for demonstration)
  const key = await decrypt(Buffer.from('dummy-key-for-test', 'utf-8'), Buffer.from('')); // Key must be derived or generated securely
  const dataToEncrypt = Buffer.from('Hello, Isomorphic World!');
  
  try {
    // Note: `encrypt` and `decrypt` require proper key management and IVs for real-world use.
    // This example is simplified and might not run without a valid crypto key setup.
    const encryptedData = await encrypt(dataToEncrypt, key);
    console.log('Encrypted data (truncated):', encryptedData.toString('hex').substring(0, 30) + '...');

    const decryptedData = await decrypt(encryptedData, key);
    console.log('Decrypted data:', decryptedData.toString());
  } catch (error) {
    console.warn('Could not perform encryption/decryption. Ensure a valid crypto key and IV setup:', error.message);
  }
}

runIsomorphicExample().catch(console.error);