Knowledge Base updated: 2026-11-16
Knowledge Base Index
1. Orientation
This repository is the open-source FingerprintJS browser fingerprinting library. Its highest-level flow is: public API entrypoints create an agent, the agent collects entropy components from browser APIs, serializes them, hashes them into a visitor ID, and returns confidence metadata.
Main parts:
- src/index.ts and src/agent.ts expose the public API and orchestrate fingerprint collection.
src/sources/**contains entropy sources grouped around browser, device, rendering, storage, DOM, and media capabilities.src/utils/**provides shared browser, DOM, async, hashing, data, and entropy-source helpers.tests/**, karma.conf.ts, and per-source *.test.ts files define the browser test harness and source-level coverage.- Build, release, documentation, playground, and asset files live in root config files,
docs/**,playground/**, andresources/**.
Critical state:
- There is no server-side database, queue, cache, or object store in this repo.
- Runtime state is gathered transiently from browser APIs and DOM probes, then returned to callers as fingerprint components/results.
- Build and package state is represented by root config files such as package.json, rollup.config.ts, terser.config.ts, TypeScript configs, and yarn.lock.
2. Architecture diagrams
flowchart TD
Consumer[Library consumer] --> PublicAPI[src/index.ts exports]
PublicAPI --> Agent[src/agent.ts]
subgraph Core[src]
Agent --> Registry[src/sources/index.ts]
Agent --> Hashing[src/utils/hashing.ts]
Agent --> Confidence[src/confidence.ts]
Registry --> Sources[src/sources/**]
Sources --> Utils[src/utils/**]
end
subgraph Browser[Browser environment]
APIs[Navigator, Screen, Storage, DOM, Canvas, WebGL, Audio]
end
Sources --> APIs
Hashing --> Result[visitorId and components]
Confidence --> Result
Result --> Consumer
subgraph RepoSupport[Repository support]
Tests[tests/** and *.test.ts]
Build[package.json / Rollup / Terser / TS / CI]
Docs[docs/**, readme.md, playground/**, resources/**]
end
Tests --> Core
Build --> Core
Docs --> PublicAPI
sequenceDiagram
participant App as Consumer app
participant API as src/index.ts
participant Agent as src/agent.ts
participant Sources as src/sources/index.ts
participant Browser as Browser APIs
participant Hash as Hashing and confidence
App->>API: load(options)
API->>Agent: create/load agent
App->>Agent: get(options)
Agent->>Sources: collect components
Sources->>Browser: run entropy probes
Browser-->>Sources: values/errors/unsupported states
Sources-->>Agent: component map
Agent->>Hash: serialize, hash, score confidence
Hash-->>Agent: visitorId and confidence
Agent-->>App: fingerprint result
flowchart LR
subgraph EntropySources[src/sources/**]
Rendering[Canvas/WebGL/Audio/Math]
DOM[Fonts/Plugins/DOM blockers]
Display[Screen/Color/Media prefs]
Navigator[Navigator and client env]
Storage[Storage/Cookies/DB features]
end
Rendering --> Registry[Entropy source registry]
DOM --> Registry
Display --> Registry
Navigator --> Registry
Storage --> Registry
Registry --> Agent[Agent collection flow]
Agent --> Components[Normalized components]
Components --> Hash[Stable hash input]
3. Glossary
- FingerprintJS: the browser fingerprinting library implemented by this repository.
- Entropy source: a module under
src/sources/**that probes one browser/device characteristic and contributes one fingerprint component. - Visitor ID: the stable identifier computed from collected components by the hashing path.
- Confidence: metadata estimating reliability of the computed fingerprint, implemented around src/confidence.ts.
- Playground: the demo app under
playground/**that exercises the packaged browser library.
4. Codebase-wide invariants
- Entropy source implementations live under
src/sources/, and most source files have colocated tests named src/…/*.test.ts; examples include src/…/canvas.ts with src/…/canvas.test.ts and src/…/timezone.ts with src/…/timezone.test.ts. - Shared utility modules live under
src/utils/, with colocated tests for major helpers such as src/…/browser.test.ts, src/…/dom.test.ts, src/…/hashing.test.ts, and src/…/entropy_source.test.ts. - The package is TypeScript-first: source, tests, build config, and playground entrypoints use .ts files, evidenced by src/index.ts, karma.conf.ts, rollup.config.ts, playground/index.ts, and tsconfig.json.
- Public/user-facing documentation is kept separately from implementation docs under readme.md and
docs/**, while demo and asset support live underplayground/**andresources/**.
5. Routing table
-
any change to public API exports, agent loading,
get()behavior, result shape, or public types -> docs/public-agent-api.md -
src/…/entropy_source.test.ts -> docs/entropy-sources-registry.md
-
any change to how entropy sources are registered, loaded, typed, or collected -> docs/entropy-sources-registry.md
-
src/confidence.test.ts -> docs/fingerprint-hashing-confidence.md
-
src/…/hashing.test.ts -> docs/fingerprint-hashing-confidence.md
-
src/…/data.test.ts -> docs/fingerprint-hashing-confidence.md
-
any change to visitor ID hashing, component serialization, confidence scoring, or data normalization helpers -> docs/fingerprint-hashing-confidence.md
-
src/…/canvas.test.ts -> docs/rendering-media-entropy-sources.md
-
src/…/webgl.test.ts -> docs/rendering-media-entropy-sources.md
-
src/…/audio.test.ts -> docs/rendering-media-entropy-sources.md
-
src/…/audio_base_latency.ts -> docs/rendering-media-entropy-sources.md
-
src/…/audio_base_latency.test.ts -> docs/rendering-media-entropy-sources.md
-
src/…/math.test.ts -> docs/rendering-media-entropy-sources.md
-
any change to canvas, WebGL, audio, audio latency, or math entropy behavior -> docs/rendering-media-entropy-sources.md
-
src/…/font_preferences.ts -> docs/dom-font-and-blocker-sources.md
-
src/…/font_preferences.test.ts -> docs/dom-font-and-blocker-sources.md
-
src/…/dom_blockers.ts -> docs/dom-font-and-blocker-sources.md
-
src/…/dom_blockers.test.ts -> docs/dom-font-and-blocker-sources.md
-
any change to DOM measurement, font detection, plugin detection, or content blocker detection -> docs/dom-font-and-blocker-sources.md
-
src/…/screen_resolution.ts -> docs/display-and-media-preference-sources.md
-
src/…/screen_resolution.test.ts -> docs/display-and-media-preference-sources.md
-
src/…/screen_frame.ts -> docs/display-and-media-preference-sources.md
-
src/…/screen_frame.test.ts -> docs/display-and-media-preference-sources.md
-
src/…/color_depth.ts -> docs/display-and-media-preference-sources.md
-
src/…/color_depth.test.ts -> docs/display-and-media-preference-sources.md
-
src/…/color_gamut.ts -> docs/display-and-media-preference-sources.md
-
src/…/color_gamut.test.ts -> docs/display-and-media-preference-sources.md
-
src/…/hdr.ts -> docs/display-and-media-preference-sources.md
-
src/…/hdr.test.ts -> docs/display-and-media-preference-sources.md
-
src/…/monochrome.ts -> docs/display-and-media-preference-sources.md
-
src/…/monochrome.test.ts -> docs/display-and-media-preference-sources.md
-
src/…/contrast.ts -> docs/display-and-media-preference-sources.md
-
src/…/contrast.test.ts -> docs/display-and-media-preference-sources.md
-
src/…/inverted_colors.ts -> docs/display-and-media-preference-sources.md
-
src/…/inverted_colors.test.ts -> docs/display-and-media-preference-sources.md
-
src/…/forced_colors.ts -> docs/display-and-media-preference-sources.md
-
src/…/forced_colors.test.ts -> docs/display-and-media-preference-sources.md
-
src/…/reduced_motion.ts -> docs/display-and-media-preference-sources.md
-
src/…/reduced_motion.test.ts -> docs/display-and-media-preference-sources.md
-
src/…/reduced_transparency.ts -> docs/display-and-media-preference-sources.md
-
src/…/reduced_transparency.test.ts -> docs/display-and-media-preference-sources.md
-
any change to screen, color, HDR, contrast, forced colors, reduced motion, reduced transparency, or related media-query entropy -> docs/display-and-media-preference-sources.md
-
src/…/user_agent_data.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/user_agent_data.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/vendor.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/vendor.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/vendor_flavors.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/vendor_flavors.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/platform.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/platform.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/os_cpu.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/os_cpu.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/cpu_class.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/cpu_class.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/architecture.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/architecture.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/hardware_concurrency.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/hardware_concurrency.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/device_memory.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/device_memory.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/languages.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/languages.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/date_time_locale.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/date_time_locale.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/timezone.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/timezone.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/touch_support.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/touch_support.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/pdf_viewer_enabled.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/pdf_viewer_enabled.test.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/apple_pay.ts -> docs/navigator-and-client-environment-sources.md
-
src/…/apple_pay.test.ts -> docs/navigator-and-client-environment-sources.md
-
any change to navigator properties, client hints, platform/vendor identity, CPU/device characteristics, locale/timezone, touch support, PDF viewer, or Apple Pay detection -> docs/navigator-and-client-environment-sources.md
-
src/…/session_storage.ts -> docs/storage-and-browser-feature-sources.md
-
src/…/session_storage.test.ts -> docs/storage-and-browser-feature-sources.md
-
src/…/local_storage.ts -> docs/storage-and-browser-feature-sources.md
-
src/…/local_storage.test.ts -> docs/storage-and-browser-feature-sources.md
-
src/…/indexed_db.ts -> docs/storage-and-browser-feature-sources.md
-
src/…/indexed_db.test.ts -> docs/storage-and-browser-feature-sources.md
-
src/…/open_database.ts -> docs/storage-and-browser-feature-sources.md
-
src/…/open_database.test.ts -> docs/storage-and-browser-feature-sources.md
-
src/…/cookies_enabled.ts -> docs/storage-and-browser-feature-sources.md
-
src/…/cookies_enabled.test.ts -> docs/storage-and-browser-feature-sources.md
-
src/…/private_click_measurement.ts -> docs/storage-and-browser-feature-sources.md
-
src/…/private_click_measurement.test.ts -> docs/storage-and-browser-feature-sources.md
-
any change to storage availability, cookies, IndexedDB, Web SQL/openDatabase, or private click measurement feature detection -> docs/storage-and-browser-feature-sources.md
-
tests/…/mock_match_media.ts -> docs/shared-browser-utilities.md
-
tests/…/mock_properties.ts -> docs/shared-browser-utilities.md
-
any change to shared async, browser detection, DOM helper, miscellaneous helper, or reusable test mock behavior -> docs/shared-browser-utilities.md
-
tests/integration.test.ts -> docs/test-and-browser-harness.md
-
any change to browser test runner setup, integration test flow, or test lint TypeScript configuration -> docs/test-and-browser-harness.md
-
tsconfig.rollupConfig.json -> docs/build-package-and-ci-tooling.md
-
.prettierrc-> docs/build-package-and-ci-tooling.md -
.editorconfig-> docs/build-package-and-ci-tooling.md -
.npmignore-> docs/build-package-and-ci-tooling.md -
.husky/**-> docs/build-package-and-ci-tooling.md -
.github/workflows/**-> docs/build-package-and-ci-tooling.md -
any change to package metadata, build output, bundling, minification, typecheck, lint, formatting, hooks, dependency lockfile, or CI workflows -> docs/build-package-and-ci-tooling.md
-
readme.md -> docs/project-documentation-playground-and-assets.md
-
docs/**-> docs/project-documentation-playground-and-assets.md -
playground/**-> docs/project-documentation-playground-and-assets.md -
resources/**-> docs/project-documentation-playground-and-assets.md -
contributing.md -> docs/project-documentation-playground-and-assets.md
-
code_of_conduct.md -> docs/project-documentation-playground-and-assets.md
-
LICENSE-> docs/project-documentation-playground-and-assets.md -
any change to user-facing docs, migration/version/publishing guidance, playground demo behavior, content-blocking resources, static assets, contribution docs, or licensing docs -> docs/project-documentation-playground-and-assets.md