---
description: When user works on Chrome extension files (manifest.json, background/content scripts, popup files), apply these best practices for structure, security, performance, and UX
globs: manifest.json, background.js, content.js, **/popup/*
alwaysApply: false
---
# Rules for Chrome Extension Development
## Architecture & Structure
- Organize code according to Chrome extension components (background, content, popup)
- Keep manifest.json updated with the latest schema version
- Use a modular approach for different extension features
- Implement clear communication between different scripts (background, content, popup)
- Consider using a framework like React for popup UIs if they're complex
## Background Scripts
- Minimize background script resource usage
- Use service workers instead of persistent background pages
- Implement proper state management without relying on global variables
- Use Chrome storage API for persistent data instead of localStorage
- Handle extension lifecycle events properly (install, update, uninstall)
## Content Scripts
- Keep content scripts lightweight and focused
- Minimize DOM manipulation in content scripts
- Use MutationObserver for tracking DOM changes
- Avoid conflicts with the website's JavaScript
- Use unique CSS selectors and namespaces to prevent style conflicts
## Permissions
- Follow the principle of least privilege
- Request only the permissions your extension actually needs
- Explain to users why each permission is needed
- Consider optional permissions for features that aren't core to the extension
- Re-evaluate permission needs with each new version
## Security
- Sanitize any data injected into the DOM to prevent XSS attacks
- Validate messages between extension components
- Implement proper Content Security Policy
- Use secure authentication methods for API access
- Be cautious with executing code dynamically (eval, new Function)
## Performance
- Minimize resource usage, especially in background scripts
- Implement lazy loading for non-critical features
- Use event-driven programming to avoid polling
- Optimize content script performance, especially for frequently visited pages
- Monitor memory usage and implement cleanup where necessary
## User Experience
- Design a clear and intuitive UI for popup and options pages
- Provide feedback for user actions
- Implement proper error handling with user-friendly messages
- Make the extension accessible (keyboard navigation, screen reader support)
- Consider internationalization for broader audience
## Testing
- Test on different websites for content script functionality
- Verify behavior with different Chrome versions
- Test installation, updates, and uninstallation
- Implement unit tests for core functionality
- Use browser automation for end-to-end testing
## Distribution & Maintenance
- Keep detailed changelogs
- Provide clear documentation
- Plan for Chrome manifest changes (V2 to V3 migration)
- Respond to user feedback and bug reports promptly
- Implement analytics to understand feature usage (with user consent)
## Privacy
- Be transparent about data collection
- Implement proper data handling and privacy practices
- Provide options to opt-out of non-essential data collection
- Include a privacy policy if collecting any user data
- Respect user data and don't collect unnecessary information
