@tryghost/referrer-parser

Referrer Parser

A simple library for parsing referrer URLs to identify their source and medium.

Installation

npm install @tryghost/referrer-parser
# or
yarn add @tryghost/referrer-parser

Usage

Basic Usage

const { parse } = require('@tryghost/referrer-parser');

// Parse a referrer URL
const result = parse('https://www.google.com/search?q=ghost+cms');
console.log(result);
// {
//   referrerSource: 'Google',
//   referrerMedium: 'search',
//   referrerUrl: 'www.google.com'
// }

With Site Configuration

const { parse } = require('@tryghost/referrer-parser');

// Parse with site configuration to detect internal traffic
const result = parse(
  'https://example.com/blog?utm_source=newsletter&utm_medium=email',
  { 
    siteUrl: 'https://example.com',
    adminUrl: 'https://example.com/ghost'
  }
);

Using the ReferrerParser Class

For more advanced usage, you can use the ReferrerParser class directly:

const { ReferrerParser } = require('@tryghost/referrer-parser');

// Create a parser instance
const parser = new ReferrerParser({
  siteUrl: 'https://example.com',
  adminUrl: 'https://example.com/ghost'
});

// Parse multiple URLs with the same configuration
const result1 = parser.parse('https://www.google.com/search?q=ghost+cms');
const result2 = parser.parse('https://twitter.com/ghostcms');

Features

• Identifies sources and mediums from known referrers
• Handles special cases for Ghost Explore and Ghost Newsletters
• Detects UTM parameters
• Works with or without site/admin URL configuration
• TypeScript support

TypeScript Support

This package is fully written in TypeScript and provides its own type definitions.

import { parse, ReferrerParser, ReferrerData, ParserOptions } from '@tryghost/referrer-parser';

// Parse a referrer URL with type safety
const result: ReferrerData = parse('https://www.google.com/search?q=ghost+cms');
console.log(result.referrerSource);  // 'Google'
console.log(result.referrerMedium);  // 'search'
console.log(result.referrerUrl);     // 'www.google.com'

// Configure the parser with typed options
const options: ParserOptions = {
  siteUrl: 'https://example.com',
  adminUrl: 'https://example.com/ghost'
};

// Create a parser instance with TypeScript
const parser = new ReferrerParser(options);
const customResult = parser.parse('https://example.com/blog?utm_source=newsletter');

License

MIT

Testing

Run the tests with:

yarn test

This will run the test suite using Mocha and report on test coverage.