Registry / http-networking / ts-referer-parser

ts-referer-parser

library1.1.0jsnpmunverified

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.

http-networking serialization

npm install ts-referer-parser

github ↗package ↗

INSTALL

IMPORT

SIG · TS-REFERER-PARSER

ts-referer-parser

http-networkingjavascriptv1.1.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

parse

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

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

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

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

✗ import { 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

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

✗ const RefererParser = require('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.

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 }

Debug

Known issues

breakingThe `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(...)`.

affects: >=1.0.8

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

affects: <1.0.9

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

affects: <1.0.8

gotchaThe 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'`.

affects: <1.0.3

Errors

Common errors & fixes

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

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

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.

Upgrade

Version history

1.1.0latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

12 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/stevan-borus/ts-referer-parser ↗

packagehttps://www.npmjs.com/package/ts-referer-parser ↗