PACify - Advanced Proxy Configuration Manager for Chrome

PACify is a powerful, modern Chrome extension for managing all types of proxy configurations. Built with Svelte 5 and TypeScript, it provides a professional-grade interface for creating, editing, and switching between different proxy configurations with ease.

✨ Key Features

📋 Latest Updates: See CHANGELOG.md for recent changes and version history.

🔄 Quick Switch Mode

• One-Click Proxy Switching: Click the extension icon to cycle through enabled proxy configurations
• Drag-and-Drop Management: Easily organize which proxies are in the quick switch rotation
• Visual Feedback: Color-coded badges show active proxy at a glance
• Smart Toggle: Enable/disable quick switch mode from the options page

🤖 Auto-Proxy (Automatic URL-Based Routing)

Intelligent automatic proxy switching based on URL patterns - no manual switching needed!

Key Features:

• Pattern-Based Rules: Define URL patterns that automatically route to specific proxies
• Multiple Match Types:
  • Domain matching (*.example.com, example.com)
  • Keyword matching (contains text)
  • Wildcard patterns for flexible routing
• Flexible Routing Options:
  • Route to existing proxy configurations
  • Define inline proxy settings per-rule
  • Direct connection (no proxy)
  • Blackhole (block requests)
• Smart Fallback: Configure default routing for URLs that don't match any rule
• Rule Management:
  • Enable/disable individual rules
  • Drag-and-drop priority ordering
  • Rule descriptions for documentation
• Pattern Tester: Test URLs against your rules to preview routing behavior
• Visual Rule Editor: Intuitive interface with color-coded rule cards

Common Use Cases:

• Work vs Personal: Route *.company.com through corporate proxy, everything else direct
• Geographic Routing: Send *.netflix.com to US proxy, *.bbc.co.uk to UK proxy
• Service Isolation: Different social media platforms through different proxies
• Development: Route *.local and 192.168.* directly, external sites through proxy

Technical Implementation:

• Powered by PAC (Proxy Auto-Configuration) script generation
• Real-time rule compilation and validation
• Optimized pattern matching for performance
• Supports complex rule sets with hundreds of patterns

🎯 Comprehensive Proxy Support

All Chrome Proxy Modes + Auto-Proxy:

• Auto-Proxy Mode: 🆕 Automatic URL-based routing with visual rule editor (see section above)
• System Proxy: Inherit proxy settings from your operating system
• Direct Connection: Bypass all proxies for direct internet access
• Auto-detect (WPAD): Automatically discover proxy settings using Web Proxy Auto-Discovery Protocol
• PAC Script: Create and run custom Proxy Auto-Config scripts with full JavaScript support
• Manual Configuration: Set up individual proxy servers for different protocols

📝 Professional PAC Script Editor

Powered by CodeMirror 6 (modern, lightweight code editor):

• Syntax Highlighting: Full JavaScript syntax highlighting for PAC scripts
• IntelliSense: Smart autocompletion for PAC functions (FindProxyForURL, isInNet, dnsResolve, etc.)
• Performance Optimized: 87% smaller bundle size with faster initialization
• Multiple Templates: Choose from 4 built-in templates:
  • Empty: Start from scratch
  • Basic: Simple proxy routing with internal domain bypass
  • Advanced: Complex routing with subnet detection and URL pattern matching
  • Pro: Enterprise-grade template with failover chains, time-based routing, geo-location handling, and security policies
• Theme Support: Automatic dark/light mode switching based on system preferences
• Modern Architecture: Built with CodeMirror 6's extensible plugin system
• URL-Based PAC Scripts: Load PAC scripts from external URLs
• Auto-Update: Configurable auto-update intervals (15 min to 24 hours) for URL-based scripts
• Manual Refresh: "Refresh now" button to immediately fetch latest PAC script
• Last Fetched Timestamp: Shows when script was last updated

⚙️ Manual Proxy Configuration

• Per-Protocol Proxies: Configure separate proxies for:
  • HTTP
  • HTTPS (Secure)
  • FTP
  • SOCKS (SOCKS4/SOCKS5)
• Shared Proxy Mode: Use a single proxy for all protocols
• Fallback Proxy: Define backup proxy for failover scenarios
• Bypass Rules: Set up domain/IP bypass list (one per line)
• Multiple Proxy Schemes: Support for HTTP, HTTPS, QUIC, SOCKS4, and SOCKS5

🎨 User Interface & Experience

Modern Navigation & Layout:

• Button Group Navigation: iOS/macOS-inspired segmented control for tab switching
• View Mode Toggle: Switch between grid and list layouts for proxy configurations
• Show Quick Settings: Toggle visibility of Quick Switch section
• Responsive Design: Optimized layouts for different screen sizes
• Enhanced Proxy Cards: Three-section layout (Header, Content, Footer) with refined shadows and borders

Visual Feedback & Identification:

• ACTIVE Badge: Prominent green badge with ShieldCheck icon on enabled proxies for instant identification
• Color-Coded Proxies: Assign colors to proxies for quick visual identification (8 color options)
• Badge Labels: Customizable 1-4 character labels for proxy identification
• Real-Time Status: Connection status banner shows active proxy
• Micro-Animations: Subtle scale effects on cards (hover, active states)

Interaction Enhancements:

• Tooltips: Context-sensitive help tooltips throughout the interface
• Keyboard Shortcuts:
  • Ctrl+N / Cmd+N (Mac: Cmd+N) - Add new proxy configuration
  • Escape - Close modal dialogs
  • Clear conflict handling to prevent shortcut interference
• Drag-and-Drop:
  • Custom styled drag ghost with proxy color and shadow
  • Drop zone highlighting with blue border and background tint
  • Source item visual feedback (fade, scale, blue ring)
• Inline Toggle Switches: Quick proxy switching directly from configuration cards

Design System:

• Modern UI: Clean, intuitive interface built with Tailwind CSS 4
• Dark Mode Support: Automatic dark theme based on system preferences
• Visual Hierarchy: Color-coded section headers with icons (Zap, Cable, Database)
• WCAG Compliance:
  • Level AA: Keyboard navigation with focus-visible states
  • Level AAA: 44x44px minimum touch targets
  • Proper ARIA labels and roles
  • Screen reader friendly

💾 Data Management

• Backup & Restore: Export/import all configurations as JSON
• Migrate from Other Extensions: 🆕 One-click import from Proxy SwitchyOmega / ZeroOmega, FoxyProxy, PAC scripts/URLs, PACify backups, and even the current browser proxy — auto-detects the format, previews exactly what will be created (with a report of anything skipped), and lets you merge into or replace your existing setup. See Migrating to PACify.
• Export to Other Tools: 🆕 Two-way migration — export your configs as a PACify backup, SwitchyOmega .bak, or FoxyProxy JSON.
• Cloud Sync: Settings sync across Chrome browsers via Chrome Sync Storage
• Storage Diagnostics: Monitor storage usage with visual progress bars
• Import Validation: Automatic validation when restoring from backup
• Cache Management: Intelligent caching with invalidation support

🔀 Migrating to PACify

Already using another proxy manager? Bring your whole setup over in seconds:

1. Export your configuration from your current extension:
   • Proxy SwitchyOmega / ZeroOmega: Options → Import/Export → Make backup (a .bak file).
   • FoxyProxy: Options → Export (a .json file).
   • PAC users: any .pac file or PAC script text.
2. In PACify, open Settings → Data Management → Import (or use the prompt on the onboarding screen / empty Proxy Configs view).
3. Drop in the file (or paste its contents) — PACify detects the format automatically. You can also paste a PAC URL, or click Detect current browser proxy to capture whatever proxy the browser is using right now.
4. Review the preview: how many proxies and rules will be created, plus any items that need your attention (copyable as a report). Choose Add to my configurations or Replace all, optionally download a safety backup, and confirm.

Leaving for another tool later? Settings → Data Management → Export writes your configs back out as a PACify backup, a SwitchyOmega .bak, or FoxyProxy JSON.

What gets mapped:

Source construct	Becomes in PACify
SwitchyOmega FixedProfile / FoxyProxy proxy	Manual (fixed-servers) proxy, with bypass list
SwitchyOmega PacProfile / .pac file	PAC Script config (URL or inline)
SwitchyOmega SwitchProfile rules	Auto-Proxy rules (wildcard / regex / IP-CIDR)
SwitchyOmega RuleListProfile / GFWList	Auto-Proxy subscription with cached rules
FoxyProxy URL patterns	Auto-Proxy configuration routed to the proxy

Everything runs locally — nothing is uploaded. Constructs without a PACify equivalent (e.g. time-based rules) are listed in the import report rather than dropped silently.

🔔 Notifications & Feedback

• Unified Notification System: Chrome system notifications and in-app toast messages
• Intelligent Routing: Automatic selection of notification type based on context (foreground/background)
• User Preferences: Toggle system notifications on/off from Settings
• Multiple Types: Success, error, warning, and info notifications
• Persistent Preferences: Notification settings sync across devices
• In-App Toasts: Non-intrusive toast notifications with auto-dismiss

🚀 Startup & Performance

• Startup Behavior Control: Choose to disable proxy on browser launch
• Auto-Reload Toggle: Enable/disable automatic page reload when switching proxies
• Smart Initialization: Message queuing system prevents race conditions during startup
• Debounced Saves: Optimized storage writes reduce unnecessary operations
• Mutex Locking: Prevents concurrent proxy changes
• Conditional Tab Reload: Intelligently reload tabs when proxy changes (skips special Chrome pages)

🔒 Privacy & Security

• Local-Only Storage: All data stored in Chrome's local/sync storage
• No External Requests: Extension doesn't transmit data to external servers
• No Tracking: Zero analytics or user tracking
• Secure Script Execution: PAC scripts run in isolated environment
• Manifest V3: Built with latest Chrome extension security standards

🌍 Internationalization

• Multi-Language Support: Full i18n framework with locale-based messages
• 12 Languages: 100% i18n compliance with proper translations for all supported locales
• Dynamic Loading: Messages loaded automatically based on browser locale
• Comprehensive Coverage: All UI elements, tooltips, and messages fully translated

📊 Dashboard & Statistics

• Quick Stats: View total proxies, quick switch count, active proxy, and last used
• Storage Metrics: Real-time sync and local storage usage with visual indicators
• Proxy Status: At-a-glance view of all proxy configurations
• Activity Tracking: Track which proxies are used most

🏗️ Technical Architecture

Technology Stack

• Frontend: Svelte 5 (with latest runes API)
• Language: TypeScript 5.7+ (strict mode)
• Build Tool: Vite 7 with code splitting
• Styling: Tailwind CSS 4 with PostCSS, tailwind-variants for component styling
• Code Editor: CodeMirror 6 (lightweight, modern)
• Icons: Lucide Svelte (tree-shaken with direct imports)
• Testing: Bun Test + Playwright
• Code Quality: Biome (Rust-based linting & formatting), Husky (git hooks)
• Runtime: Bun (10x faster than Node.js)

Project Structure

pacify/
├── src/
│   ├── background/          # Manifest V3 service worker
│   │   └── background.ts    # Message handling, proxy management
│   ├── popup/               # Extension popup UI
│   │   ├── Popup.svelte     # Quick proxy switcher
│   │   └── popup.html
│   ├── options/             # Options page (full settings)
│   │   ├── Options.svelte   # Tabbed interface with drag-and-drop
│   │   └── options.html
│   ├── components/          # Reusable Svelte components
│   │   ├── ProxyConfig/     # Configuration modal & forms
│   │   ├── DragDrop/        # Drag-and-drop system
│   │   ├── Tabs/            # Tab navigation
│   │   └── common/          # Shared UI primitives
│   ├── services/            # Business logic layer
│   │   ├── chrome/          # Chrome API abstractions
│   │   ├── i18n/            # Internationalization
│   │   ├── CodeMirrorService.ts # CodeMirror editor integration
│   │   ├── StorageService.ts # Settings persistence
│   │   ├── ScriptService.ts  # PAC script validation
│   │   ├── NotifyService.ts  # Notification system (toasts + Chrome notifications)
│   │   └── LoggerService.ts  # Centralized logging
│   ├── stores/              # Svelte stores (state management)
│   │   ├── settingsStore.ts # Central app state
│   │   ├── proxyStore.ts
│   │   └── toastStore.ts
│   ├── interfaces/          # TypeScript type definitions
│   ├── constants/           # App constants & templates
│   └── utils/               # Utility functions
├── tests/
│   ├── e2e/                 # Playwright E2E tests
│   ├── unit/                # Vitest unit tests
│   └── integration/         # Integration tests
├── _locales/                # i18n message files
│   └── en/messages.json
└── icons/                   # Extension icons

Chrome Extension Architecture

• Manifest Version: 3 (latest)
• Service Worker: Event-driven background script with message queue and alarm-based auto-refresh
• Popup: Lightweight proxy switcher (384px width, 400px height)
• Options Page: Full-featured settings with modern button group navigation
• Permissions: proxy, storage, alarms, notifications
• Background Tasks: Automatic PAC script updates using Chrome alarms API

🚀 Getting Started

Installation from Source

1. Clone the repository:

   git clone https://github.com/navbytes/pacify.git
   cd pacify

2. Install dependencies:

   bun install
   # or: npm install / pnpm install / yarn install

3. Build the extension:

   # Production build
   bun run build
   
   # Development build with watch mode
   bun run dev:extension

4. Load in Chrome:

   • Navigate to chrome://extensions/
   • Enable "Developer mode" (top-right toggle)
   • Click "Load unpacked"
   • Select the dist/ directory (or dev/ for development builds)

Development Scripts

# Development server (for component development)
bun run dev

# Build extension in watch mode
bun run dev:extension

# Production build
bun run build

# Run unit tests
bun run test

# Run E2E tests
bun run test:e2e

# Lint code
bun run lint

# Format code
bun run format

# Type checking
bun run check

💻 Usage Guide

Creating Your First Proxy

1. Click the PACify icon in Chrome's toolbar
2. Click "Settings" (gear icon) to open the options page
3. Click "Add New Script" button
4. Fill in basic information:
   • Name: Give your proxy a descriptive name
   • Color: Choose a color for visual identification
5. Select Proxy Mode:
   • System: Use OS proxy settings
   • Direct: No proxy (direct connection)
   • Auto-detect: WPAD auto-discovery
   • PAC Script: Write custom routing logic
   • Manual: Configure specific proxy servers
6. Click "Save" to create the configuration

Using Quick Switch

1. Open Options → Proxy Configs tab
2. Enable "Quick Switch Mode" toggle
3. Drag proxy configurations to the "Quick Switch Configs" section
4. Click the extension icon to cycle through enabled proxies
5. Badge shows active proxy name (first 3 letters)

Setting Up Auto-Proxy (Automatic Routing)

1. Click "Add Auto-Proxy" button (orange button with branch icon)
2. Configure Basic Settings:
   • Name: Descriptive name (e.g., "Work Router")
   • Color: Visual identifier
   • Badge Label: 1-4 character label (optional)
3. Add Routing Rules:
   • Click "Add Rule" to create a new routing rule
   • Pattern: URL pattern to match (e.g., *.company.com, github.com, *.local)
   • Match Type: Choose domain, keyword, or wildcard matching
   • Route To: Select destination (existing proxy, inline proxy, direct, or blackhole)
   • Description: Optional note for the rule
   • Enable/disable rules with toggle switch
4. Configure Fallback:
   • Set default routing for URLs that don't match any rule
   • Options: direct, existing proxy, or inline proxy
5. Test Your Rules:
   • Use the Pattern Tester to verify routing
   • Enter test URLs to see which rule/proxy they match
6. Reorder Rules (optional):
   • Drag rules to change priority
   • Rules are evaluated top-to-bottom (first match wins)
7. Click "Save" to activate

Example Configuration:

• Rule 1: *.company.com → Corporate Proxy
• Rule 2: *.github.com → Direct Connection
• Rule 3: netflix.com → US Proxy
• Fallback: Direct Connection

Writing PAC Scripts

1. Create a new proxy configuration
2. Select "PAC Script" mode
3. Choose a template:
   • Basic: For simple internal/external routing
   • Advanced: For subnet detection and pattern matching
   • Pro: For enterprise scenarios with failover
4. Edit the script in CodeMirror Editor:
   • Intelligent autocompletion for PAC functions
   • Available PAC functions: isInNet, dnsResolve, shExpMatch, etc.
   • Automatic theme switching (dark/light mode)
   • Test with different URLs before saving
5. Save and activate the proxy

Manual Proxy Setup

1. Select "Manual Configuration" mode
2. Choose between:
   • Shared Proxy: Same proxy for all protocols
   • Per-Protocol: Different proxies for HTTP, HTTPS, FTP
3. Enter proxy details:
   • Scheme: http, https, socks4, socks5, quic
   • Host: Proxy server address
   • Port: Proxy server port
4. Add bypass rules (optional):
   • Enter domains/IPs to bypass proxy (one per line)
   • Example: *.local, 192.168.*.*, localhost

Backup & Restore

To Backup:

1. Go to Options → Settings tab
2. Click "Backup Settings"
3. JSON file downloads with all configurations

To Restore:

1. Go to Options → Settings tab
2. Click "Restore Settings"
3. Select your backup JSON file
4. All configurations are restored and validated

📋 Chrome Permissions

PACify requires minimal permissions:

• proxy: To manage Chrome's proxy settings
• storage: To save configurations locally and sync across devices
• alarms: For background auto-refresh of URL-based PAC scripts
• notifications: For system notifications when enabled in settings

No permissions for network access, browsing history, or tabs data beyond what's necessary for core functionality.

🔧 Configuration Options

App Settings

Setting	Description	Default
Quick Switch Mode	Enable one-click proxy cycling	false
Disable Proxy on Startup	Clear proxy when browser starts	false
Auto-Reload on Switch	Automatically reload tabs when changing proxies	true
System Notifications	Enable Chrome system notifications	true
Show Quick Settings	Show/hide Quick Switch section in UI	true
View Mode	Display proxy configs in grid or list layout	grid

Proxy Configuration Fields

Field	Type	Description
Name	Text	Proxy configuration name (required)
Color	Choice	Visual color identifier (8 options)
Mode	Dropdown	Proxy type (system/direct/auto/PAC/manual)
Quick Switch	Toggle	Include in quick switch rotation
Active	Auto	Currently active proxy (one at a time)

PAC Script Fields

Field	Description
Script Data	JavaScript PAC script content (inline mode)
Script URL	External PAC script URL (alternative to inline)
Update Interval	Auto-update frequency (15min - 24hrs) for URL-based scripts
Last Fetched	Timestamp showing when URL-based script was last refreshed
Mandatory	Fail closed if PAC script fails

Manual Proxy Fields

Field	Description
Scheme	Proxy protocol (http/https/socks4/socks5/quic)
Host	Proxy server hostname or IP
Port	Proxy server port number
Bypass List	Domains/IPs to bypass proxy

🧪 Testing

Test Suite Status: 113 unit tests passing with comprehensive Chrome API mocks

Unit Tests

# Run all unit tests
bun run test

# Run with UI
bun run test:ui

# Run with coverage
bun run test:coverage

Recent Improvements:

• Fixed test hanging issues with Chrome API mock timing
• Comprehensive mocks for notifications, tabs, storage, and proxy APIs
• Enhanced test infrastructure with proper singleton handling

E2E Tests

# Run all E2E tests
bun run test:e2e

# Run with UI
bun run test:e2e:ui

# Run smoke tests only
bun run test:e2e:smoke

Test Automation:

• Playwright-based E2E testing with data-testid attributes
• Improved test reliability with proper element selectors
• Smoke tests for critical user flows

🤝 Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Development Guidelines

• Follow TypeScript strict mode with zero type errors
• Use Svelte 5 runes API (avoid legacy stores in components)
• Use Biome for linting and formatting (10x faster than ESLint/Prettier)
• Write tests for new features (unit tests with Bun, E2E with Playwright)
• Run bun run lint and bun run format before committing
• Use tailwind-variants for component styling (replaced CVA)
• Import Lucide icons directly (not from barrel exports) for better tree-shaking
• Update documentation for significant changes

📜 License

This project is licensed under the MIT License - see the LICENSE file for details.

🛡️ Security & Privacy

• Local Storage Only: All configurations stored in Chrome's local/sync storage
• No External Servers: Extension operates entirely offline
• No Analytics: Zero telemetry or usage tracking
• No Third-Party Services: No external dependencies at runtime
• Open Source: Full source code available for audit

For more details, see our Privacy Policy.

💬 Support & Feedback

• Issues: GitHub Issues
• Discussions: GitHub Discussions
• Feature Requests: Open an issue with the "enhancement" label

🌟 Acknowledgments

Built with these amazing open-source projects:

• Svelte - Reactive UI framework
• TypeScript - Type-safe JavaScript
• CodeMirror 6 - Modern, lightweight code editor
• Vite - Next-generation build tool
• Tailwind CSS - Utility-first CSS framework
• tailwind-variants - Component styling library
• Lucide Icons - Beautiful icon set
• Bun - Fast JavaScript runtime and package manager
• Biome - Rust-based linting and formatting
• Playwright - Reliable E2E testing

Special thanks to all contributors and the open-source community! 🙏

---

Made with ❤️ by the PACify team