|
1 | 1 | # 📧 Gmail Alias Toolkit |
2 | 2 |
|
3 | | -A powerful browser extension for generating and managing Gmail aliases using plus addressing (+tag). Streamline your email workflow with smart presets, favorites, context menus, and Gmail tricks. |
| 3 | +A powerful browser extension for generating and managing Gmail aliases using plus addressing (+tag). Streamline your email workflow with random generators, custom presets, favorites, and comprehensive statistics. |
4 | 4 |
|
5 | 5 | ## ✨ Features |
6 | 6 |
|
7 | 7 | ### 🎯 Core Features |
8 | | -- **Quick Alias Generation**: Generate Gmail aliases with custom tags instantly |
| 8 | +- **Random Alias Generator**: Generate secure random aliases with multiple format options |
| 9 | + - Private Mail format (e.g., `private-mail-q2ga`) |
| 10 | + - Alphanumeric (e.g., `abc123xy`) |
| 11 | + - Random Words (e.g., `happy-fox-42`) |
| 12 | + - Timestamp-based (e.g., `lk9x2m3n`) |
| 13 | +- **Custom Tags**: Create aliases with your own custom tags |
| 14 | +- **Gmail Tricks**: Quick access to Gmail filtering and management tricks |
9 | 15 | - **Built-in Presets**: Shopping, Work, Test, Social, Finance, Travel |
10 | | -- **Custom Presets**: Create and manage unlimited custom preset tags |
11 | | -- **Favorites**: Save frequently used aliases with custom labels for quick access |
12 | | -- **Recent History**: View, search, and manage recent generated aliases |
| 16 | +- **Custom Presets**: Create and manage unlimited preset tags with context menu integration |
| 17 | +- **Favorites System**: Star frequently used aliases for instant access |
| 18 | +- **Recent Aliases**: View, search, filter, and manage alias history with pagination |
13 | 19 | - **Multi-Account Support**: Switch between multiple Gmail accounts seamlessly |
14 | 20 | - **Statistics Dashboard**: Track usage with detailed analytics and insights |
| 21 | +- **Badge Counter**: Display alias count on extension icon (Total, Today, Week, or All-Time) |
15 | 22 |
|
16 | | -### Settings & Customization |
| 23 | +### 🎨 UI/UX Features |
| 24 | +- **Modern Design**: Clean, gradient-based interface with card layouts |
| 25 | +- **Tabbed Interface**: Organized main view with Random, Custom, and Gmail Tricks tabs |
| 26 | +- **Pagination**: Navigate through large alias histories (5-50 items per page) |
| 27 | +- **Search & Filter**: Real-time search and tag-based filtering |
| 28 | +- **View Modes**: Switch between Recent and Favorites views |
| 29 | +- **Responsive**: Optimized for 360px extension popup |
| 30 | +- **Context Menu**: Right-click integration for quick alias generation on any editable field |
| 31 | + |
| 32 | +### ⚙️ Settings & Customization |
17 | 33 |
|
18 | 34 | #### General Settings |
19 | | -- **History Limit**: Choose how many recent aliases to keep (3-50) |
20 | | -- **Theme**: Light mode (Dark mode coming soon) |
21 | | -- **Auto-save**: Automatically save generated aliases to history |
| 35 | +- **Badge Counter**: Choose what to display on extension icon |
| 36 | + - None (Hidden) |
| 37 | + - Total in History |
| 38 | + - Total Generated (All Time) |
| 39 | + - Created Today |
| 40 | + - This Week |
| 41 | +- **Random Format**: Select default format for random alias generation |
| 42 | +- **Auto-save Limit**: Set history size (20-500 aliases) |
| 43 | +- **Theme**: Light mode (Dark mode coming in next update) |
22 | 44 | - **Show Notifications**: Toggle copy confirmation messages |
23 | 45 |
|
| 46 | +#### Account Management |
| 47 | +- **Multi-Account**: Add, edit, delete, and switch between Gmail accounts |
| 48 | +- **Account Labels**: Organize accounts with custom labels (Work, Personal, etc.) |
| 49 | +- **Data Isolation**: Each account has separate history, stats, and favorites |
| 50 | +- **Quick Add**: Add accounts directly from Settings with auto-complete |
| 51 | +- **Email Migration**: Change account email while preserving all data |
| 52 | + |
24 | 53 | #### Custom Presets |
25 | | -- Add unlimited custom preset buttons |
26 | | -- Each preset has a label and tag |
27 | | -- Appears separately from default presets with purple styling |
28 | | -- Easy add/remove functionality |
29 | | - |
30 | | -#### Favorites |
31 | | -- Save your most-used aliases with custom labels |
32 | | -- Quick one-click copy access |
33 | | -- Star icon for easy identification |
34 | | -- Manage directly from the main popup |
35 | | - |
36 | | -#### Statistics |
37 | | -- **Total Generated**: Track all aliases created |
38 | | -- **Created Today**: Daily usage counter |
39 | | -- **Created This Week**: Weekly tracking |
40 | | -- **Most Used Tag**: See your most popular tag |
41 | | - |
42 | | -#### Advanced Features |
43 | | -- **Export Settings**: Download all settings as JSON |
44 | | -- **Import Settings**: Restore settings from backup |
45 | | -- **Reset Settings**: Restore all defaults |
46 | | -- **Clear History**: Remove all recent aliases |
47 | | -- **Search & Filter**: Search through recent aliases |
48 | | - |
49 | | -### Keyboard Shortcuts |
50 | | -- `Enter`: Generate alias (when in custom tag input) |
51 | | -- `Ctrl/Cmd + K`: Open settings |
52 | | -- `Esc`: Close settings |
| 54 | +- Add unlimited custom preset tags |
| 55 | +- Synced with context menu automatically |
| 56 | +- Dynamic creation and deletion |
| 57 | +- Display with colored badges |
| 58 | + |
| 59 | +#### Data Management |
| 60 | +- **Export Settings**: Download all settings as JSON backup |
| 61 | +- **Import Settings**: Restore settings from backup file |
| 62 | +- **Clear History**: Remove all recent aliases for active account |
| 63 | +- **Reset Settings**: Restore all defaults with confirmation |
53 | 64 |
|
54 | 65 | ## 🛠 Tech Stack |
55 | 66 |
|
@@ -179,81 +190,108 @@ yarn zip |
179 | 190 | - `storage`: Save settings and history |
180 | 191 | - `clipboardWrite`: Copy aliases to clipboard |
181 | 192 |
|
182 | | -## 📂 Project Structure |
| 193 | +## � Project Structure |
183 | 194 |
|
184 | 195 | ``` |
185 | 196 | gmail-alias-toolkit/ |
186 | 197 | ├── entrypoints/ |
187 | | -│ ├── background.ts # Background service worker |
| 198 | +│ ├── background.ts # Service worker (context menu, badge) |
188 | 199 | │ ├── content.ts # Content script |
189 | 200 | │ └── popup/ |
190 | | -│ ├── App.tsx # Main app component |
| 201 | +│ ├── App.tsx # Main popup component |
191 | 202 | │ ├── main.tsx # React entry point |
192 | | -│ ├── index.html # Popup HTML |
193 | 203 | │ └── components/ |
194 | | -│ ├── Settings.tsx # Settings modal |
195 | | -│ ├── Statistics.tsx # Usage statistics |
196 | | -│ ├── Favorites.tsx # Favorites management |
197 | | -│ ├── Button.tsx # Reusable button |
198 | | -│ ├── Input.tsx # Reusable input |
199 | | -│ ├── Toggle.tsx # Toggle switch |
200 | | -│ └── KeyboardShortcuts.tsx |
| 204 | +│ ├── Button.tsx |
| 205 | +│ ├── Favorites.tsx |
| 206 | +│ ├── GmailTricks.tsx |
| 207 | +│ ├── Input.tsx |
| 208 | +│ ├── KeyboardShortcuts.tsx |
| 209 | +│ ├── Settings.tsx |
| 210 | +│ ├── Statistics.tsx |
| 211 | +│ ├── Toggle.tsx |
| 212 | +│ └── WelcomeScreen.tsx |
201 | 213 | ├── public/ |
202 | 214 | │ └── icon/ # Extension icons |
| 215 | +├── assets/ # Static assets |
203 | 216 | ├── package.json |
204 | 217 | ├── wxt.config.ts # WXT configuration |
205 | | -├── tailwind.config.ts # Tailwind configuration |
206 | | -├── tsconfig.json # TypeScript configuration |
207 | | -└── README.md |
| 218 | +├── tsconfig.json # TypeScript config |
| 219 | +└── tailwind.config.ts # Tailwind CSS config |
208 | 220 | ``` |
209 | 221 |
|
210 | | -## 🤝 Contributing |
| 222 | +## 🔑 Key Components |
211 | 223 |
|
212 | | -Contributions are welcome! Here's how: |
| 224 | +### App.tsx |
| 225 | +- Main popup interface |
| 226 | +- State management for accounts, history, favorites |
| 227 | +- Pagination and filtering logic |
| 228 | +- Account switching functionality |
213 | 229 |
|
214 | | -1. **Fork the repository** |
215 | | -2. **Create a feature branch**: `git checkout -b feature/amazing-feature` |
216 | | -3. **Make your changes** |
217 | | -4. **Test thoroughly**: `yarn dev` and test in browser |
218 | | -5. **Commit**: `git commit -m 'Add amazing feature'` |
219 | | -6. **Push**: `git push origin feature/amazing-feature` |
220 | | -7. **Open a Pull Request** |
| 230 | +### background.ts |
| 231 | +- Context menu creation and handling |
| 232 | +- Badge counter updates |
| 233 | +- Storage change listeners |
| 234 | +- Dynamic menu synchronization with presets |
| 235 | + |
| 236 | +### Settings.tsx |
| 237 | +- Comprehensive settings interface |
| 238 | +- Account management (add/edit/delete) |
| 239 | +- Custom preset management |
| 240 | +- Data import/export |
| 241 | +- Version display from manifest |
| 242 | + |
| 243 | +### Statistics.tsx |
| 244 | +- Usage analytics dashboard |
| 245 | +- Tag-based statistics (excludes 'unknown') |
| 246 | +- Time-based counters (today, week, all-time) |
| 247 | + |
| 248 | +## 🤝 Contributing |
221 | 249 |
|
222 | | -### Development Guidelines |
223 | | -- Follow existing code style (TypeScript + React hooks) |
224 | | -- Use Tailwind for styling (no custom CSS unless necessary) |
225 | | -- Add comments for complex logic |
226 | | -- Test on Chrome and Firefox if possible |
227 | | -- Update README if adding new features |
| 250 | +Contributions are welcome! Please follow these guidelines: |
228 | 251 |
|
229 | | -## ⭐ Show Your Support |
| 252 | +1. Fork the repository |
| 253 | +2. Create a feature branch: `git checkout -b feature/your-feature` |
| 254 | +3. Commit your changes: `git commit -m 'Add some feature'` |
| 255 | +4. Push to the branch: `git push origin feature/your-feature` |
| 256 | +5. Submit a pull request |
230 | 257 |
|
231 | | -If you find this extension useful: |
232 | | -- ⭐ Star the repository |
233 | | -- 🐦 Share on social media |
234 | | -- 🔗 Link from your blog/website |
235 | | -- 💬 Leave a review (when published on Chrome Web Store) |
| 258 | +## 📄 License |
236 | 259 |
|
237 | | -## 📝 License |
| 260 | +MIT License - see [LICENSE.md](LICENSE.md) for details |
238 | 261 |
|
239 | | -MIT License © 2025 |
| 262 | +## 🐛 Support |
240 | 263 |
|
241 | | -Permission is hereby granted, free of charge, to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of this software. |
| 264 | +- **Issues**: [GitHub Issues](https://github.com/yourusername/gmail-alias-toolkit/issues) |
| 265 | +- **Email**: dev@eplus.dev |
242 | 266 |
|
243 | | -See [LICENSE.md](LICENSE.md) for full details. |
| 267 | +## 📝 Changelog |
244 | 268 |
|
245 | | -## 📧 Support & Contact |
| 269 | +### Version 1.1.0 |
| 270 | +- ✨ Added badge counter with 5 display options (none/total/all-time/today/week) |
| 271 | +- 🎨 Complete Settings UI redesign with categorized card sections |
| 272 | +- ➕ Add Account form directly in Settings tab |
| 273 | +- 📊 Added "Total Generated (All Time)" statistics option |
| 274 | +- 📄 Pagination system with configurable items per page (5-50) |
| 275 | +- 🔄 Merged Favorites into Recent Aliases with tabbed interface |
| 276 | +- 🎯 Expanded auto-save limit range (20-500) |
| 277 | +- 💬 Email text wrapping fix (break-all for full visibility) |
| 278 | +- 📱 Version display in Settings footer from manifest |
| 279 | +- 🐛 Fixed duplicate state declarations bug |
| 280 | +- 🔧 Auto-sync version from package.json to manifest |
246 | 281 |
|
247 | | -- 🐛 **Bug Reports**: Create an issue on GitHub |
248 | | -- 💡 **Feature Requests**: Open a discussion or issue |
249 | | -- ❓ **Questions**: Check this README first, then open an issue |
250 | | -- 📧 **Email**: dev@eplus.dev |
251 | | -- 🌐 **Website**: https://eplus.dev |
| 282 | +### Version 1.0.0 |
| 283 | +- 🎉 Initial release |
| 284 | +- 🚀 Random alias generator with multiple formats |
| 285 | +- 📌 Built-in and custom presets |
| 286 | +- ⭐ Favorites system |
| 287 | +- 📊 Statistics dashboard |
| 288 | +- 🔄 Multi-account support |
| 289 | +- 🎨 Modern UI with Tailwind CSS |
252 | 290 |
|
253 | 291 | --- |
254 | 292 |
|
255 | | -**Built with ❤️ by developers, for developers** |
| 293 | +Made with ❤️ for Gmail power users |
256 | 294 |
|
257 | | -🛠️ Stack: WXT + React 19 + TypeScript + Tailwind CSS |
| 295 | +🛠️ Built with: WXT + React 19 + TypeScript + Tailwind CSS |
258 | 296 |
|
259 | | -📦 Version: 1.0.0 | 📅 Last Updated: December 2025 |
| 297 | +📦 Version: 1.1.0 | 📅 Last Updated: January 2025 |
0 commit comments