JavaScript Library Detector

Common errors

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

  cause The `detect` function was called without a valid `window` object in its execution context, likely in a Node.js environment without JSDOM or similar setup.
  fix Ensure you are either running the detection in a browser environment, or providing a simulated browser `window` object when using it in Node.js, e.g., `detect.call(dom.window, options);`.

• ReferenceError: document is not defined

  cause Similar to the `window` error, this occurs when the detection logic attempts to access `document` (which resides on `window`) in an environment where it's not present.
  fix Set up a JSDOM instance in your Node.js environment and pass its `window` object to the `detect` function's `this` context, or execute the code within a browser or headless browser context.

• Detected libraries are inconsistent or incomplete compared to actual page content.

  cause This often happens when running detection on dynamically loaded content or pages that execute complex JavaScript after initial DOM load. The detector might run before all scripts have initialized the libraries.
  fix When using JSDOM or Puppeteer, ensure you wait sufficiently for the page's scripts to execute and for all dynamic content to render before invoking the `detect` function. In JSDOM, use `dom.window.addEventListener('load', ...)` or a `setTimeout` with a reasonable delay after `runScripts: 'dangerously'` is enabled. In Puppeteer, use `page.goto(url, { waitUntil: 'networkidle0' })` or `page.waitForSelector()`.

Warnings

• breaking Detection for 'Create React App' was removed due to conflicts and breaking certain login flows in v6.0.0. If your application relies on detecting CRA, this functionality is no longer available.
  Fix: Update your detection logic to not expect 'Create React App' to be reported. Consider alternative, more robust methods if this specific detection is critical for your use case.
• gotcha The `detect` function must be called with a browser-like `window` object as its `this` context for accurate results. Running it directly in a Node.js environment without a simulated DOM (like JSDOM) or headless browser (like Puppeteer) will yield incorrect or no detections.
  Fix: When using `js-library-detector` in Node.js, ensure you're passing a `window` object from a JSDOM instance or a Puppeteer page context to the `detect` function, typically by using `detect.call(window, options)`.

Install

• npm install js-library-detector npm
• yarn add js-library-detector yarn
• pnpm add js-library-detector pnpm

Imports

• detect
  wrong:

  import detector from 'js-library-detector';

  correct:

  import { detect } from 'js-library-detector';

  The 'detect' function is a named export. The package's `main` entry uses CommonJS `module.exports = { detect: ... }`.
• detect (CommonJS)
  wrong:

  const detector = require('js-library-detector');
  detector();

  correct:

  const { detect } = require('js-library-detector');

  When using CommonJS, it's common to destructure the `detect` function directly from the exported object.
• libraries (CommonJS)

  const { libraries } = require('js-library-detector');

  The package also exports a 'libraries' object containing metadata about all detectable libraries.

Quickstart

This quickstart demonstrates how to use js-library-detector in a Node.js environment by simulating a browser window with JSDOM, loading HTML content, and then executing the detection logic to identify JavaScript libraries present on the page.

import { JSDOM } from 'jsdom';
import { detect } from 'js-library-detector';

async function detectLibrariesOnPage(url) {
  try {
    const response = await fetch(url);
    const html = await response.text();

    const dom = new JSDOM(html, {
      url: url,
      resources: 'usable',
      runScripts: 'dangerously',
      beforeParse(window) {
        // Mock common browser APIs if necessary for detections that rely on them
        window.Element.prototype.getBoundingClientRect = () => ({
          width: 10, height: 10, top: 0, left: 0, bottom: 0, right: 0,
        });
      }
    });

    // Wait for the DOM and scripts to load/execute
    // This is crucial as many libraries are initialized after page load
    await new Promise(resolve => {
      dom.window.addEventListener('load', resolve);
      // Fallback in case 'load' doesn't fire for some reason (e.g., no scripts)
      setTimeout(resolve, 5000); // Wait up to 5 seconds for scripts
    });

    // Perform detection using the JSDOM window object
    // The detect function expects a window object as 'this' context
    const detected = detect.call(dom.window, { html: dom.window.document.documentElement.outerHTML });

    const detectedNames = Object.keys(detected).filter(lib => detected[lib].found);
    console.log(`Detected libraries on ${url}:`);
    if (detectedNames.length > 0) {
      detectedNames.forEach(name => {
        console.log(`- ${name} (version: ${detected[name].version || 'N/A'})`);
      });
    } else {
      console.log('No known libraries detected.');
    }
  } catch (error) {
    console.error(`Error detecting libraries on ${url}:`, error);
  }
}

// Example usage: detect libraries on a public website (e.g., Google)
// Note: This requires 'jsdom' and 'node-fetch' to be installed.
// `npm install jsdom node-fetch`
detectLibrariesOnPage('https://www.google.com/');