TS Referer Parser

Common errors

• TypeError: parse(...).then is not a function

  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.
  fix Remove the `await` keyword from the `parse()` call. The function now returns the `Referer` object directly. Example: `const result = parse(referer, url);`

• Error: Cannot find module 'ts-referer-parser' or ERR_PACKAGE_PATH_NOT_EXPORTED

  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.
  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.

Warnings

• breaking 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.
  Fix: Remove the `await` keyword from all calls to `parse()`. For example, change `const result = await parse(...)` to `const result = parse(...)`.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  Fix: Update your `package.json` dependency to `ts-referer-parser` and adjust all import paths accordingly to `from 'ts-referer-parser'`.

Install

• npm install ts-referer-parser npm
• yarn add ts-referer-parser yarn
• pnpm add ts-referer-parser pnpm

Imports

• parse
  wrong:

  const parse = require('ts-referer-parser').parse;

  correct:

  import { parse } from 'ts-referer-parser';

  The library supports both ESM and CJS module systems since v1.0.9, but ESM is the recommended approach for modern TypeScript/JavaScript projects.
• Referer
  wrong:

  import { Referer } from 'ts-referer-parser';

  correct:

  import type { Referer } from 'ts-referer-parser';

  `Referer` is a TypeScript interface representing the parsed referer object. It should be imported as a type.
• All exports as namespace
  wrong:

  const RefererParser = require('ts-referer-parser');

  correct:

  import * as RefererParser from 'ts-referer-parser';

  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.

Quickstart

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.

import { parse, Referer } from "ts-referer-parser";

// Determine referer URL based on environment
let refererUrl: string | null = null;
let currentPageUrl: string = 'http://www.example.com/'; // Your current page URL

if (typeof window !== 'undefined' && window.document) {
  // Client-side (browser) environment
  refererUrl = window.document.referrer;
  currentPageUrl = window.location.href;
} else {
  // Server-side environment (e.g., Node.js with Express)
  // In a real application, 'request' would come from your HTTP server context.
  // For this example, we'll simulate it.
  const request = { headers: { referer: 'https://www.google.com/search?q=example' } };
  refererUrl = request.headers.referer || null;
}

// Example 1: Direct traffic
let result: Referer = parse(null, currentPageUrl);
console.log("Direct traffic:", result); // Expected: { medium: 'direct', referer: null, term: null }

// Example 2: Social media referral
result = parse(
  "https://www.facebook.com/somepage",
  currentPageUrl
);
console.log("Social media referral:", result); // Expected: { medium: 'social', referer: 'Facebook', term: null }

// Example 3: Search engine referral with search term
result = parse(
  "http://www.google.com/search?q=typescript+parser&hl=en",
  currentPageUrl
);
console.log("Search engine referral:", result); // Expected: { medium: 'search', referer: 'Google', term: 'typescript parser' }

// Example 4: AI Chatbot referral (new in v1.1.0)
result = parse(
  "https://chatgpt.com/c/12345",
  currentPageUrl
);
console.log("AI Chatbot referral:", result); // Expected: { medium: 'chatbot', referer: 'ChatGPT', term: null }