X User Country Extension

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

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:

• Open an issue on GitHub
• Email: [your-email@example.com]

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