url-cleaner/CLAUDE.md

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

This is a Cloudflare Workers project called "url-cleaner" built with TypeScript. It's a serverless URL cleaning service that removes tracking parameters from URLs, similar to the ClearURLs browser extension. The worker runs on Cloudflare's edge network for fast global performance.

Architecture

• Runtime: Cloudflare Workers (serverless edge computing)
• Language: TypeScript with ES2021 target
• Entry Point: src/index.ts - main worker handler accepting ?url= parameter
• URL Cleaner: src/cleaner.ts - core cleaning engine with redirect following and fragment cleaning
• Rules Cache: src/rules-cache.ts - Durable Object for caching ClearURLs rules with SHA256 validation
• Types: src/types.ts - TypeScript interfaces for ClearURLs rule structure
• Configuration: wrangler.jsonc - Cloudflare Workers deployment configuration with Durable Objects
• Testing: Vitest with Cloudflare Workers testing pool

API Usage

Clean URL Endpoint

Endpoint: GET /?url=<encoded-url> Response: Plain text containing the cleaned URL

Examples:

• /?url=https://example.com?utm_source=test → https://example.com
• /?url=https://youtube.com/watch?v=abc&feature=share → https://youtube.com/watch?v=abc

Cache Purge Endpoint

Endpoint: DELETE /?url=<encoded-url> Response: Plain text confirming cache deletion

Examples:

• DELETE /?url=https://example.com?utm_source=test → Cache entry deleted (200)
• DELETE /?url=https://nonexistent.com → Cache entry not found (404)

Common Commands

Development

• npm run dev or npm run start - Start local development server with Wrangler
• npm run deploy - Deploy worker to Cloudflare
• npm test - Run tests with Vitest
• npm run format - Format code with Prettier
• npm run format:check - Check code formatting
• npm run cf-typegen - Generate TypeScript types for Cloudflare bindings

Development Server

The development server runs on http://localhost:8787/ by default.

Project Structure

src/
├── index.ts          # Main worker entry point with fetch handler
├── cleaner.ts        # Core URL cleaning engine with redirect following and fragment cleaning
├── rules-cache.ts    # Durable Object for caching ClearURLs rules with validation
└── types.ts          # TypeScript interfaces for ClearURLs rule structure
test/
├── index.spec.ts     # Unit and integration tests with ClearURLs rule mocking
├── tsconfig.json     # Test-specific TypeScript config
└── env.d.ts          # Test environment types

URL Cleaning Features

Core Functionality

• Official ClearURLs Rules: Uses the same rule database as ClearURLs browser extension (250+ providers)
• Redirect Following: Follows up to 5 redirects to unwrap shortened URLs and tracking redirects
• Provider-Specific Rules: Domain-specific rules prevent false positives and preserve functionality
• Query Parameter Cleaning: Removes tracking from URL query parameters (?utm_source=test)
• Fragment Cleaning: Removes tracking from URL fragments/hash parameters (#utm_campaign=test)
• Raw Rules Support: Handles complex regex-based cleaning for advanced tracking patterns
• Loop Prevention: Tracks visited URLs to prevent infinite redirect loops
• Response Caching: 1-hour cache using Cloudflare Cache API for improved performance
• Cache Management: DELETE endpoint for manual cache purging

Rule System

• Live Updates: Fetches rules from ClearURLs official API (https://rules2.clearurls.xyz/)
• SHA256 Validation: Cryptographically verifies rule integrity
• Durable Object Caching: 7-day cache with automatic refresh
• Fallback Support: Uses cached rules if fresh fetch fails
• Provider Priority: Domain-specific providers take precedence over global rules

Supported Providers (250+ total)

• Google: Search, Analytics, Ads tracking removal
• YouTube: Preserves video/playlist IDs, removes tracking
• Amazon: E-commerce functionality preserved, affiliate tracking removed
• Facebook/Meta: Social features preserved, tracking removed
• Twitter/X: Post/user functionality preserved, tracking removed
• TikTok: Video functionality preserved, tracking removed
• And 240+ more providers maintained by the ClearURLs community

Advanced Features

• Exception Handling: Respects provider-specific exception rules
• Redirection Unwrapping: Follows ClearURLs redirection patterns
• Regex Pattern Matching: Exact ClearURLs compatibility with ^rule$ pattern matching
• Case-Insensitive Matching: Handles mixed-case tracking parameters
• Fragment Parameter Support: Cleans tracking from URL hash fragments

Key Files

• wrangler.jsonc - Worker configuration including compatibility date and observability
• vitest.config.mts - Test configuration using Cloudflare Workers pool
• worker-configuration.d.ts - Generated TypeScript definitions for Cloudflare bindings
• tsconfig.json - TypeScript configuration with strict mode enabled

Testing

The project uses Vitest with the Cloudflare Workers testing pool (@cloudflare/vitest-pool-workers). Tests support both unit testing (with mocked context) and integration testing (using SELF.fetch()).

TypeScript Configuration

• Target: ES2021
• Module: ES2022
• Strict mode enabled
• JSX support configured for React
• Excludes test files from main compilation