A typed referer parser library
npm install ts-referer-parserbash
pnpm add ts-referer-parser
`
If you're using npm or yarn, you can use their respective commands:
`bash
npm install ts-referer-parser
or
yarn add ts-referer-parser
`
Usage
`typescript
import { parse } from "ts-referer-parser";
async function example() {
let result = await parse("", "http://www.example.com/");
console.log("Direct traffic:", result);
// Output: Direct traffic: { medium: 'direct', referer: null, term: null }
result = await 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 = await 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' }
}
example();
`
$3
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:
`javascript
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 = await 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
$3
Parses the given referer URL and returns a Promise that resolves to a Referer object containing:
- medium: The type of referer (e.g., 'search', 'social', 'unknown', 'internal', 'direct', 'invalid')
- referer: The name of the referer (e.g., 'google', 'facebook', 'twitter')
- term: The search term used, if applicable (null otherwise)
Features
- Supports various search engines, social media platforms, and email providers
- Handles internal referrals
- Typescript support
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:
`bash
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