👥 Athenea - Dashboard Desktop App

Plantilla pública lista para usar como base de app de escritorio con Electron + Preact + Vite, usando electron-vite para un flujo de desarrollo integrado.

Creado por Ignacio Basilio (Ignadev).

⚡ Inicio Rápido

npm create athenea-app@latest

O con nombre directo:

npm create athenea-app@latest mi-proyecto
cd mi-proyecto
npm run dev

🛠️ Stack Tecnológico

Core

🧬 Preact - Alternativa ligera y rápida a React (3KB)
⚡ Vite - Build tool ultrarrápido con HMR instantáneo
🖥️ Electron - Framework para apps de escritorio multiplataforma
🔧 electron-vite - Integración Vite + Electron (HMR, build unificado)
📦 electron-builder - Empaquetado y distribución

Gestión de Estado y Datos

🐻 Zustand - State management minimalista (1KB)
🌐 Ky - HTTP client ligero
🔐 safeStorage (Electron) - Almacenamiento seguro de credenciales
🎯 Zod - Validación de schemas TypeScript-first
🔑 jwt-decode - Decodificación de tokens JWT
⚡ @preact/signals - Estado reactivo
📊 @tanstack/react-table - Tablas flexibles
🍬 SweetAlert2 - Alertas modales

Utilidades

📅 Day.js - Manipulación de fechas (2KB)
🖨️ pdf-to-printer - Impresión de PDFs
📝 electron-log - Sistema de logging
🔄 electron-updater - Auto-actualizaciones (configurable)

Desarrollo

🎨 Tailwind CSS - Framework CSS utility-first
📘 TypeScript - Listo para tipado estático (sin fuentes .ts todavía; ver nota en "Calidad de Código")
✅ Vitest - Framework de testing ultrarrápido
🎭 @testing-library/preact - Testing de componentes
🧹 ESLint + Prettier - Linting y formateo

🚀 Scripts Disponibles

Desarrollo

# Desarrollo completo (Electron + Vite con HMR)
npm run dev

# En Linux, si tenés problemas de sandbox:
npm run dev:linux

Build y Distribución

# Compilar todo (main + preload + renderer)
npm run build

# Vista previa del build
npm run preview

# Generar instalador completo (Windows/Linux)
npm run dist

# Targets específicos
npm run dist:win
npm run dist:linux

# Generar solo carpeta empaquetada (sin instalador)
npm run pack

Calidad de Código

# Análisis de código con ESLint
npm run lint

# Formatear código con Prettier
npm run format

# Verificación de tipos TypeScript
npm run typecheck

# Ejecutar tests
npm run test

Nota sobre typecheck: el proyecto es TypeScript-ready (tsconfig.json con allowJs), pero hoy no hay fuentes .ts/.tsx y checkJs está desactivado, por lo que tsc --noEmit no reporta errores reales todavía. El gate se activa solo cuando se agregan archivos .ts/.tsx o se habilita checkJs.

🧭 Guía Operativa: AGENTS + Skills

Este repositorio usa una capa de reglas operativas para mantener cambios consistentes entre app desktop, renderer y CLI.

Cómo funciona AGENTS

AGENTS.md (raíz) define reglas globales del proyecto.
Cada zona relevante tiene su propio AGENTS.md (src/, src/main/, src/preload/, src/renderer/, create-athenea-app/, create-athenea-app/template/).
Regla de precedencia: siempre manda el AGENTS.md más cercano al archivo editado.

Skills disponibles y para qué sirve cada una

skills/electron-ipc-contract/SKILL.md: asegura consistencia y seguridad del contrato IPC entre src/main/ y src/preload/.
skills/renderer-preact-routes/SKILL.md: guía cambios en rutas/componentes del renderer Preact manteniendo estructura y patrones de UI.
skills/create-athenea-template-sync/SKILL.md: obliga sincronía entre create-athenea-app/bin/ y create-athenea-app/template/ para que el scaffolding no se rompa.
skills/desktop-quality-gates/SKILL.md: define gates mínimos de calidad antes de cerrar cambios (lint, typecheck/build y coherencia documental).

Política de versionado limpio

Se versiona solo código y configuración fuente.
Se ignoran salidas generadas de build/distribución (out/, release/, dist/, dist-ssr/).
Se ignoran dependencias/caches de tooling (node_modules/, .npm/, .pnpm-store/, .vite/, .cache/, .eslintcache, coverage/, *.tsbuildinfo).

💻 Instalación y Configuración

Requisitos Previos

Node.js v22.12.0 o superior (requerido). Usamos Node 22.12+ para cumplir el mínimo de Electron 43 y evitar rebuilds inconsistentes de módulos nativos. Incluimos .nvmrc y .node-version para fijar la base soportada.
npm v8.0.0 o superior
Git (recomendado)

Instalación

# 1. Clonar el repositorio
git clone https://github.com/ignadev/Athenea-Desktop.git
cd Athenea-Desktop

# 2. Instalar dependencias
npm install

🧪 Desarrollo Local

Modo Desarrollo Completo

Para desarrollo con hot-reload en Electron:

npm run dev

Esto iniciará:

Build de main y preload
Vite dev server para el renderer
Electron con HMR automático

Nota Linux: Si tenés errores de sandbox, usá npm run dev:linux que agrega --no-sandbox.

📦 Build para Producción

1. Compilar y Probar

# Compilar todo
npm run build

# Preview
npm run preview

2. Generar Instalador

npm run dist

Esto generará instaladores en la carpeta release/ según tu plataforma:

Windows: .exe (NSIS installer)
Linux: .AppImage, .deb

🏗️ Estructura del Proyecto

athenea/
├── AGENTS.md              # Reglas globales del repo
├── skills/                # Skills operativas por dominio
│   ├── electron-ipc-contract/
│   ├── renderer-preact-routes/
│   ├── create-athenea-template-sync/
│   └── desktop-quality-gates/
├── src/
│   ├── AGENTS.md          # Reglas de app desktop
│   ├── main/             # Proceso principal de Electron
│   │   ├── AGENTS.md
│   │   └── index.js      # Entry point, manejo de ventanas, IPC
│   ├── preload/          # Scripts de preload
│   │   ├── AGENTS.md
│   │   └── index.js      # Bridge seguro (window.electronAPI)
│   └── renderer/         # UI (Preact)
│       ├── AGENTS.md
│       ├── index.html    # HTML principal
│       ├── public/       # Assets estáticos
│       └── src/          # Código fuente del renderer
│           ├── components/
│           ├── routes/
│           └── main.jsx
├── create-athenea-app/    # CLI para scaffolding (publicado en npm)
│   ├── AGENTS.md
│   ├── bin/
│   └── template/
│       └── AGENTS.md
├── resources/            # Assets para electron-builder (iconos, BMP)
├── out/                  # Output del build (generado)
├── release/              # Instaladores generados
├── electron.vite.config.js
└── package.json

🔒 Seguridad

Credenciales: Cifradas con safeStorage (Electron) usando el almacén de claves del sistema operativo
Context isolation: Habilitado para proteger el proceso renderer
Preload script: Expone solo APIs necesarias de forma controlada (window.electronAPI)
Code signing: Configurado para Windows (ajustar según necesidad)

🚢 Distribución y Updates

El build coloca los artefactos en release/.
electron-updater está disponible; configurá publish en package.json si vas a usar updates.

🎨 Branding (nombre e imágenes)

Este repo está pensado como plantilla. Por defecto dejamos todo en genérico para que puedas "re-brandear" sin buscar strings sueltos.

Nombre de la app (producción)

Instalador / app empaquetada: package.json → build.productName
Identificador (AppUserModelId / bundle id): package.json → build.appId

Títulos visibles (runtime)

Ventanas de Electron: src/main/index.js → BrowserWindow({ title: ... })
HTML (cuando corre como web/renderer): src/renderer/index.html → <title>

Recursos del instalador (electron-builder / NSIS)

Estos archivos se incluyen como placeholders blancos para que el build no falle si todavía no tenés diseño:

Ícono: resources/build.ico
Sidebar instalador: resources/installer-sidebar.bmp
Header instalador: resources/installer-header.bmp

Reemplazalos por tus assets finales manteniendo los mismos nombres/rutas.

Favicon del renderer (Vite)

src/renderer/index.html referencia /vite.svg

📦 Recursos empaquetados

Por defecto no se incluye ningún recurso extra.
Si necesitás sumar binarios o archivos externos, configuralos en build.extraResources en package.json.
Mantené esos recursos fuera del repositorio si son generados o sensibles y copiá las versiones necesarias antes de npm run dist o npm run pack.

🧰 Troubleshooting

Error al instalar dependencias

# Limpiar cache e instalar nuevamente
npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Error con módulos nativos

# Reinstalar dependencias nativas de Electron
npm run postinstall

Error en Linux (sandbox)

# Usar el script con --no-sandbox
npm run dev:linux

📚 Recursos Útiles

🤝 Contribuir

¡Las contribuciones son bienvenidas! Por favor:

Fork el proyecto
Creá tu feature branch (git checkout -b feature/AmazingFeature)
Commit tus cambios (git commit -m 'Add some AmazingFeature')
Push al branch (git push origin feature/AmazingFeature)
Abrí un Pull Request

📄 Licencia

Repositorio público pensado como plantilla. Definí y agregá tu LICENSE antes de distribuir una app basada en esto.

👨‍💻 Soporte

¿Tenés dudas o problemas?

🐛 Reportá bugs en Issues
💬 Discusiones en Discussions
📧 Email: ignacio.n.basilio.b@gmail.com

Name		Name	Last commit message	Last commit date
create-athenea-app		create-athenea-app
resources		resources
scripts		scripts
skills		skills
src		src
.gitignore		.gitignore
.node-version		.node-version
.nvmrc		.nvmrc
AGENTS.md		AGENTS.md
README.md		README.md
electron.vite.config.js		electron.vite.config.js
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
postcss.config.js		postcss.config.js
tailwind.config.js		tailwind.config.js
tsconfig.json		tsconfig.json
vitest.config.js		vitest.config.js

Latest commit

History

Folders and files

Repository files navigation

👥 Athenea - Dashboard Desktop App

⚡ Inicio Rápido

🛠️ Stack Tecnológico

Core

Gestión de Estado y Datos

Utilidades

Desarrollo

🚀 Scripts Disponibles

Desarrollo

Build y Distribución

Calidad de Código

🧭 Guía Operativa: AGENTS + Skills

Cómo funciona AGENTS

Skills disponibles y para qué sirve cada una

Política de versionado limpio

💻 Instalación y Configuración

Requisitos Previos

Instalación

🧪 Desarrollo Local

Modo Desarrollo Completo

📦 Build para Producción

1. Compilar y Probar

2. Generar Instalador

🏗️ Estructura del Proyecto

🔒 Seguridad

🚢 Distribución y Updates

🎨 Branding (nombre e imágenes)

Nombre de la app (producción)

Títulos visibles (runtime)

Recursos del instalador (electron-builder / NSIS)

Favicon del renderer (Vite)

📦 Recursos empaquetados

🧰 Troubleshooting

Error al instalar dependencias

Error con módulos nativos

Error en Linux (sandbox)

📚 Recursos Útiles

🤝 Contribuir

📄 Licencia

👨‍💻 Soporte

About

Resources

Stars

Watchers

Forks

Releases

Packages

Contributors

Languages