{"id":22197867,"url":"https://github.com/onmax/nimiq-identicons","last_synced_at":"2026-02-19T11:03:35.069Z","repository":{"id":259857057,"uuid":"878003941","full_name":"onmax/nimiq-identicons","owner":"onmax","description":"The modern implementation for Nimiq Identicons","archived":false,"fork":false,"pushed_at":"2024-11-22T18:25:13.000Z","size":1005,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-11-30T14:41:51.884Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://onmax.github.io/nimiq-identicons/","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onmax.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-10-24T15:54:48.000Z","updated_at":"2024-11-30T02:08:27.000Z","dependencies_parsed_at":"2024-10-29T17:53:55.290Z","dependency_job_id":null,"html_url":"https://github.com/onmax/nimiq-identicons","commit_stats":null,"previous_names":["onmax/identicons","onmax/nimiq-identicons"],"tags_count":0,"template":false,"template_full_name":"antfu/starter-ts","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnimiq-identicons","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnimiq-identicons/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnimiq-identicons/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onmax%2Fnimiq-identicons/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onmax","download_url":"https://codeload.github.com/onmax/nimiq-identicons/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":227359617,"owners_count":17769571,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-12-02T14:24:27.922Z","updated_at":"2025-10-07T16:13:28.306Z","avatar_url":"https://github.com/onmax.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Identicons\n\nA rewrite of the Identicon module with ESM support.\n\n[Docs preview](https://deploy-preview-78--developer-center.netlify.app/build/ui/identicons#nimiq-identicons)\n\n- Fully typed\n- Runtime agnostic: works in browser, workerd, node, bun...\n- About 2 times faster on startup and 5 times faster on re-rendering than previous version\n- Produces about 25% smaller SVG, thanks to svgo\n- Simplify bundling compare to previous version\n- No more promises!\n\n## Installation\n\n```bash\nnpm install identicons-esm\n```\n\n```ts\nimport { createIdenticon } from 'identicons-esm'\n\nconst input = 'Your input here'\nconst svg = createIdenticon(input, { shouldValidateAddress: false }) // shouldValidateAddress is `true` by default\n```\n\n## Identicons as `\u003cimg\u003e`\n\n```ts\nimport { createIdenticon } from 'identicons-esm'\n\nconst input = 'Your input here'\nconst imgSrc = await createIdenticon(input, { shouldValidateAddress: false, format: 'image/svg+xml' })\n```\n\n```html\n\u003cimg src=\"imgSrc\" alt=\"Identicon\" /\u003e\n```\n\n## Identicons as Web Component\n\n```html\n\u003cnimiq-identicon input=\"Your input here\" should-validate-address=\"false\"\u003e\u003c/nimiq-identicon\u003e\n\u003cnimiq-shiny-identicon input=\"Your input here\" should-validate-address=\"false\" material=\"gold\"\u003e\u003c/nimiq-shiny-identicon\u003e\n```\n\nMake sure to import the web components in your project before using them.\n\n### Web Components in Vue 3\n\n```vue\n\u003cscript setup lang=\"ts\"\u003e\nimport type { IdenticonMaterial } from 'identicons-esm/types'\nimport 'identicons-esm/web-components'\nimport 'identicons-esm/shiny-web-components'\n\nconst input = 'Your input here'\nconst shouldValidateAddress = false\nconst material: IdenticonMaterial = 'gold'\n\u003c/script\u003e\n\n\u003ctemplate\u003e\n  \u003cnimiq-identicon :input=\"input\" :should-validate-address=\"shouldValidateAddress\" /\u003e\n  \u003cnimiq-shiny-identicon :input=\"input\" :should-validate-address=\"shouldValidateAddress\" :material=\"material\" /\u003e\n\u003c/template\u003e\n```\n\n#### Vite warning\n\nTo avoid a warning in development mode, you have to let Vite know that the web component exists:\n\n```ts\n// vite.config.ts\nimport vue from '@vitejs/plugin-vue'\nimport { defineConfig } from 'vite'\n\nexport default defineConfig({\n  plugins: [vue({\n    template: {\n      compilerOptions: {\n        isCustomElement: tag =\u003e ['nimiq-identicon', 'nimiq-shiny-identicon'].includes(tag),\n      }\n    }\n  })],\n})\n```\n\n\u003e [!WARNING]\n\u003e This is a PoC and the API might change\n\n### Getting just a specific color or section of the identicon\n\n```ts\nimport { getIdenticonsParams } from 'identicons-esm/core'\n\nconst input = 'Your input here'\nconst { colors, sections } = getIdenticonsParams(input)\n\n// colors.background -\u003e '#0ab123'\n// colors.main -\u003e '#0ab123'\n// colors.accent -\u003e '#0ab123'\n// sections.top -\u003e Path to the SVG\n// sections.bottom -\u003e Path to the SVG\n// sections.sides -\u003e Path to the SVG\n// sections.face -\u003e Path to the SVG\n```\n\n## Why not just use the V1 version?\n\nWe were having issues running the lib in workerd. That's it. But then, when I started looking into it, I discovered that we are there was space for improvements.\n\n### Bundling\n\nWhile `gulp` is great and allows you to build the library, `vite` is the standard these days. With the old implementation, the library loaded all the features of svg into a single DOM element (using `dom-parser`) and from there, depending on the hash, it selected the features for the fiven hash. Then it ensabmages all the selected elements together with a predefined background and colors and runs an optimization process on each render.\n\nWith the new approach, we run `svgo` with some defined plugins in dev and write the optimized svg to the folder. Then at runtime we just assemble the selected optimized features and return the SVG. After the selected features have been retrieved, we just ensamlbe the SVG and return it. **We don't use `dom-parser` and we don't need to optimize the SVG at runtime**.\n\n### Performance Comparison\n\n| Metric                 | V1 Implementation | Current Implementation |\n| ---------------------- | ----------------- | ---------------------- |\n| First Time Load        | ~20ms             | ~10ms                  |\n| Already Loaded         | ~6ms              | ~1ms                   |\n| Average Size Reduction | -                 | 25% smaller            |\n\n## Migrate\n\nCurrently part of the implementation has been ported\n\n### Generate SVG string\n\n#### Before\n\n```js\n// @ts-ignore Types no implemented\nimport Identicons from '@nimiq/identicons/dist/identicons.min.js'\nIdenticonsV1.svgPath = '@nimiq/identicons/dist/identicons.min.svg'\n\nconst input = 'Your input here'\nconst svg = await Identicons.svg(input)\n//    ^ type any 😩\n```\n\n#### Now\n\n```ts\nimport { createIdenticon } from 'identicons-esm'\n\nconst input = 'Your input here'\nconst svg = createIdenticon(input)\n//    ^ type string\n```\n\n### Generate Data URI\n\n#### Before\n\n```js\n// @ts-ignore Types no implemented\nimport Identicons from '@nimiq/identicons/dist/identicons.min.js'\nIdenticonsV1.svgPath = '@nimiq/identicons/dist/identicons.min.svg'\n\nconst input = 'Your input here'\nconst svg = await Identicons.toDataUri(input)\n//    ^ type any 😩\n```\n\n#### Now\n\n```ts\nimport { createIdenticon } from 'identicons-esm'\n\nconst input = 'Your input here'\nconst svg = createIdenticon(input, { format: 'image/svg+xml' })\n//    ^ type string\n```\n\n### Discontiuned functions\n\nThere are functions in the original library that are not included in this implementation due to lack of use. These functions are:\n\n- `makeLetterHash`\n- `wordsByEntropy`\n- `Identicons.render`\n- `Identicons.image`\n- `Identicons.placeholder`\n\n## Development\n\n```bash\ngit clone https://github.com/onmax/nimiq-identicons\npnpm install\npnpm dev\npnpm optimize-svg # Run just if you modify the content of the features\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonmax%2Fnimiq-identicons","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonmax%2Fnimiq-identicons","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonmax%2Fnimiq-identicons/lists"}