Registry / auth-security / isomorphic.js

isomorphic.js

library0.2.5jsnpmunverified

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.

auth-security serialization

npm install isomorphic.js

github ↗package ↗

INSTALL

IMPORT

SIG · ISOMORPHIC.JS

isomorphic.js

auth-securityjavascriptv0.2.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

randomBytes

✓ import { randomBytes } from 'isomorphic.js';

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

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

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

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

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

encrypt

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

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

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

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);

Debug

Known issues

breakingVersion 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.

affects: >=0.2.0

breakingVersion 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.

affects: >=0.2.3

gotchaThe 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`.

affects: >=0.1.0

gotchaThe `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.

affects: >=0.1.0

Errors

Common errors & fixes

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

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?

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

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');`.

Upgrade

Version history

0.2.5latest on npm

Audit

Dependencies

yjsrequiredProvides core environment detection utilities like `isBrowser` and `isNode`, which are re-exported by `isomorphic.js`.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/dmonad/isomorphic.js ↗

packagehttps://www.npmjs.com/package/isomorphic.js ↗