Introducing a new way to review your PRs.

Read the announcement

fingerprintjs / fingerprintjs

The most advanced free and open-source browser fingerprinting library

View on GitHub

13 documents · Updated Nov 16, 2026

overview

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/**, and resources/**.

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

5. Routing table