README

🚀 Un watcher inteligente para Drupal que vigila tus módulos y temas custom, ejecutando drush cr automáticamente al detectar cambios. Soporte nativo para DDEV, Lando y entornos locales.

📋 Tabla de Contenidos

¿Qué hace?
Características
Requisitos
Instalación
Comandos
Configuración
Ejemplos de uso
Solución de problemas
Preguntas frecuentes
Contribución
Licencia

¿Qué hace?

Olvídate de ejecutar manualmente drush cr cada vez que modificas un archivo. Drupal Watcher:

Vigila en tiempo real los archivos de tus módulos y temas custom
Detecta automáticamente cambios en archivos .html.twig, .inc, .yml, .module y .theme
Ejecuta drush cr de forma inteligente (con debounce para no saturar el sistema)
Compatible con DDEV, Lando y entornos locales (usa ddev drupal-watcher en DDEV)
Persiste tus rutas personalizadas en un archivo de configuración

Características

Gestión de rutas

Añade, elimina, lista y restablece rutas a vigilar
Filtrar rutas con --watch=<ruta> y --no-watch=<ruta>
Persistencia en watcher.config.json
Validación de existencia de carpetas

Optimizado para Drupal

Detecta automáticamente el docroot de Drupal (docroot, web, html...)
Debounce inteligente (800ms por defecto)
Compatible con DDEV: ejecuta ddev drupal-watcher <comando>

Ultra rápido

Instalación con Bun (10-30x más rápido que npm)
Arranque en frío instantáneo (~8ms)
Bajo consumo de memoria

Desarrollado con Bun 🛠️

JavaScript modular (src/) con arquitectura limpia
Sin dependencias externas (solo Bun)
Ejecutable como binario standalone (opcional)
Singleton con PID file para evitar duplicados
Estadísticas en tiempo real al detener el watcher

Requisitos

Bun (instalado globalmente: curl -fsSL https://bun.sh/install | bash)
Composer (gestión de dependencias de PHP)
Drupal con Drush instalado

Instalación

Método 1: Desde Packagist (recomendado)

composer require irving-frias/drupal-watcher

Método 2: Desde repositorio local

Clona o descarga el paquete en packages/drupal-watcher/
Añade el repositorio a tu composer.json:

"repositories": [
    {
        "type": "path",
        "url": "packages/drupal-watcher-bun"
    }
]

Instala:

composer require irving-frias/drupal-watcher:@dev

Método 3: Desde ZIP

Descarga el ZIP
Descomprime en packages/drupal-watcher-bun/
Sigue los pasos del Método 2

Comandos

Todos los comandos se ejecutan desde la raíz de tu proyecto Drupal usando el binario instalado por Composer.

Iniciar el watcher

# Local o Lando
vendor/bin/drupal-watcher start

# DDEV
ddev drupal-watcher start

Verás algo como:

🚀 Iniciando Drupal Watcher
📁 Directorio raíz: docroot
🔧 Drush: drush cr
👀 Vigilando rutas:
  - docroot/modules/custom
  - docroot/themes/custom
✅ Watcher activo. Esperando cambios... (Ctrl+C para salir)

Listar rutas configuradas

vendor/bin/drupal-watcher list

Muestra las rutas actuales, patrones, debounce y comando Drush.

Añadir una nueva ruta

vendor/bin/drupal-watcher add docroot/modules/contrib

Eliminar una ruta

vendor/bin/drupal-watcher remove docroot/modules/contrib

Restablecer rutas por defecto

vendor/bin/drupal-watcher reset

Ver estado del watcher

vendor/bin/drupal-watcher status

Muestra si el watcher está activo, su PID y tiempo de ejecución.

Filtrar rutas al iniciar

# Solo vigilar una ruta específica
vendor/bin/drupal-watcher start --watch=modules/mi-modulo

# Excluir una ruta específica
vendor/bin/drupal-watcher start --no-watch=modules/contrib

# Terminar si Drush no responde
vendor/bin/drupal-watcher start --abort-on-drush-error

Comandos como alias de Composer (opcional)

Si prefieres composer watcher:*, añade estos scripts a tu composer.json raíz:

"scripts": {
    "watcher:start": "vendor/bin/drupal-watcher start",
    "watcher:list": "vendor/bin/drupal-watcher list",
    "watcher:status": "vendor/bin/drupal-watcher status",
    "watcher:add": "vendor/bin/drupal-watcher add",
    "watcher:remove": "vendor/bin/drupal-watcher remove",
    "watcher:reset": "vendor/bin/drupal-watcher reset"
}

Luego podrás ejecutar composer watcher:start, etc.

Configuración

El archivo watcher.config.json se crea automáticamente en la raíz de tu proyecto.

Estructura del archivo

{
  "routes": [
    "docroot/modules/custom",
    "docroot/themes/custom"
  ],
  "patterns": [".html.twig", ".inc", ".yml", ".module", ".theme"],
  "excludePatterns": [],
  "debounce": 800,
  "drushCmd": null,
  "drushCommand": "cr",
  "drushArgs": [],
  "postClearCommands": []
}

Opciones de configuración

Opción	Descripción	Valor por defecto
`routes`	Lista de rutas a vigilar	`["docroot/modules/custom", "docroot/themes/custom"]`
`patterns`	Extensiones de archivo a vigilar	`[".html.twig", ".inc", ".yml", ".module", ".theme"]`
`excludePatterns`	Extensiones a ignorar (ej: `[".css", ".js"]`)	`[]`
`debounce`	Tiempo de espera (ms) antes de ejecutar drush	`800`
`drushCmd`	Comando Drush personalizado (ej: `"ddev drush"`)	`null` (auto-detecta)
`drushCommand`	Subcomando de Drush a ejecutar	`"cr"`
`drushArgs`	Argumentos extra para Drush	`[]`
`postClearCommands`	Comandos a ejecutar tras limpiar caché	`[]`

Notas sobre la configuración

Patrones: Añade o quita extensiones según tus necesidades
Exclude patterns: Ignora archivos como .css o .js si no quieres que disparen drush cr
Debounce: Ajusta según el rendimiento de tu proyecto (proyectos grandes pueden necesitar más tiempo)
Drush personalizado: Si usas un binario Drush en una ubicación específica, defínelo en drushCmd
drushCommand: Cambia a "cc bin" para limpieza más rápida (solo un bin de caché) en vez de "cr" (completo)
postClearCommands: Array de comandos shell a ejecutar tras cada limpieza (ej: ["ddev drush cex", "echo 'listo'"])

Ejemplos de uso

Ejemplo 1: Watcher básico

# Instalación
composer require irving-frias/drupal-watcher

# Iniciar watcher (local o Lando)
vendor/bin/drupal-watcher start

# En DDEV
ddev drupal-watcher start

# Editar un archivo .twig...
📝 mi-plantilla.html.twig
🔄 Limpiando caché...
✅ Caché limpiada correctamente.

Ejemplo 2: Añadir módulos contrib

# Añadir módulos contrib
vendor/bin/drupal-watcher add docroot/modules/contrib

# Verificar
vendor/bin/drupal-watcher list

# Ahora vigila tanto custom como contrib

Ejemplo 3: Cache clear más rápido

Para limpiar solo un bin en vez de toda la caché, edita watcher.config.json:

{
  "drushCommand": "cc bin"
}

Esto ejecuta drush cc bin en vez de drush cr, que es más rápido.

Ejemplo 4: Comandos post-clear

Ejecuta drush cex automáticamente tras cada cambio:

{
  "postClearCommands": ["drush cex"]
}

Ejemplo 5: Compilar a binario standalone

Si no quieres depender de Composer/Bun para el día a día:

# Compilar desde el paquete de Composer
bun build --compile ./vendor/irving-frias/drupal-watcher/bin/drupal-watcher --outfile ./drupal-watcher

# O desde el repositorio local
bun run build          # compila para el SO actual
bun run build:mac      # macOS (ARM64)
bun run build:linux    # Linux (x64)
bun run build:win      # Windows (x64)

./drupal-watcher start

Ejemplo 6: Ejecutar tests

bun test                    # ejecuta tests una vez
bun run test:watch          # modo watch

Ejemplo 7: Flags avanzados del comando start

# Abortar si Drush no responde
vendor/bin/drupal-watcher start --abort-on-drush-error

# Vigilar solo una ruta específica
vendor/bin/drupal-watcher start --watch=docroot/modules/custom/mi-modulo

# Excluir contrib modules
vendor/bin/drupal-watcher start --no-watch=docroot/modules/contrib

Solución de problemas

❌ Error: `command not found: bun`

Bun no está instalado globalmente en tu sistema. Verifica:

Bun está instalado: bun --version
Si no lo tienes, instálalo con: curl -fsSL https://bun.sh/install | bash

❌ Error: `No se encontró Drush`

El watcher busca Drush en:

vendor/bin/drush (proyecto Drupal)
bin/drush (alternativa)

Verifica que:

Drush está instalado: composer require drush/drush
Estás ejecutando desde la raíz del proyecto Drupal
Si usas DDEV, ejecuta ddev drupal-watcher <comando> en lugar de vendor/bin/drupal-watcher <comando>

❌ Error: `Ninguna de las rutas configuradas existe`

Asegúrate de que:

Las carpetas docroot/modules/custom y docroot/themes/custom existen
O añade rutas válidas con vendor/bin/drupal-watcher add

❌ El watcher no detecta cambios

Verifica:

Estás editando archivos con las extensiones correctas (.html.twig, .inc, .yml, .module, .theme)
Los archivos están dentro de las rutas configuradas
En proyectos con muchos archivos, el watcher puede tardar en iniciar

❌ La caché se limpia demasiado frecuentemente

Aumenta el valor de debounce en watcher.config.json:

{
  "debounce": 1200  // 1.2 segundos
}

Preguntas frecuentes

¿Por qué usar Bun en lugar de Node.js?

Bun es 10-30x más rápido en instalaciones y 8x más rápido en arranque en frío. Además, es un "todo-en-uno" (runtime, gestor de paquetes, empaquetador), lo que reduce dependencias y complejidad.

¿Puedo usarlo sin Composer?

Sí. Puedes compilar el script a un binario standalone:

bun build --compile ./bin/drupal-watcher --outfile ./drupal-watcher
./drupal-watcher start

¿Funciona en Windows?

Sí, Bun es multiplataforma. Puedes instalarlo desde bun.sh.

¿Puedo vigilar múltiples proyectos?

No directamente. Cada proyecto tiene su propio watcher y configuración. Ejecuta el comando desde la raíz de cada proyecto.

¿Qué archivos vigila?

Por defecto: .html.twig, .inc, .yml, .module, .theme. Puedes añadir más patrones en watcher.config.json.

Contribución

¡Las contribuciones son bienvenidas!

Fork del proyecto
Crea una rama para tu feature (git checkout -b feature/amazing-feature)
Commit tus cambios (git commit -m 'Add some amazing feature')
Push a la rama (git push origin feature/amazing-feature)
Abre un Pull Request

Reportar issues

Usa el issue tracker para reportar bugs o sugerir mejoras.

Licencia

Este proyecto está bajo la Licencia MIT. Ver el archivo LICENSE para más detalles.

Agradecimientos

Bun - Por su increíble velocidad
Drupal - Por ser el mejor CMS del mundo

¿Te ha sido útil? ⭐️ Dale una estrella al repositorio y compártelo con otros desarrolladores de Drupal.

Creado con ❤️ por Irving Frías

irving-frias/drupal-watcher

包简介

README 文档