{"id":11113,"library":"isomorphic.js","title":"Isomorphic.js Utilities","description":"Isomorphic.js is a utility library providing a consistent API for platform-specific JavaScript features, with a strong focus on cryptographic operations like `randomBytes`, `encrypt`, and `decrypt`. It also offers environment detection utilities such as `isBrowser` and `isNode`. Currently at version `0.2.5`, the package receives infrequent, maintenance-oriented updates, primarily for dependency bumps. Its key differentiator is abstracting away the complexities of disparate browser and Node.js environments, offering polyfills where native APIs are unavailable, thereby enabling truly isomorphic code execution without explicit runtime checks for common tasks, particularly in security-sensitive areas. It relies on `yjs` for some environment detection logic, simplifying cross-platform development.","status":"maintenance","version":"0.2.5","language":"javascript","source_language":"en","source_url":"https://github.com/dmonad/isomorphic.js","tags":["javascript"],"install":[{"cmd":"npm install isomorphic.js","lang":"bash","label":"npm"},{"cmd":"yarn add isomorphic.js","lang":"bash","label":"yarn"},{"cmd":"pnpm add isomorphic.js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Provides core environment detection utilities like `isBrowser` and `isNode`, which are re-exported by `isomorphic.js`.","package":"yjs","optional":false}],"imports":[{"note":"ESM named import is preferred. CommonJS `require` still works but ESM is best practice for modern projects, especially with Node.js support for `exports`.","wrong":"const randomBytes = require('isomorphic.js').randomBytes;","symbol":"randomBytes","correct":"import { randomBytes } from 'isomorphic.js';"},{"note":"The library primarily uses named exports for its utility functions. Attempting a default import will likely result in `undefined` or an empty object.","wrong":"import isomorphic from 'isomorphic.js'; const isBrowser = isomorphic.isBrowser;","symbol":"isBrowser","correct":"import { isBrowser, isNode } from 'isomorphic.js';"},{"note":"All public APIs are exported directly from the main package entry point. Direct imports from internal `lib` paths are not supported and may break.","wrong":"const { encrypt } = require('isomorphic.js/lib');","symbol":"encrypt","correct":"import { encrypt, decrypt } from 'isomorphic.js';"}],"quickstart":{"code":"import { isBrowser, isNode, randomBytes, encrypt, decrypt } from 'isomorphic.js';\n\nasync function runIsomorphicExample() {\n  if (isBrowser) {\n    console.log('Running in a browser environment.');\n  } else if (isNode) {\n    console.log('Running in a Node.js environment.');\n  } else {\n    console.log('Running in an unknown environment.');\n  }\n\n  // Generate 16 random bytes\n  const randomBuffer = randomBytes(16);\n  console.log('Generated random bytes:', randomBuffer.toString('hex'));\n\n  // Example of cryptographic operations (using a dummy key for demonstration)\n  const key = await decrypt(Buffer.from('dummy-key-for-test', 'utf-8'), Buffer.from('')); // Key must be derived or generated securely\n  const dataToEncrypt = Buffer.from('Hello, Isomorphic World!');\n  \n  try {\n    // Note: `encrypt` and `decrypt` require proper key management and IVs for real-world use.\n    // This example is simplified and might not run without a valid crypto key setup.\n    const encryptedData = await encrypt(dataToEncrypt, key);\n    console.log('Encrypted data (truncated):', encryptedData.toString('hex').substring(0, 30) + '...');\n\n    const decryptedData = await decrypt(encryptedData, key);\n    console.log('Decrypted data:', decryptedData.toString());\n  } catch (error) {\n    console.warn('Could not perform encryption/decryption. Ensure a valid crypto key and IV setup:', error.message);\n  }\n}\n\nrunIsomorphicExample().catch(console.error);","lang":"typescript","description":"Demonstrates environment detection, random byte generation, and basic (though simplified for security) encryption/decryption using the isomorphic API."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":">=0.2.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=0.2.3"},{"fix":"Ensure `yjs` is listed in your project's `dependencies` and properly installed via `npm install yjs` or `yarn add yjs`.","message":"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`.","severity":"gotcha","affected_versions":">=0.1.0"},{"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.","message":"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.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"The internal `yjs` dependency, which provides environment detection functions like `isBrowser` and `isNode`, failed to load or initialize correctly.","error":"TypeError: Cannot read properties of undefined (reading 'isBrowser') or TypeError: Cannot read properties of null (reading 'isBrowser')"},{"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).","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.","error":"Error: require() of ES Module CJS_MODULE from CommonJS module JS_FILE not supported. Did you mean to import CJS_MODULE?"},{"fix":"Use a named ESM import: `import { randomBytes } from 'isomorphic.js';` or for CommonJS: `const { randomBytes } = require('isomorphic.js');`.","cause":"Incorrectly importing the `randomBytes` function, possibly through a default import or a CommonJS `require` that doesn't destructure correctly.","error":"TypeError: isomorphic.randomBytes is not a function"}],"ecosystem":"npm"}