TS Referer Parser

A TypeScript-based referer parser library inspired by nodejs-referer-parser. This library can be used in any JavaScript or TypeScript project, including various frameworks like React, Vue, Angular, or Node.js applications.

The referer database is compiled from snowplow-referer-parser and Matomo's searchengine-and-social-list, covering 450+ sources including AI chatbots, search engines, social networks, email providers, and paid advertising platforms.

Installation

To install the package:

pnpm add ts-referer-parser

If you're using npm or yarn, you can use their respective commands:

npm install ts-referer-parser
# or
yarn add ts-referer-parser

Usage

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

let result = parse('', 'http://www.example.com/');

console.log('Direct traffic:', result);
// Output: Direct traffic: { medium: 'direct', referer: null, term: null }

result = parse('https://www.facebook.com/', 'http://www.example.com/');

console.log('Social media referral:', result);
// Output: Social media referral: { medium: 'social', referer: 'Facebook', term: null }

result = parse(
  'http://www.google.com/search?q=gateway+oracle+cards+denise+linn&hl=en&client=safari',
  'http://www.example.com/',
);

console.log('Search engine referral:', result);
// Output: Search engine referral: { medium: 'search', referer: 'Google', term: 'gateway oracle cards denise linn' }

Extracting Referer

To use this library effectively, you need to extract the referer URL. The method for doing this differs between client-side and server-side environments:

let referer = '';

if (typeof window !== 'undefined') {
  // Client-side (browser) environment
  referer = document.referrer;
} else {
  // Server-side environment
  // Note: The exact method to get the referer may vary depending on your server setup
  referer = request.headers.referer; // Example for Express.js
}

// Now you can use the referer with the parse function
const result = parse(referer, currentPageUrl);

Note: In a server-side environment, the method to access the referer may vary depending on your server setup and framework. The example above assumes an Express.js-like setup.

API

parse(refererUrl: string | null, pageUrl?: string, internalDomains: string[] = []): Referer

Parses the given referer URL and returns a Referer object containing:

• medium: The type of referer (e.g., 'search', 'social', 'chatbot', 'email', 'paid', 'unknown', 'internal', 'direct', 'invalid')
• referer: The name of the referer (e.g., 'Google', 'Facebook', 'ChatGPT')
• term: The search term used, if applicable (null otherwise)

Matching rules

Matching starts with the full hostname, then checks each parent domain at a DNS label boundary. For example, mobile.x.com matches x.com; netflix.com does not. Hostnames are case-insensitive, and a trailing DNS root dot is ignored for source matching.

At each hostname, matching path rules take priority over a hostname-only rule. Paths are case-sensitive and match whole segments: /products matches /products/catalog, but not /products-fake. A trailing slash in a rule is optional. Query strings and fragments do not participate in path matching; search terms still come from the matched rule's parameters.

A more specific hostname wins before a parent hostname is considered. This preserves sources such as Gmail at mail.google.com. Explicit www aliases in the database let www.google.com/imgres match Google Images, while www.google.com/search still matches Google.

When pageUrl is supplied, internal-referral detection runs before source matching and compares exact hosts, including ports.

Features

• Supports 450+ sources across search engines, social media, email, paid ads, and AI chatbots
• AI/chatbot detection: ChatGPT, Claude, Perplexity, Gemini, DeepSeek, Grok, Copilot, and more
• Handles internal referrals
• TypeScript support with full type inference

Project Structure

• src/index.ts: Contains the main parsing logic
• src/types.ts: Defines the TypeScript interfaces
• src/index.test.ts: Contains the test suite

Testing

This library uses Vitest for testing. To run the tests, use the following command:

pnpm test

License

This project is licensed under the Apache-2.0 License.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

Development

To set up the project for development:

1. Clone the repository
2. Run pnpm i to install dependencies
3. Use pnpm test to run the test suite
4. Use pnpm build to build the project

Note: While pnpm is the preferred package manager for this project, npm or yarn should work as well.

Acknowledgements

• Snowplow referer-parser for the referer database
• Matomo searchengine-and-social-list for additional AI assistant and social media data
• nodejs-referer-parser for inspiration