netbird/client/ui-electron

NetBird Electron UI

A modern, beautiful Electron-based desktop UI for NetBird VPN built with React, TypeScript, and Tailwind CSS.

Features

• Modern Glass Design: Beautiful icy blue theme with glassmorphism effects
• System Tray Integration: Runs in background with system tray icon
• Real-time Status: Live connection status updates
• Network Management: Select and manage network routes
• Profile Management: Switch between multiple NetBird profiles
• Advanced Settings: Full configuration control
• Debug Tools: Create debug bundles for troubleshooting

Technology Stack

• Electron 28: Desktop application framework
• React 18: UI library
• TypeScript 5: Type-safe development
• Tailwind CSS: Utility-first styling
• Framer Motion: Smooth animations
• Zustand: State management
• gRPC: Daemon communication via @grpc/grpc-js
• Lucide React: Modern icon library

Prerequisites

• Node.js 18+ and npm
• NetBird daemon running (netbird service start)
• Linux with Unix domain socket support (or Windows with TCP)

Installation

cd /home/pascal/Git/Netbird/netbird/client/ui-electron
npm install

Development

Run in development mode with hot reload:

npm run dev

This starts:

1. Vite dev server on port 5173 (React app)
2. Electron main process

Building

Build for current platform

npm run build

Build for Linux

npm run build:linux

Generates AppImage and .deb packages in release/ directory.

Build for all platforms

npm run build:all

Project Structure

ui-electron/
├── electron/              # Electron main process
│   ├── main.ts           # Main process entry point
│   ├── preload.ts        # Preload script for IPC
│   └── grpc/
│       └── client.ts     # gRPC client for daemon communication
├── src/                  # React application
│   ├── App.tsx          # Main app component
│   ├── main.tsx         # React entry point
│   ├── index.css        # Global styles
│   ├── store/
│   │   └── useStore.ts  # Zustand state management
│   └── pages/           # Page components
│       ├── Dashboard.tsx
│       ├── Settings.tsx
│       ├── Networks.tsx
│       ├── Profiles.tsx
│       └── Debug.tsx
├── assets/              # Icons and images
├── package.json
├── tsconfig.json        # TypeScript config (renderer)
├── tsconfig.electron.json  # TypeScript config (main)
├── vite.config.ts       # Vite config
├── tailwind.config.js   # Tailwind CSS config
└── postcss.config.js    # PostCSS config

Design System

Colors

• Icy Blue: #a3d7e5 - Primary accent color
• Dark Background: #121218 - Main background
• Dark Card: #1c1c23 - Card backgrounds
• Text Light: #f8f8fc - Primary text
• Text Muted: #a0a0aa - Secondary text

Components

• Glass morphism cards with blur effects
• Smooth page transitions with Framer Motion
• Icy blue glow effects on active elements
• Custom scrollbars
• Modern toggle switches and checkboxes

gRPC Communication

The app communicates with the NetBird daemon via gRPC:

• Unix Socket (Linux/macOS): unix:///var/run/netbird.sock
• TCP (Windows): localhost:41731

All daemon operations are exposed through the Electron IPC bridge for security.

System Tray

The system tray provides quick access to:

• Connection status
• Connect/Disconnect
• Settings menu
• Networks
• Debug bundle creation
• Quit

Menu items update dynamically based on daemon state.

Development Notes

Hot Reload

Vite provides hot module replacement for the React app. Changes to Electron main process require restart.

Debugging

• React DevTools: Available in development mode
• Electron DevTools: Opens automatically in dev mode
• gRPC logging: Check console for daemon communication

Type Safety

Full TypeScript coverage with strict mode enabled. The preload script exposes typed APIs to the renderer process.

Customization

Theme

Edit tailwind.config.js to customize colors:

colors: {
  icy: {
    blue: '#a3d7e5',  // Change primary color
  },
}

Icons

System tray icons should be placed in assets/ directory:

• tray-icon-connected.png - Connected state
• tray-icon-disconnected.png - Disconnected state
• tray-icon-connecting.png - Connecting state
• tray-icon-error.png - Error state

Deployment

Linux

AppImage and .deb packages can be distributed directly. The app will:

1. Auto-launch on system startup (if configured)
2. Run in system tray
3. Connect to local NetBird daemon

Permissions

The app requires:

• Network access (for gRPC communication)
• File system access (for debug bundles)
• System tray access

Troubleshooting

Cannot connect to daemon

Ensure NetBird daemon is running:

systemctl status netbird
# or
netbird status

gRPC errors

Check daemon socket permissions:

ls -la /var/run/netbird.sock

Build errors

Clear node_modules and reinstall:

rm -rf node_modules package-lock.json
npm install

Contributing

This is a modern alternative UI for NetBird. Improvements welcome!

Code Style

• Use TypeScript strict mode
• Follow React hooks best practices
• Use Tailwind utility classes
• Implement smooth transitions with Framer Motion

License

Same as NetBird project (BSD 3-Clause).

Credits

• NetBird: github.com/netbirdio/netbird
• Design: Modern glass morphism with icy blue theme
• Icons: Lucide React

---

Note: This is a community-contributed modern UI alternative. The official NetBird UI is built with Fyne (Go).