Skip to content

Commit 1ccd431

Browse files
author
Murat Akdeniz
committed
Initial commit: WhatsApp Desktop Linux v1.0.0
✨ Features: - Native WhatsApp Web desktop app for Linux - System tray integration with minimize/show/quit - Desktop notifications for unread messages - Keyboard shortcuts for conversation navigation - Auto-updater with GitHub releases integration - Sandbox-free AppImage distribution - Modern Electron with security best practices ⌨️ Keyboard Shortcuts: - Ctrl+Tab: Next conversation - Ctrl+Shift+Tab: Previous conversation - Ctrl+M: Mute/unmute chat 🔧 Built with Electron and electron-builder 📦 Distributed as AppImage for universal Linux compatibility
0 parents  commit 1ccd431

File tree

10 files changed

+5794
-0
lines changed

10 files changed

+5794
-0
lines changed

‎.gitignore‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Dependencies
2+
node_modules/
3+
npm-debug.log*
4+
yarn-debug.log*
5+
yarn-error.log*
6+
7+
# Build outputs
8+
dist/
9+
build/
10+
*.AppImage
11+
12+
# Environment variables
13+
.env
14+
.env.local
15+
.env.development.local
16+
.env.test.local
17+
.env.production.local
18+
19+
# IDE files
20+
.vscode/
21+
.idea/
22+
*.swp
23+
*.swo
24+
*~
25+
26+
# OS generated files
27+
.DS_Store
28+
.DS_Store?
29+
._*
30+
.Spotlight-V100
31+
.Trashes
32+
ehthumbs.db
33+
Thumbs.db
34+
35+
# Electron
36+
out/
37+
app/dist/
38+
39+
# Logs
40+
logs
41+
*.log
42+
43+
# Runtime data
44+
pids
45+
*.pid
46+
*.seed
47+
48+
# Coverage directory used by tools like istanbul
49+
coverage/
50+
51+
# Dependency directories
52+
jspm_packages/
53+
54+
# Optional npm cache directory
55+
.npm
56+
57+
# Optional eslint cache
58+
.eslintcache
59+
60+
# Temporary folders
61+
tmp/
62+
temp/
63+
64+
# Editor directories and files
65+
.vscode/
66+
!.vscode/extensions.json
67+
.idea/
68+
*.suo
69+
*.ntvs*
70+
*.njsproj
71+
*.sln
72+
*.sw?

‎CONTRIBUTING.md‎

Lines changed: 113 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,113 @@
1+
# Contributing to WhatsApp Desktop Linux
2+
3+
Thank you for your interest in contributing! 🎉
4+
5+
## 🚀 Getting Started
6+
7+
1. **Fork the repository** on GitHub
8+
2. **Clone your fork** locally:
9+
```bash
10+
git clone https://github.com/YOUR-USERNAME/whatsapp-desktop-linux.git
11+
cd whatsapp-desktop-linux
12+
```
13+
3. **Install dependencies**:
14+
```bash
15+
npm install
16+
```
17+
4. **Create a branch** for your changes:
18+
```bash
19+
git checkout -b feature/your-feature-name
20+
```
21+
22+
## 🛠️ Development
23+
24+
### Running in Development Mode
25+
```bash
26+
npm start
27+
```
28+
29+
### Building AppImage
30+
```bash
31+
npm run build-linux
32+
```
33+
34+
### Testing Changes
35+
- Test the app functionality thoroughly
36+
- Verify keyboard shortcuts work
37+
- Check system tray integration
38+
- Test on different Linux distributions if possible
39+
40+
## 📝 Guidelines
41+
42+
### Code Style
43+
- Follow existing code formatting
44+
- Use meaningful variable and function names
45+
- Add comments for complex logic
46+
- Keep functions focused and small
47+
48+
### Commit Messages
49+
- Use clear, descriptive commit messages
50+
- Start with a verb (Add, Fix, Update, Remove, etc.)
51+
- Reference issues when applicable
52+
53+
Example:
54+
```
55+
Add support for notification sound toggle
56+
57+
Fixes #42
58+
```
59+
60+
### Pull Request Process
61+
62+
1. **Update documentation** if you're adding features
63+
2. **Test thoroughly** - ensure no regressions
64+
3. **Update README.md** if needed
65+
4. **Create pull request** with:
66+
- Clear title and description
67+
- Reference any related issues
68+
- Screenshots/videos for UI changes
69+
70+
## 🐛 Bug Reports
71+
72+
When reporting bugs, please include:
73+
- Operating system and version
74+
- Electron version (from Help → About)
75+
- Steps to reproduce
76+
- Expected vs actual behavior
77+
- Screenshots if applicable
78+
- Console logs (if available)
79+
80+
## 💡 Feature Requests
81+
82+
For feature requests:
83+
- Check if similar request exists
84+
- Explain the use case
85+
- Describe the proposed solution
86+
- Consider if it fits the project scope
87+
88+
## 🔒 Security Issues
89+
90+
Please **DO NOT** create public issues for security vulnerabilities.
91+
Instead, email directly to: [email protected]
92+
93+
## 📄 License
94+
95+
By contributing, you agree that your contributions will be licensed under the MIT License.
96+
97+
## 🤝 Code of Conduct
98+
99+
- Be respectful and inclusive
100+
- Focus on constructive feedback
101+
- Help others learn and grow
102+
- Maintain a welcoming environment
103+
104+
## ❓ Questions?
105+
106+
Feel free to ask questions by:
107+
- Opening a discussion
108+
- Creating an issue with the "question" label
109+
- Reaching out to maintainers
110+
111+
---
112+
113+
Thank you for making WhatsApp Desktop Linux better! 🚀

‎LICENSE‎

Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
MIT License
2+
3+
Copyright (c) 2025 codeXpedite
4+
5+
Permission is hereby granted, free of charge, to any person obtaining a copy
6+
of this software and associated documentation files (the "Software"), to deal
7+
in the Software without restriction, including without limitation the rights
8+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9+
copies of the Software, and to permit persons to whom the Software is
10+
furnished to do so, subject to the following conditions:
11+
12+
The above copyright notice and this permission notice shall be included in all
13+
copies or substantial portions of the Software.
14+
15+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21+
SOFTWARE.

‎README.md‎

Lines changed: 176 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,176 @@
1+
# WhatsApp Desktop Linux
2+
3+
🚀 **Native WhatsApp Web desktop application for Linux** with system tray, notifications, keyboard shortcuts, and AppImage distribution. Built with Electron.
4+
5+
![WhatsApp Desktop Linux](https://img.shields.io/badge/Platform-Linux-blue)
6+
![License](https://img.shields.io/badge/License-MIT-green)
7+
![Electron](https://img.shields.io/badge/Built%20with-Electron-9feaf9)
8+
![AppImage](https://img.shields.io/badge/Distribution-AppImage-orange)
9+
10+
## ✨ Features
11+
12+
- 🌐 **WhatsApp Web Integration** - Full WhatsApp Web functionality in a native app
13+
- 🚫 **Sandbox-Free** - No more `--no-sandbox` flags required
14+
- 🔔 **System Notifications** - Desktop notifications for new messages
15+
- 🎛️ **System Tray** - Minimize to tray, quick access menu
16+
- ⌨️ **Keyboard Shortcuts** - Navigate conversations with ease
17+
- 🔄 **Auto-Updates** - Automatic update checking and notifications
18+
- 📦 **AppImage** - Single-file distribution, no installation needed
19+
- 🔒 **Modern Security** - Latest Electron with proper security policies
20+
21+
## 🎹 Keyboard Shortcuts
22+
23+
| Shortcut | Action |
24+
|----------|--------|
25+
| `Ctrl+Tab` | Switch to next conversation |
26+
| `Ctrl+Shift+Tab` | Switch to previous conversation |
27+
| `Ctrl+M` | Mute/unmute current chat |
28+
29+
## 📥 Download & Installation
30+
31+
### Method 1: Download AppImage (Recommended)
32+
1. Go to [Releases](../../releases)
33+
2. Download the latest `WhatsApp Web-X.X.X.AppImage`
34+
3. Make it executable: `chmod +x WhatsApp\ Web-*.AppImage`
35+
4. Run it: `./WhatsApp\ Web-*.AppImage`
36+
37+
### Method 2: Build from Source
38+
```bash
39+
# Clone the repository
40+
git clone https://github.com/codeXpedite/whatsapp-desktop-linux.git
41+
cd whatsapp-desktop-linux
42+
43+
# Install dependencies
44+
npm install
45+
46+
# Build AppImage
47+
npm run build-linux
48+
49+
# AppImage will be created in dist/ folder
50+
```
51+
52+
## 🚀 Usage
53+
54+
### First Run
55+
1. Launch the application
56+
2. Scan QR code with your phone's WhatsApp
57+
3. Start chatting!
58+
59+
### System Tray
60+
- **Left-click tray icon**: Show/hide window
61+
- **Right-click tray icon**: Context menu with options
62+
- **Close button**: Minimizes to tray (doesn't quit)
63+
64+
### Notifications
65+
- Automatic desktop notifications for unread messages
66+
- Only shows when app is not focused
67+
- Respects system notification settings
68+
69+
## 🛠️ Development
70+
71+
### Prerequisites
72+
- Node.js 16+
73+
- npm or yarn
74+
75+
### Setup
76+
```bash
77+
git clone https://github.com/codeXpedite/whatsapp-desktop-linux.git
78+
cd whatsapp-desktop-linux
79+
npm install
80+
```
81+
82+
### Scripts
83+
```bash
84+
npm start # Run in development mode
85+
npm run build # Build for current platform
86+
npm run build-linux # Build AppImage for Linux
87+
```
88+
89+
### Project Structure
90+
```
91+
whatsapp-desktop-linux/
92+
├── main.js # Main Electron process
93+
├── preload.js # Preload script
94+
├── package.json # Project configuration
95+
├── assets/ # Application icons
96+
├── scripts/ # Build scripts
97+
└── dist/ # Built AppImages
98+
```
99+
100+
## 🔧 Configuration
101+
102+
### Auto-Updates
103+
Auto-updates are enabled by default. The app checks for updates on startup and notifies you when updates are available.
104+
105+
To configure updates, modify the `publish` section in `package.json`:
106+
107+
```json
108+
{
109+
"publish": {
110+
"provider": "github",
111+
"owner": "codeXpedite",
112+
"repo": "whatsapp-desktop-linux"
113+
}
114+
}
115+
```
116+
117+
### Custom Settings
118+
The app stores settings in standard locations:
119+
- **Linux**: `~/.config/whatsapp-web-wrapper/`
120+
121+
## ❓ Troubleshooting
122+
123+
### Common Issues
124+
125+
**Q: App won't start / Sandbox errors**
126+
A: This has been fixed! The app automatically handles sandbox issues.
127+
128+
**Q: Notifications not working**
129+
A: Check your system notification permissions and ensure the app has notification access.
130+
131+
**Q: Keyboard shortcuts not working**
132+
A: Make sure the WhatsApp window has focus when using shortcuts.
133+
134+
**Q: System tray not visible**
135+
A: Ensure your desktop environment supports system tray icons.
136+
137+
### Debug Mode
138+
Run with environment variable for debugging:
139+
```bash
140+
DEBUG=1 ./WhatsApp\ Web-*.AppImage
141+
```
142+
143+
## 🤝 Contributing
144+
145+
Contributions are welcome! Please feel free to submit a Pull Request.
146+
147+
### Development Guidelines
148+
1. Fork the repository
149+
2. Create a feature branch
150+
3. Make your changes
151+
4. Test thoroughly
152+
5. Submit a pull request
153+
154+
## 📄 License
155+
156+
This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
157+
158+
## ⚠️ Disclaimer
159+
160+
This is an unofficial WhatsApp client. WhatsApp is a trademark of Meta Platforms, Inc. This project is not affiliated with or endorsed by Meta Platforms, Inc.
161+
162+
## 🙏 Acknowledgments
163+
164+
- Built with [Electron](https://electronjs.org/)
165+
- Inspired by various WhatsApp desktop clients
166+
- Community feedback and contributions
167+
168+
## 📞 Support
169+
170+
- 🐛 **Bug Reports**: [Create an issue](../../issues)
171+
- 💡 **Feature Requests**: [Create an issue](../../issues)
172+
- 💬 **Discussions**: [GitHub Discussions](../../discussions)
173+
174+
---
175+
176+
**Made with ❤️ for the Linux community**

‎assets/icon.png‎

4.21 KB
Loading

0 commit comments

Comments
 (0)