Jdenticon

Common errors

• TypeError: Cannot read properties of undefined (reading 'update')

  cause After v3.0.0, `jdenticon` no longer automatically initializes or exposes top-level methods for direct access via a script tag without explicit import or assignment to a global.
  fix If using a module system, import named exports like `import { update } from 'jdenticon';`. If using a script tag and relying on auto-rendering, ensure you are importing `jdenticon/standalone` or explicitly call `update()`.

• Module not found: Can't resolve 'jdenticon'

  cause The module resolver (e.g., Webpack, TypeScript) cannot locate the package or is configured incorrectly for your environment (browser vs. Node.js).
  fix Check your `node_modules` for `jdenticon`. If using a bundler with specific environment targets or Node16 module resolution, try `import 'jdenticon/browser'` or `import 'jdenticon/node'`.

• Property 'toPng' does not exist on type 'typeof import("jdenticon")'.

  cause The `toPng` function is specific to the Node.js environment and is not part of the main (browser-oriented) `jdenticon` export.
  fix Explicitly import `toPng` from the Node.js specific bundle: `import { toPng } from 'jdenticon/node';`.

• Error: Jdenticon: Canvas element must be passed when rendering on Node.js.

  cause When using `drawIcon` on Node.js, it typically expects a canvas-compatible object (e.g., from `node-canvas`) as the first argument, unlike in the browser where it can automatically find elements based on `data-jdenticon-value`.
  fix Ensure you are passing a valid canvas context or element from a library like `node-canvas` when calling `drawIcon` in a Node.js environment.

Warnings

• breaking Starting with v3.0.0, the main 'jdenticon' bundle no longer automatically renders icons on page startup. You must explicitly call `update()` or `drawIcon()` from your code to render icons.
  Fix: Call `jdenticon.update()` after DOM content is loaded, or `import 'jdenticon/standalone'` instead of `jdenticon` if you prefer the old automatic rendering behavior.
• breaking In v3.0.0, the default `padding` for the `drawIcon` method was changed from `0` to `0.08` to improve visual consistency.
  Fix: If you relied on zero padding for `drawIcon`, explicitly pass `{ padding: 0 }` as part of the config object to the `drawIcon` method.
• deprecated Directly setting `jdenticon_config.saturation` is deprecated since v2.1.0. Use `jdenticon_config.saturation.color` or `jdenticon_config.saturation.grayscale` instead.
  Fix: Update your configuration to use the nested `saturation.color` and `saturation.grayscale` properties for finer control over saturation settings.
• gotcha When using bundlers or TypeScript with Node16 module resolution, you might need to explicitly import specific bundles (`jdenticon/browser` or `jdenticon/node`) to ensure the correct environment-specific code is used.
  Fix: For browser-specific code: `import { update } from 'jdenticon/browser';`. For Node.js-specific code: `import { toPng } from 'jdenticon/node';`.
• gotcha Older TypeScript configurations (pre-v3.0.1) might have required adding `"dom"` to `lib` in `tsconfig.json` or experienced Node typings leaking into browser contexts. These issues were largely addressed in v3.0.1.
  Fix: Ensure you are on Jdenticon v3.0.1 or later. If issues persist, review your `tsconfig.json` `lib` array and `typeRoots`.

Install

• npm install jdenticon npm
• yarn add jdenticon yarn
• pnpm add jdenticon pnpm

Imports

• update
  wrong:

  const jdenticon = require('jdenticon'); jdenticon.update();

  correct:

  import { update } from 'jdenticon';

  For ESM modules, named imports are standard. CommonJS `require` works but may pull an incorrect bundle in certain bundler/Node.js configurations without explicit subpath imports (e.g., `jdenticon/node`).
• drawIcon
  wrong:

  import jdenticon from 'jdenticon'; jdenticon.drawIcon(...);

  correct:

  import { drawIcon } from 'jdenticon';

  Jdenticon uses named exports for its primary API functions. Attempting a default import will result in `undefined` for `drawIcon`.
• toPng
  wrong:

  import { toPng } from 'jdenticon';

  correct:

  import { toPng } from 'jdenticon/node';

  The `toPng` function, used for server-side PNG generation, is specifically exported from the Node.js bundle to ensure correct dependencies and environment assumptions.
• Standalone auto-rendering

  import 'jdenticon/standalone';

  Since v3.0.0, automatic icon rendering on page load is disabled by default for the main 'jdenticon' import. To restore the pre-v3 auto-rendering behavior, explicitly import the 'standalone' bundle.

Quickstart

Demonstrates how to import and use Jdenticon to render icons on page load and dynamically create/update icons, accounting for v3.0.0 breaking changes.

import { update } from 'jdenticon';

document.addEventListener('DOMContentLoaded', () => {
  // Assume HTML elements with data-jdenticon-value are present
  // e.g., <svg width="80" height="80" data-jdenticon-value="my-icon-seed"></svg>
  // or <canvas width="80" height="80" data-jdenticon-value="my-icon-seed"></canvas>

  // To render all icons on the page with data-jdenticon-value attribute:
  update();

  // To dynamically create and render an icon on a specific element:
  const svgElement = document.createElement('svg');
  svgElement.setAttribute('width', '100');
  svgElement.setAttribute('height', '100');
  // The `update` function can take an element and a value
  update(svgElement, 'dynamic-icon-seed');
  document.body.appendChild(svgElement);

  // Example of using a specific value for an existing element:
  const existingCanvas = document.querySelector('canvas[data-jdenticon-value="icon value"]');
  if (existingCanvas) {
    update(existingCanvas, 'new-seed-for-canvas');
  }
});