Clean URL - Chrome Extension
A privacy-focused Chrome extension that removes tracking parameters from URLs with a single click. Built with WXT framework and TypeScript for a modern, type-safe development experience.
🚀 Features
- Manual URL Cleaning: Click the extension icon to clean the current tab's URL
- Comprehensive Tracking Removal: Removes 25+ types of tracking parameters
- Visual Feedback: Shows badge with tracking parameter count
- Copy to Clipboard: Easily copy cleaned URLs
- Privacy First: All processing happens locally - no data collection
- Real-time Analysis: Instantly see what tracking parameters are found
- TypeScript: Fully type-safe codebase with excellent IDE support
- Modern Development: Hot Module Replacement (HMR) for instant feedback
📋 Supported Tracking Parameters
UTM Parameters
utm_source, utm_medium, utm_campaign, utm_term, utm_content, utm_nooverride
Social Media Trackers
fbclid (Facebook Click ID)igshid (Instagram Share ID)ttclid (TikTok Click ID)tiktok_r (TikTok Referral)li_fat_id (LinkedIn Fat ID)mkt_tok (LinkedIn/Marketo token)
Ad Platform Trackers
gclid (Google Click ID)yclid (Yandex Click ID)dclid (DoubleClick Click ID)msclkid (Microsoft Click ID)gad_source, gad_campaignid, gbraid (Google Ads)utm_ad, matchtype, campaign_id, ad_id (Campaign tracking)
Email & Newsletter Trackers
ck_subscriber_id (ConvertKit)mc_cid, mc_eid (MailChimp)_hsenc, _hsmi (HubSpot)
Affiliate & Referral Trackers
ref, referral, affiliate_id, click_id, subid, partner_id
View complete list
🔧 Installation
For Users
- Download from the Chrome Web Store (coming soon)
- Click "Add to Chrome"
- Start cleaning URLs by clicking the extension icon!
For Developers
-
Clone this repository:
git clone https://github.com/laststance/clean-url.git
cd clean-url
-
Install dependencies (using pnpm):
pnpm install
-
Start development server:
pnpm dev
-
Load the extension in Chrome:
- Open Chrome and go to
chrome://extensions/
- Enable "Developer mode"
- Click "Load unpacked" and select
.output/chrome-mv3 directory
-
The extension icon should appear in your toolbar with live reloading!
📱 Usage
Basic Usage
- Navigate to any URL with tracking parameters
- Click the Clean URL extension icon
- Review the tracking parameters found
- Click "Apply Cleaned URL" to navigate to the clean version
Copy Cleaned URLs
- Use the copy button next to the cleaned URL
- Share clean URLs without exposing tracking data
Context Menu
- Right-click on any link
- Select "Clean this link" to copy a cleaned version
🛡️ Privacy & Security
Data Minimization
- Local Processing Only: All URL cleaning happens in your browser
- No Data Collection: We don't collect, store, or transmit any user data
- No Analytics: No usage tracking or telemetry
- No Remote Requests: Fully offline functionality
Security Best Practices
- Content Security Policy compliance
- Minimal permissions (only
tabs, storage, contextMenus)
- Input validation and sanitization
- Open source and auditable
🧪 Testing
Run Unit Tests
pnpm test
Run Unit Tests with Coverage (93.78%)
pnpm test:coverage
Run E2E Tests
pnpm install:playwright
pnpm test:e2e
Run in Watch Mode
pnpm test:watch
Run All Validation
pnpm validate # Runs lint, tests, and TypeScript checks
🏗️ Development
Project Structure
clean-url/
├── wxt.config.ts # WXT framework configuration
├── tsconfig.json # TypeScript configuration
├── vitest.config.ts # Vitest testing configuration
├── entrypoints/ # Extension entrypoints (WXT convention)
│ ├── background.ts # Service worker
│ └── popup/ # Popup interface
│ ├── index.html # Popup HTML
│ ├── main.ts # Popup logic
│ └── style.css # Popup styling
├── utils/ # Shared utilities
│ └── clean-url-logic.ts # Core cleaning logic (TypeScript)
├── public/ # Static assets
│ ├── icon-*.png # Extension icons
│ └── privacy-policy.md # Privacy policy
├── scripts/ # Release automation
│ └── submit-chrome.mjs # Chrome Web Store API v2 verification and submission
├── tests/ # Test suites
│ ├── unit/ # Vitest unit tests
│ ├── e2e/ # Playwright E2E tests
│ ├── test-urls.json # Test fixtures
│ └── setup.ts # Test setup
└── .output/ # Build output
└── chrome-mv3/ # Built extension
Key Components
Core Logic (utils/clean-url-logic.ts)
TypeScript module containing URL cleaning algorithms and tracking parameter patterns with full type safety.
Popup Interface (entrypoints/popup/)
User interface built with TypeScript, including URL display, cleaning controls, and feedback.
Background Service Worker (entrypoints/background.ts)
Handles badge updates, context menus, and extension lifecycle using WXT's defineBackground pattern.
Technology Stack
- Framework: WXT (Web Extension Tools)
- Language: TypeScript 5.9
- Testing: Vitest (unit) + Playwright (E2E)
- Build: Vite (via WXT)
- Manifest: V3 (auto-generated)
Development Commands
pnpm dev # Start dev server with HMR
pnpm build # Build production extension
pnpm zip # Create distribution ZIP
pnpm typecheck # TypeScript type checking
pnpm lint # ESLint code quality check
pnpm validate # Run all quality checks
Adding New Tracking Parameters
- Add the parameter to
TRACKING_PARAM_PATTERNS in utils/clean-url-logic.ts
- Add test cases to
tests/test-urls.json
- Update this README documentation
- Run tests to ensure compatibility:
pnpm test
🤝 Contributing
We welcome contributions! Please see our Contributing Guidelines for details.
Development Setup
- Fork the repository
- Create a feature branch:
git checkout -b feature-name
- Make your changes with TypeScript
- Add tests for new functionality
- Run the test suite:
pnpm validate
- Commit your changes:
git commit -am 'Add feature'
- Push to the branch:
git push origin feature-name
- Create a Pull Request
Reporting Issues
- Use the GitHub Issues page
- Provide detailed reproduction steps
- Include browser version and extension version
- Add example URLs that demonstrate the issue
📝 License
This project is licensed under the ISC License - see the LICENSE file for details.
🔗 Links
📊 Statistics
- Language: TypeScript
- Framework: WXT
- Test Coverage: 93.78%
- Tracking Parameters: 25+ supported
- Build Size: ~40KB
- Tests: 163 passing
🎯 Roadmap
🙏 Acknowledgments
- Inspired by the need for better online privacy
- Built with WXT - next-generation web extension framework
- Powered by Vite for blazing fast builds
- Thanks to the open source community for tools and libraries
Made with ❤️ for privacy-conscious users
Clean URL helps you browse the web without leaving tracking breadcrumbs behind.
