{"id":15865,"library":"ts-referer-parser","title":"TS Referer Parser","description":"This library provides a typed solution for parsing HTTP referer URLs, classifying them into categories such as search engines, social media, email providers, paid advertising platforms, and notably, AI chatbots. It is currently stable at version 1.1.0, with minor releases occurring periodically to introduce new features, expand database coverage, and address maintenance. A key differentiator is its comprehensive referer database, which is compiled from both Snowplow's referer-parser and Matomo's searchengine-and-social-list, covering over 450 sources. Recent updates significantly expanded its AI/chatbot detection capabilities to include popular models like ChatGPT, Claude, and Google Gemini, alongside broader social media coverage for platforms like X (formerly Twitter) and Bluesky. The library offers full TypeScript support, ensuring type inference, and is designed to work in both client-side (browser) and server-side (Node.js) JavaScript environments.","status":"active","version":"1.1.0","language":"javascript","source_language":"en","source_url":"https://github.com/stevan-borus/ts-referer-parser","tags":["javascript","typescript","referer","referrer","parser"],"install":[{"cmd":"npm install ts-referer-parser","lang":"bash","label":"npm"},{"cmd":"yarn add ts-referer-parser","lang":"bash","label":"yarn"},{"cmd":"pnpm add ts-referer-parser","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"The library supports both ESM and CJS module systems since v1.0.9, but ESM is the recommended approach for modern TypeScript/JavaScript projects.","wrong":"const parse = require('ts-referer-parser').parse;","symbol":"parse","correct":"import { parse } from 'ts-referer-parser';"},{"note":"`Referer` is a TypeScript interface representing the parsed referer object. It should be imported as a type.","wrong":"import { Referer } from 'ts-referer-parser';","symbol":"Referer","correct":"import type { Referer } from 'ts-referer-parser';"},{"note":"This pattern imports all named exports into a single namespace object. It's less common but useful for accessing all utilities via `RefererParser.parse` etc.","wrong":"const RefererParser = require('ts-referer-parser');","symbol":"All exports as namespace","correct":"import * as RefererParser from 'ts-referer-parser';"}],"quickstart":{"code":"import { parse, Referer } from \"ts-referer-parser\";\n\n// Determine referer URL based on environment\nlet refererUrl: string | null = null;\nlet currentPageUrl: string = 'http://www.example.com/'; // Your current page URL\n\nif (typeof window !== 'undefined' && window.document) {\n  // Client-side (browser) environment\n  refererUrl = window.document.referrer;\n  currentPageUrl = window.location.href;\n} else {\n  // Server-side environment (e.g., Node.js with Express)\n  // In a real application, 'request' would come from your HTTP server context.\n  // For this example, we'll simulate it.\n  const request = { headers: { referer: 'https://www.google.com/search?q=example' } };\n  refererUrl = request.headers.referer || null;\n}\n\n// Example 1: Direct traffic\nlet result: Referer = parse(null, currentPageUrl);\nconsole.log(\"Direct traffic:\", result); // Expected: { medium: 'direct', referer: null, term: null }\n\n// Example 2: Social media referral\nresult = parse(\n  \"https://www.facebook.com/somepage\",\n  currentPageUrl\n);\nconsole.log(\"Social media referral:\", result); // Expected: { medium: 'social', referer: 'Facebook', term: null }\n\n// Example 3: Search engine referral with search term\nresult = parse(\n  \"http://www.google.com/search?q=typescript+parser&hl=en\",\n  currentPageUrl\n);\nconsole.log(\"Search engine referral:\", result); // Expected: { medium: 'search', referer: 'Google', term: 'typescript parser' }\n\n// Example 4: AI Chatbot referral (new in v1.1.0)\nresult = parse(\n  \"https://chatgpt.com/c/12345\",\n  currentPageUrl\n);\nconsole.log(\"AI Chatbot referral:\", result); // Expected: { medium: 'chatbot', referer: 'ChatGPT', term: null }","lang":"typescript","description":"This quickstart demonstrates how to parse various types of referer URLs, including direct traffic, social media, search engines, and AI chatbots, showing how to obtain the referer string in both browser and Node.js environments."},"warnings":[{"fix":"Remove the `await` keyword from all calls to `parse()`. For example, change `const result = await parse(...)` to `const result = parse(...)`.","message":"The `parse()` function became synchronous in v1.0.8, directly returning the `Referer` object instead of a Promise. Any `await` calls on `parse()` will now result in a TypeError or unexpected behavior as it no longer returns a Promise.","severity":"breaking","affected_versions":">=1.0.8"},{"fix":"Upgrade to `ts-referer-parser@1.0.9` or later. If issues persist after upgrading, clear `node_modules` and your package manager's cache, then reinstall dependencies.","message":"Prior to v1.0.9, the package's `main` field in `package.json` incorrectly pointed to a non-existent file (`dist/index.js`), potentially causing module resolution errors in some CommonJS environments, particularly older bundlers or Node.js versions.","severity":"gotcha","affected_versions":"<1.0.9"},{"fix":"Update to `ts-referer-parser@1.0.8` or newer to ensure all bundled dependencies and the build process are patched against known vulnerabilities.","message":"Version 1.0.8 included a fix for `Rollup CVE-2026-27606`, addressing a vulnerability in the underlying build tool. While not directly exploitable through `ts-referer-parser` itself, it's a critical dependency update to mitigate potential supply chain risks introduced by the build process.","severity":"gotcha","affected_versions":"<1.0.8"},{"fix":"Update your `package.json` dependency to `ts-referer-parser` and adjust all import paths accordingly to `from 'ts-referer-parser'`.","message":"The package was renamed to `ts-referer-parser` in v1.0.3. If you were using an earlier, differently named version (e.g., `referer-parser-ts`), you must update your `package.json` and import statements.","severity":"gotcha","affected_versions":"<1.0.3"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Remove the `await` keyword from the `parse()` call. The function now returns the `Referer` object directly. Example: `const result = parse(referer, url);`","cause":"Attempting to use `await` with the `parse()` function after v1.0.8, which converted it from an asynchronous Promise-returning function to a synchronous one.","error":"TypeError: parse(...).then is not a function"},{"fix":"Ensure you are using `ts-referer-parser@1.0.9` or a newer version. If the problem persists, delete your `node_modules` directory and `package-lock.json` (or `yarn.lock`, `pnpm-lock.yaml`) and reinstall dependencies.","cause":"Module resolution issues, particularly in CommonJS environments, due to an incorrect `main` field in `package.json` in versions prior to v1.0.9. This meant the primary entry point for CJS was not correctly identified.","error":"Error: Cannot find module 'ts-referer-parser' or ERR_PACKAGE_PATH_NOT_EXPORTED"}],"ecosystem":"npm"}