Miniapps monorepo

Monorepo para alojar múltiples miniapps PWA independientes en GitHub Pages usando un único repositorio.

Cada miniapp vive en apps/<slug> y se publica como una subruta estática del repositorio. El proyecto está diseñado para minimizar trabajo manual e incluye un launcher home, un generador de miniapps, validación estructural y un build agregador para GitHub Pages.

Ejemplos de URL finales:

• https://<usuario>.github.io/<repo>/
• https://<usuario>.github.io/<repo>/nombre_miniapp1/
• https://<usuario>.github.io/<repo>/nombre_miniapp2/

Características

• pnpm workspaces
• Vite + Preact + TypeScript
• vite-plugin-pwa para manifest y service worker
• apps/home como launcher de miniapps
• miniapp real de ejemplo: planning-board
• generador pnpm new:miniapp
• validación automática del monorepo
• build agregado para GitHub Pages
• previsualización local del artefacto final
• workflow de GitHub Actions para despliegue

Estructura del repositorio

miniapps/
├─ apps/
│  ├─ home/
│  └─ planning-board/
├─ assets/
│  └─ pwa/
├─ tooling/
│  └─ create-miniapp/
├─ scripts/
│  ├─ lib/
│  ├─ build-pages.mjs
│  ├─ generate-home-registry.mjs
│  ├─ validate-miniapps.mjs
│  └─ preview-pages.mjs
└─ .github/workflows/

Requisitos

• Git
• Node.js 20 o superior
• pnpm 10

Comprobación rápida:

node -v
pnpm -v
git --version

Puesta en marcha local

Instala dependencias y valida que el repositorio está consistente:

pnpm install
pnpm test:scripts
pnpm validate:miniapps
pnpm generate:home

Esto deja validado el generador, la estructura del monorepo y el launcher home.

Desarrollo local

Para levantar una app concreta en modo desarrollo:

pnpm --filter @miniapps/home dev
pnpm --filter @miniapps/planning-board dev
pnpm --filter @miniapps/md-converter dev
pnpm --filter @miniapps/sticky-board dev
pnpm --filter @miniapps/template-mgr dev

Crear una nueva miniapp

Comando

pnpm new:miniapp <slug> [opciones]

Ejemplos

pnpm new:miniapp shopping-list

pnpm new:miniapp habit-tracker --title "Habit Tracker" --desc "Seguimiento de hábitos" --router --theme "#0f766e"

pnpm new:miniapp habit-tracker \
  --title "Habit Tracker" \
  --desc "Seguimiento de hábitos" \
  --router \
  --theme "#0f766e" \
  --background "#ffffff" \
  --tags "habit,productivity" \
  --icon "leaf"

Opciones soportadas

• --title <texto> Nombre amigable de la miniapp. Se usa en home y en el manifest PWA. Ejemplo: --title "Habit Tracker"

• --desc <texto> Descripción corta de la app para el launcher y metadatos. Ejemplo: --desc "Seguimiento de hábitos"

• --router Activa modo SPA con router cliente. El generador establecerá router: true en app.config.json y creará public/404.html para restaurar rutas en GitHub Pages. Úsalo si la app necesita rutas internas, por ejemplo /settings.

• --no-pwa Genera una miniapp sin huella PWA. No añade vite-plugin-pwa, no copia iconos PWA y no genera manifest ni service worker.

• --theme <hex> Color primario en hexadecimal. Se aplica a manifest.theme_color, meta theme-color y variables CSS de acento. Por defecto: #004F87 Ejemplo: --theme "#0f766e"

• --background <hex> Color de fondo en hexadecimal para manifest.background_color y estilos de carga. Por defecto: #FFFFFF Ejemplo: --background "#ffffff"

• --category <texto> Metadata opcional para clasificación futura. home no depende de ello. Ejemplo: --category "productivity"

• --tags <csv> Metadata opcional separada por comas. Solo se guarda si se proporciona. Ejemplo: --tags "habit,productivity,offline"

• --icon <nombre> Metadata opcional del icono. Solo se guarda si se proporciona. Ejemplo: --icon "leaf"

• --listed=false Evita que la app aparezca en home. Por defecto las apps se listan. Es útil para apps privadas o en desarrollo. Ejemplo: --listed=false

Qué hace el generador

1. Valida el slug.
2. Crea apps/<slug>.
3. Genera los archivos base de la app.
4. Copia iconos PWA solo si la app es PWA.
5. Crea 404.html si la app usa router.
6. Regenera el launcher home.
7. Valida el resultado. Si falla por un problema global del repositorio, conserva la nueva app para revisión.

La plantilla base comparte estilos desde styles/base.css. La miniapp nueva solo redefine las variables necesarias para su identidad visual y ajustes locales.

Uso de la skill miniapp-monorepo-builder

Si prefieres usar el asistente/skill del repositorio para proponer y generar la miniapp, sigue este flujo resumido (la definición completa está en .agents/skills/miniapp-monorepo-builder/SKILL.md).

• Verifica el contrato del repo: asegúrate de tener package.json con pnpm new:miniapp, tooling/create-miniapp/src/cli.js, y los scripts de validación (scripts/validate-miniapps.mjs, scripts/generate-home-registry.mjs).
• Recoge los datos mínimos: slug, title, desc, si necesita rutas cliente (--router) y si será PWA (--no-pwa).
• Propón antes de ejecutar: la skill exige una propuesta que incluya el slug, el comando exacto pnpm new:miniapp ..., el alcance funcional inicial y los tests previstos; sólo se ejecuta tras tu aprobación.
• Genera con el CLI del repo: la skill invoca pnpm new:miniapp <slug> [flags] (usa siempre el entrypoint pnpm en vez de llamar al CLI por node salvo motivo concreto).
• Implementa la primera versión: tras el scaffold, la skill sugiere reemplazar los placeholders por la primera funcionalidad (estructura recomendada: src/features, src/lib, src/hooks).
• Valida y documenta: ejecutar tests relevantes, pnpm validate:miniapps y describir explícitamente qué fue generado por el CLI y qué se implementó manualmente.

Usa la skill cuando quieras que el agente proponga, genere y aterrice una miniapp coherente con las convenciones del monorepo; para detalles y criterios de decisión revisa el archivo de la skill enlazado arriba.

Flujo recomendado tras crear una app

pnpm new:miniapp <slug> --title "..." --desc "..."
pnpm test:scripts
pnpm validate:miniapps
pnpm --filter @miniapps/<slug> dev
pnpm build:pages

Checklist sugerido:

1. Crear la app con pnpm new:miniapp.
2. Revisar apps/<slug>/app.config.json.
3. Levantar la app en local.
4. Ejecutar validaciones.
5. Generar dist-pages/.
6. Hacer commit y push.

Validación y utilidades

Validar miniapps

pnpm validate:miniapps

Comprueba:

• nombres válidos
• ficheros obligatorios
• coherencia entre app.config.json y package.json
• iconos requeridos solo para apps PWA
• 404.html si router=true
• ausencia de lógica de redirect en apps sin router

Regenerar el launcher home

pnpm generate:home

Generar build agregado para Pages

pnpm build:pages

Previsualizar el artefacto final

pnpm preview:pages

Despliegue en GitHub Pages

Crear y vincular el repositorio

Desde GitHub:

1. Crea un repositorio nuevo.
2. Asígnale un nombre, por ejemplo miniapps.
3. Márcalo como público si quieres el caso más simple con GitHub Pages.

Después, vincula el repositorio local:

git init
git remote add origin https://github.com/<usuario>/<repo>.git
git add .
git commit -m "Initial commit"
git branch -M main
git push -u origin main

Configuración de Pages

1. Ve a Settings > Pages.
2. En Build and deployment, selecciona GitHub Actions.
3. Verifica que la pestaña Actions esté habilitada.
4. Haz push a main.

El despliegue incluido vive en .github/workflows/deploy-pages.yml y no requiere secretos manuales en el caso estándar de GitHub Pages.

Qué hace el workflow

1. checkout
2. setup de Node y pnpm
3. pnpm install --frozen-lockfile
4. validación del repositorio
5. build de Pages
6. subida de dist-pages/
7. despliegue

Verificación previa recomendada en local

Antes del primer push, ejecuta:

pnpm install
pnpm test:scripts
pnpm validate:miniapps
pnpm build:pages

Primer despliegue recomendado

pnpm install
pnpm test:scripts
pnpm validate:miniapps
pnpm build:pages
git add .
git commit -m "Initial commit"
git push -u origin main

Después del push:

1. Abre Actions y espera a que termine Deploy GitHub Pages.
2. Entra en Settings > Pages y confirma la URL publicada.
3. Verifica home en https://<usuario>.github.io/<repo>/.
4. Verifica al menos una miniapp en su subruta.

Detalles técnicos relevantes

Base de subruta

GitHub Pages para repositorios de proyecto sirve el sitio bajo /<repo>/. Por eso cada miniapp debe construir con una base del tipo /<repo>/<app>/.

Este monorepo calcula esa base a partir de:

• GITHUB_REPOSITORY en CI
• VITE_REPO_NAME en local

Recarga en subrutas SPA

GitHub Pages no resuelve rutas profundas de una SPA. Las apps con router incluyen public/404.html para restaurar la ruta al arrancar.

Problemas comunes

Assets con 404

Revisa:

• VITE_REPO_NAME
• GITHUB_REPOSITORY
• nombre real del repositorio en GitHub

Una SPA falla al recargar

Revisa:

• que exista public/404.html
• que router esté activado en app.config.json

home no muestra una app

Revisa:

• listed
• ejecuta pnpm generate:home
• vuelve a ejecutar pnpm validate:miniapps

Falla GitHub Actions

Comprueba que estos comandos funcionan en local:

pnpm test:scripts
pnpm validate:miniapps
pnpm build:pages

Además, verifica:

• que Pages esté configurado con GitHub Actions
• que .github/workflows/deploy-pages.yml exista y no esté deshabilitado

Ejemplo de flujo completo

pnpm new:miniapp weekly-planner --title "Weekly Planner" --desc "Planificador semanal offline" --theme "#7c3aed"
pnpm test:scripts
pnpm validate:miniapps
pnpm generate:home
pnpm --filter @miniapps/weekly-planner dev
pnpm build:pages
pnpm preview:pages
git add .
git commit -m "Add weekly-planner miniapp"
git push

TODO

• dir openspec al crear andamiaje
• skill con openspec
• md con imagenes
• versionar

✨ Sugerencias de Funcionalidades

Alta prioridad (impacto inmediato):

• Undo/Redo (Ctrl+Z) — imprescindible para un tablero creativo
• Duplicar nota — botón en el header o Ctrl+D
• Keyboard shortcuts — N para nueva nota, Del para borrar seleccionada, Esc para deseleccionar
• Selección múltiple — arrastrar para seleccionar un área, mover/borrar en bloque

Media prioridad:

• formato texto - permite ajustar formatos básicos tamaño, negrita

Ideas más ambiciosas:

• Tableros múltiples — el schema ya tiene boardId, solo falta la UI de navegación entre tableros
• Conectores entre notas — flechas SVG arrastrables para mapas mentales
• Plantillas de nota — nota de lista de tareas con checkboxes, nota de código con monoespaciado

---

① Formato de texto

La toolbar aparece en la nota al detectar selección de texto (mouseup + getSelection().toString() !== ''). Se puede anclar flotante sobre la selección usando getBoundingClientRect(). La implementación más robusta combina document.execCommand (bold, italic, underline) con CSS custom properties para el tamaño. Para proyectos nuevos, la alternativa moderna es la Selection API + Range para aplicar estilos directamente sobre nodos, evitando la deprecación de execCommand.

UX clave: la toolbar desaparece al hacer click fuera, y los botones se activan visualmente con document.queryCommandState() para reflejar el estado real del cursor.

---

② Conectores entre notas

Cada nota expone puntos de anclaje (connector-dot) en sus 4 bordes. Al arrastrar uno, se dibuja un path SVG Bézier cúbico (C) provisional. Al soltar sobre otra nota, el conector queda vinculado. La curva se recalcula en cada mousemove durante el drag de una nota, usando getBoundingClientRect() relativo al tablero. Los conectores se guardan en un array como { from: noteId, fromAnchor: 'right', to: noteId, toAnchor: 'left', label: '' }. La etiqueta central es un <foreignObject> o <text> clickeable para editar.

---

③ Plantillas de nota

La nota tiene un campo type en su modelo de datos (blank | todo | code). El selector aparece justo al crear la nota (bottom bar), antes de confirmar. Cada tipo renderiza un componente diferente: la todo-list guarda items[] con { text, done } y muestra checkboxes reactivos; la nota código activa fuente monoespaciada, un selector de lenguaje y puede integrar un syntax highlighter ligero como Prism.js sólo en ese contexto.