cleanURL

cleanURL is a Manifest V3 Chrome extension that removes tracking query parameters from URLs (for example utm_*, gclid, fbclid) to make links cleaner, more private, and easier to share.

All URL processing is local in the extension. No browsing data is sent to external services.

Features

• Auto-clean URLs during navigation (toggle in settings)
• Clean the current tab URL from the popup
• Context-menu action to copy a cleaned link
• Customizable blocked parameter list
• Local settings and lightweight clean-count stats via chrome.storage.local

Tech Stack

• React 19 + TypeScript
• Vite 8
• CRXJS (@crxjs/vite-plugin) for Chrome extension build/runtime integration
• Vitest for unit tests

Requirements

• Node.js 18+
• pnpm (recommended) or npm
• Google Chrome (Developer Mode for unpacked extension)

Quick Start

1. Install dependencies:

pnpm install

2. Start development:

pnpm dev

3. Load extension in Chrome:

• Open chrome://extensions/
• Enable Developer mode
• Click Load unpacked
• Select the dist/ folder

CRXJS supports hot updates during pnpm dev.

Build and Test

Build production bundle:

pnpm build

Run tests:

pnpm test

Preview Vite output (optional):

pnpm preview

Install and Use Release Build

Use this when you want the packaged extension instead of running pnpm dev.

1. Build the release package:

pnpm build

This generates:

• unpacked extension files in dist/
• packaged zip in release/*.zip

2. Install in Chrome:

• Open chrome://extensions/
• Enable Developer mode
• Click Load unpacked
• Select the dist/ folder

Note: Chrome does not allow installing a .zip directly from the extensions page. If you have a zip from release/, extract it first, then load the extracted folder as unpacked.

3. Use the extension:

• Pin cleanURL from the Chrome toolbar extensions menu
• Open any normal web page with tracking parameters (for example ?utm_source=...)
• Click the extension icon and use:
  • Clean Now to clean the current tab URL
  • Copy to copy the cleaned URL
  • AUTO toggle to enable/disable automatic cleaning during navigation
• Right-click any link and choose Copy Clean Link to copy a cleaned version directly

Manifest and Icon Paths

Manifest is defined in manifest.config.ts.

Current icon paths are root-relative in the built extension package:

• 48.png for extension icon
• 48.png for action icon

If your icon assets are stored under public/, keep using root-relative paths in the manifest output (for example "48.png", not "public/48.png") because Vite copies public/ contents to the extension root.

Project Structure

• src/core/ - Pure URL cleaning logic (no Chrome APIs)
• src/background/serviceWorker.ts - MV3 service worker orchestration
• src/lib/storage/ - Typed wrappers for chrome.storage.local
• src/popup/ - Popup UI
• src/content/ - Content script entry
• src/sidepanel/ - Side panel entry
• manifest.config.ts - MV3 manifest source for CRXJS

Architecture Notes

• src/core/cleanUrl.ts: main cleaner returning cleaned URL + removed params
• src/core/rules.ts: default blocked params + normalization helpers
• src/core/defaults.ts: default settings + settings-to-rules bridge
• src/core/domain.ts: guards for non-cleanable/internal URLs
• src/background/serviceWorker.ts: navigation auto-clean + redirect loop prevention
• src/lib/storage/settings.ts: sanitizes and merges settings with defaults

Design Constraints

• Ask before adding runtime dependencies
• Ask before changing manifest permissions
• Ask before adding Firefox/Safari packaging
• Never store or transmit browsing history
• Keep src/core/ side-effect-free and Chrome-API-free
• Blocked param matching must remain case-insensitive
• Auto-clean must prevent redirect loops

License

No license file is currently defined in this repository.