Skip to content

README.md

Latest commit

 

History

History
194 lines (143 loc) · 5.68 KB

README.md

File metadata and controls

194 lines (143 loc) · 5.68 KB
Raw

X User Country Extension

An unofficial Chrome extension that displays country badges next to X.com (Twitter) usernames.

Version Manifest

Features

  • 🌍 Displays country flags and names next to X.com usernames
  • ⚡ Smart caching system (7-day cache for countries, 1-day for not found)
  • 🔄 Automatic retry with exponential backoff
  • 📊 Error handling with user-friendly error badges
  • 🎨 Seamless integration with X.com's UI (light/dark mode support)

Installation

From Source (Developer Mode)

  1. Clone or download this repository
  2. Open Chrome and navigate to chrome://extensions/
  3. Enable "Developer mode" (toggle in top right)
  4. Click "Load unpacked"
  5. Select the extension directory

From Chrome Web Store

Coming soon (pending submission)

How It Works

The extension:

  1. Detects username elements on X.com pages using a MutationObserver
  2. Loads each user's /about page in a hidden iframe
  3. Extracts the "Account based in [Country]" field
  4. Displays a country flag emoji and name next to the username
  5. Caches results locally to minimize requests

⚠️ Important Disclaimer

This extension scrapes publicly available data from X.com.

  • This is an unofficial extension, not affiliated with or endorsed by X Corp.
  • Usage may violate X.com's Terms of Service
  • The extension implements rate limiting (2-second delays) to be respectful of X.com's servers
  • Use at your own risk - we are not responsible for any consequences

See DISCLAIMER.md for full legal information.

Privacy

  • All data is stored locally on your device
  • No data is transmitted to external servers
  • No analytics or tracking is performed
  • Only accesses publicly available X.com profile information

See PRIVACY.md for full privacy policy.

Development

Project Structure

├── manifest.json          # Extension manifest
├── content.js            # Main logic (DOM observation, scraping)
├── styles.css            # Badge styling
├── popup.html            # Extension popup UI
├── rules.json            # DeclarativeNetRequest rules
├── icons/                # Extension icons
├── CLAUDE.md            # Development guide
├── PRIVACY.md           # Privacy policy
└── DISCLAIMER.md        # Legal disclaimer

Building

No build step required - this is a pure JavaScript extension.

For icon generation from SVG:

cd icons
npm install --no-save sharp
node convert-icons.js

Testing

  1. Make changes to code
  2. Go to chrome://extensions/
  3. Click reload icon on extension card
  4. Navigate to x.com and test

See CLAUDE.md for detailed development documentation.

Chrome Web Store Submission Checklist

Before submitting to the Chrome Web Store:

  • Extension icons created (16x16, 48x48, 128x128)
  • Privacy policy created
  • Legal disclaimer added
  • Error handling implemented
  • Host privacy policy at public URL
  • Add privacy policy URL to manifest
  • Create 5+ screenshots for store listing
  • Write compelling store description
  • Prepare justification for permissions
  • Test on multiple X.com pages (home, profile, replies)
  • Test error scenarios (rate limiting, timeouts)
  • Consider X.com Terms of Service implications

Permissions Justification

The extension requires the following permissions:

  • storage: To cache country data locally for performance
  • declarativeNetRequest: To remove X-Frame-Options headers (allows iframe embedding)
  • host_permissions for x.com/twitter.com: To inject badges and scrape profile pages

Contributing

Contributions welcome! Please:

  1. Fork the repository
  2. Create a feature branch
  3. Make your changes
  4. Submit a pull request

License

[Add your chosen license here - e.g., MIT, GPL, etc.]

Support

For issues, questions, or suggestions:

Changelog

v1.2.0 (2026-03-07) - Production Ready Release

New Features:

  • ⚙️ Full settings/options page with customization
  • 🎨 Smooth animations and transitions
  • 📊 Storage quota management with auto-eviction
  • 🔄 Graceful degradation for X.com structure changes

Settings & Customization:

  • Enable/disable extension
  • Badge style (flag + text, flag only, text only)
  • Toggle loading states, errors, "not found" messages
  • Privacy mode (no caching)
  • Adjustable throttle delay and cache expiry
  • Cache management (view stats, clear cache)

Performance:

  • IntersectionObserver for lazy loading (only visible badges)
  • Mutation batching (50ms debounce)
  • Optimized selectors and DOM queries
  • 200px preloading margin

UX Improvements:

  • Fade-in animations for all badges
  • Hover effects (scale + opacity)
  • Loading state pulse animation
  • Error state pulse to draw attention
  • Accessibility support (prefers-reduced-motion)

Resilience:

  • Fallback selectors for X.com changes
  • Auto-detection of working selectors
  • Robust username extraction with fallbacks
  • Storage quota warnings and auto-cleanup

v1.1.0 (2026-03-07) - Critical Improvements

  • Added comprehensive error handling
  • Implemented exponential backoff for retries
  • Added rate limit detection
  • Improved error badges with helpful tooltips
  • Added privacy policy and legal disclaimer
  • Created extension icons
  • Improved documentation

v1.0.0 (Initial Release)

  • Basic country badge functionality
  • Iframe-based scraping
  • Local caching system
  • DOM observation for dynamic content

Made with ❤️ for the X.com community

Remember: Use responsibly and respect X.com's Terms of Service