https://github.com/alejandroppir/clipboard-sync
https://github.com/alejandroppir/clipboard-sync
Last synced: about 2 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/alejandroppir/clipboard-sync
- Owner: alejandroppir
- Created: 2025-05-16T11:51:29.000Z (about 1 year ago)
- Default Branch: main
- Last Pushed: 2026-05-05T23:45:20.000Z (about 2 months ago)
- Last Synced: 2026-05-06T01:21:44.636Z (about 2 months ago)
- Language: TypeScript
- Size: 79.4 MB
- Stars: 0
- Watchers: 1
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Clipboard Sync
Sincronizador de portapapeles para Windows que mantiene el portapapeles sincronizado entre máquinas usando Firebase Firestore como backend en tiempo real.
Construido con **Electron + TypeScript**. Se distribuye como un único ejecutable portable (`ClipboardSync.exe`), sin instalación.
---
## Cómo funciona
Al arrancar, la aplicación:
1. Se minimiza en la **bandeja del sistema** (system tray)
2. Abre la ventana de configuración automáticamente
3. Si no hay usuario configurado, muestra el diálogo para introducir el `userId` (email)
4. Una vez configurado, inicia la sincronización con Firebase Firestore en tiempo real
Cualquier texto copiado al portapapeles se sube a Firestore. Si otra máquina con el mismo `userId` copia algo, se descarga y se pega en el portapapeles local.
---
## Interfaz
La ventana de configuración muestra:
- **Barra de estado** — indicador visual (verde = activo, gris = detenido, rojo = error) y el `userId` actual
- **Log en tiempo real** — registro de operaciones del sync (subidas, bajadas, errores)
- **Botones de acción**:
- `Cerrar aplicación` — termina el proceso completamente
- `Minimizar a la barra de tareas` — oculta la ventana; la app sigue corriendo en el tray
- `Detener` — pausa la sincronización sin cerrar la app
- `Reiniciar` — reinicia la sincronización (útil tras cambiar el userId)
- **Botón Cambiar** — permite cambiar el `userId` en cualquier momento
Para volver a abrir la ventana desde el tray: **clic o doble clic** sobre el icono, o clic derecho → _Abrir configuración_.
---
## Estructura del repositorio
```
clipboard-sync-repo/
├── src/
│ ├── main/
│ │ ├── main.ts # Punto de entrada Electron (single-instance lock, tray, IPC)
│ │ ├── config.ts # Lectura/escritura de config.json en %LOCALAPPDATA%
│ │ ├── sync.ts # Motor de sincronización Firebase + clipboard
│ │ ├── tray.ts # Icono y menú de la bandeja del sistema
│ │ ├── window.ts # BrowserWindow + handlers IPC
│ │ └── updater.ts # Auto-actualización con electron-updater
│ ├── preload/
│ │ └── preload.ts # Bridge seguro entre main y renderer (contextBridge)
│ └── renderer/
│ ├── settings.html # Interfaz de configuración
│ ├── settings.css # Estilos dark mode
│ └── renderer.ts # Lógica del renderer
├── assets/
│ ├── logo.svg # Fuente del icono
│ └── logo.ico # Icono generado (usado por Electron y el .exe)
├── dist/ # Salida de compilación TypeScript (ignorada en git)
├── dist-release/ # Salida de empaquetado electron-builder (ignorada en git)
├── tsconfig.json # Base TypeScript
├── tsconfig.main.json # Compilación main + preload (CommonJS)
├── tsconfig.renderer.json # Compilación renderer (ESNext)
├── electron-builder.yml # Configuración de empaquetado
└── package.json
```
---
## Desarrollo local
### Requisitos
- Node.js 24+
- `npm install`
### Scripts disponibles
| Script | Descripción |
| ----------------------- | ---------------------------------------------------------------------------- |
| `npm run dev` | Compila TypeScript y lanza la app con Electron |
| `npm run build` | Solo compila TypeScript → `dist/` |
| `npm run package` | Compila + empaqueta → `dist-release/ClipboardSync.exe` (portable) |
| `npm run generate-icon` | Convierte `assets/logo.svg` → `assets/logo.ico` (ejecutar al cambiar el SVG) |
### Desarrollo diario
```powershell
npm run dev
```
### Primera ejecución sin config
Si `%LOCALAPPDATA%\clipboard-sync\config.json` no existe, la app abre el diálogo de userId automáticamente al arrancar.
Para simular una primera ejecución limpia:
```powershell
Remove-Item "$env:LOCALAPPDATA\clipboard-sync" -Recurse -Force
npm run dev
```
---
## Empaquetado local
```powershell
npm run package
```
Genera `dist-release/ClipboardSync.exe`. Requiere **Modo de desarrollador de Windows** activado (Configuración → Sistema → Para desarrolladores).
---
## Release / CI
El workflow `.github/workflows/release.yml` se dispara manualmente (`workflow_dispatch`) con un único parámetro:
- `version`: número de versión (ej. `1.2.3`, sin `v`)
El workflow:
1. Hace `npm version $version` y crea el tag en git
2. Compila TypeScript
3. Empaqueta con `electron-builder --win portable --publish always`
4. Publica `ClipboardSync.exe` en GitHub Releases automáticamente
---
## Configuración
El archivo de configuración se guarda en:
```
%LOCALAPPDATA%\clipboard-sync\config.json
```
Contenido:
```json
{"userId": "email@dominio.com"}
```
El `userId` debe coincidir entre todas las máquinas que quieran compartir portapapeles. Solo se usa como clave de documento en Firestore — no hay autenticación Firebase.
---
## Auto-actualización
Cuando la app está empaquetada (`app.isPackaged`), comprueba automáticamente si hay una nueva versión disponible en GitHub Releases al arrancar. Si la hay, descarga e instala la actualización en segundo plano y notifica al usuario.
Al arrancar, la aplicación:
1. Se minimiza en la **bandeja del sistema** (system tray)
2. Abre la ventana de configuración automáticamente
3. Si no hay usuario configurado, muestra el diálogo para introducir el `userId` (email)
4. Una vez configurado, inicia la sincronización con Firebase Firestore en tiempo real
Cualquier texto copiado al portapapeles se sube a Firestore. Si otra máquina con el mismo `userId` copia algo, se descarga y se pega en el portapapeles local.
---
## Interfaz
La ventana de configuración muestra:
- **Barra de estado** — indicador visual (verde = activo, gris = detenido, rojo = error) y el `userId` actual
- **Log en tiempo real** — registro de operaciones del sync (subidas, bajadas, errores)
- **Botones de acción**:
- `Cerrar aplicación` — termina el proceso completamente
- `Minimizar a la barra de tareas` — oculta la ventana; la app sigue corriendo en el tray
- `Detener` — pausa la sincronización sin cerrar la app
- `Reiniciar` — reinicia la sincronización (útil tras cambiar el userId)
- **Botón Cambiar** — permite cambiar el `userId` en cualquier momento
Para volver a abrir la ventana desde el tray: **clic o doble clic** sobre el icono, o clic derecho → _Abrir configuración_.
---
## Estructura del repositorio
```
clipboard-sync-repo/
├── src/
│ ├── main/
│ │ ├── main.ts # Punto de entrada Electron (single-instance lock, tray, IPC)
│ │ ├── config.ts # Lectura/escritura de config.json en %LOCALAPPDATA%
│ │ ├── sync.ts # Motor de sincronización Firebase + clipboard
│ │ ├── tray.ts # Icono y menú de la bandeja del sistema
│ │ ├── window.ts # BrowserWindow + handlers IPC
│ │ └── updater.ts # Auto-actualización con electron-updater
│ ├── preload/
│ │ └── preload.ts # Bridge seguro entre main y renderer (contextBridge)
│ └── renderer/
│ ├── settings.html # Interfaz de configuración
│ ├── settings.css # Estilos dark mode
│ └── renderer.ts # Lógica del renderer
├── assets/
│ ├── logo.svg # Fuente del icono
│ └── logo.ico # Icono generado (usado por Electron y el .exe)
├── dist/ # Salida de compilación TypeScript (ignorada en git)
├── dist-release/ # Salida de empaquetado electron-builder (ignorada en git)
├── tsconfig.json # Base TypeScript
├── tsconfig.main.json # Compilación main + preload (CommonJS)
├── tsconfig.renderer.json # Compilación renderer (ESNext)
├── electron-builder.yml # Configuración de empaquetado
└── package.json
```
---
## Desarrollo local
### Requisitos
- Node.js 24+
- `npm install`
### Scripts disponibles
| Script | Descripción |
| ----------------------- | ------------------------------------------------------------------------------ |
| `npm run dev` | Compila TypeScript y lanza la app con Electron |
| `npm run build` | Solo compila TypeScript → `dist/` |
| `npm run package` | Compila + empaqueta → `dist-release/ClipboardSync.exe` (portable) |
| `npm run generate-icon` | Convierte `assets/logo.svg` → `assets/logo.ico` (ejecutar al cambiar el SVG) |
### Desarrollo diario
```powershell
npm run dev
```
### Primera ejecución sin config
Si `%LOCALAPPDATA%\clipboard-sync\config.json` no existe, la app abre el diálogo de userId automáticamente al arrancar.
Para simular una primera ejecución limpia:
```powershell
Remove-Item "$env:LOCALAPPDATA\clipboard-sync" -Recurse -Force
npm run dev
```
---
## Empaquetado local
```powershell
npm run package
```
Genera `dist-release/ClipboardSync.exe`. Requiere **Modo de desarrollador de Windows** activado (Configuración → Sistema → Para desarrolladores).
---
## Release / CI
El workflow `.github/workflows/release.yml` se dispara manualmente (`workflow_dispatch`) con un único parámetro:
- `version`: número de versión (ej. `1.2.3`, sin `v`)
El workflow:
1. Hace `npm version $version` y crea el tag en git
2. Compila TypeScript
3. Empaqueta con `electron-builder --win portable --publish always`
4. Publica `ClipboardSync.exe` en GitHub Releases automáticamente
---
## Configuración
El archivo de configuración se guarda en:
```
%LOCALAPPDATA%\clipboard-sync\config.json
```
Contenido:
```json
{"userId": "email@dominio.com"}
```
El `userId` debe coincidir entre todas las máquinas que quieran compartir portapapeles. Solo se usa como clave de documento en Firestore — no hay autenticación Firebase.
---
## Auto-actualización
Cuando la app está empaquetada (`app.isPackaged`), comprueba automáticamente si hay una nueva versión disponible en GitHub Releases al arrancar. Si la hay, descarga e instala la actualización en segundo plano y notifica al usuario.