Resumen
Tres comandos cubren el ciclo de desarrollo completo en Spraxium: spraxium dev para iteración local, spraxium build para producir un artefacto de producción y spraxium start para ejecutar ese artefacto. Esta página cubre los tres para que no tengas que saltar entre páginas para entender cómo se conectan.
spraxium dev
spraxium dev inicia un servidor de desarrollo con observación de archivos que reinicia la aplicación automáticamente cuando cambian los archivos fuente. Usa SWC para cargar TypeScript sin un paso de compilación separado, manteniendo tiempos de reinicio cortos incluso en proyectos grandes. El watcher se activa según los patrones glob include y exclude de tu configuración, y aplica un debounce configurable para agrupar guardados rápidos en un único reinicio.
spraxium devConfiguración de dev
export default {
dev: {
entrypoint: 'src/main.ts',
include: ['src/**'],
exclude: ['src/**/*.spec.ts'],
debounce: 300,
},
};Los excludes predeterminados siempre están activos
Incluso sin bloque de configuración, el watcher ignora node_modules, .git y .spraxium para evitar bucles de reinicio causados por instalaciones de dependencias o salida de build.
Recuperación ante crashes
Si el proceso del bot se cae, el servidor de dev no se cierra. Aplica un retraso con backoff exponencial antes de relanzar, calculado como Math.min(1000 × 2^crashCount, maxBackoff). Esto evita un bucle de relanzamiento agresivo cuando el crash es reproducible. Corrige el error, guarda el archivo y el watcher disparará un reinicio normal.
spraxium build
spraxium build valida tipos y produce un bundle listo para producción. Corre en dos pasos secuenciales: primero un type-check y después el bundler. Si el type-check falla, el bundler no llega a ejecutarse, así que obtienes un código de salida limpio en el que los pipelines de CI pueden confiar.
spraxium buildQué ocurre
Type-check
Ejecuta tsc --noEmit sobre tu proyecto. Cualquier error de tipos hace que
el comando falle inmediatamente. Corrige todos los errores de TypeScript
antes de que el bundler pueda continuar.
Bundle
Ejecuta tsdown con la configuración de tu proyecto. Si existe un archivo
tsdown.config.* en la raíz del proyecto, el CLI lo usa. Si no, aplica
estos predeterminados: entry points src/main.ts y spraxium.config.ts,
directorio de salida .spraxium/dist, formato ESM, plataforma Node,
--clean y --no-dts.
La salida compilada queda en .spraxium/dist/ por defecto. Este directorio es el artefacto que busca spraxium start.
Build no ejecuta tests
Ejecutar spraxium build no corre tu suite de tests. Ejecuta tus tests por separado antes o después, y trata el build solo como una puerta de tipos y bundling.
spraxium start
spraxium start ejecuta el artefacto compilado producido por spraxium build. Establece NODE_ENV=production antes de iniciar y hereda el stdio del proceso actual para que los logs de la aplicación se muestren directamente en la terminal.
spraxium startResolución del entrypoint
El CLI comprueba las siguientes rutas en orden y ejecuta la primera que encuentre:
.spraxium/dist/src/main.js.spraxium/dist/main.jsdist/src/main.jsdist/main.jsbuild/src/main.jsbuild/main.js
Sin build no hay start
Si ninguna de las rutas candidatas existe, el comando falla e imprime un mensaje indicando que debes ejecutar spraxium build primero. Asegúrate de que las variables de entorno como DISCORD_TOKEN estén cargadas antes de correr este comando.
Flujo típico
Una iteración completa de desarrollo a producción sigue este orden: ejecuta spraxium dev durante el trabajo activo, luego pasa a spraxium build al preparar una release y finalmente ejecuta spraxium start para verificar o desplegar el artefacto compilado. En CI, omite por completo el paso de dev y ejecuta build y luego start en secuencia como pipeline de validación.
Bloqueo de proceso
Spraxium escribe un archivo de bloqueo por proyecto en .spraxium/spraxium.lock al arrancar y lo elimina en un apagado limpio. Si una segunda instancia detecta el lock, se cierra con una advertencia de conflicto en lugar de duplicar silenciosamente listeners y registros de comandos.
Banderas
Tanto spraxium dev como spraxium start soportan dos banderas relacionadas con el lock:
| Bandera | Variable de entorno | Descripción |
|---|---|---|
| --force-unlock | SPRAXIUM_FORCE_UNLOCK=1 | Mata el proceso del bot existente (y su launcher dev-watcher para evitar auto-respawn) y luego toma el control. La terminal se libera inmediatamente después del kill. |
| --no-lock | SPRAXIUM_NO_LOCK=1 | Omite por completo la comprobación de lock. Úsalo solo en configuraciones que intencionalmente ejecutan instancias concurrentes (por ejemplo, un entorno de pruebas en paralelo con producción). |
# Kill the running instance and take over
spraxium dev --force-unlock
# Skip the lock check (concurrent instances allowed)
spraxium dev --no-lockLos locks obsoletos de procesos caídos se detectan automáticamente mediante process.kill(pid, 0) y se limpian antes del arranque, así que solo verás advertencias de conflicto para instancias realmente en ejecución.
Notificador de actualizaciones
Al arrancar, Spraxium escanea node_modules/@spraxium/* para encontrar todos los paquetes del framework instalados en el proyecto, consulta el registro de npm para obtener las versiones más recientes e imprime un aviso si alguno está desactualizado. La comprobación corre en background y nunca retrasa el arranque.
Los resultados se cachean en ~/.spraxium/upgrade-check.json con un TTL de 24 horas compartido entre todos los proyectos de la máquina. Si se instaló recientemente un paquete que aún no está en caché, solo se consulta ese paquete, mientras el resto usa los datos cacheados.
Establece SPRAXIUM_NO_UPGRADE_NOTIFIER=1 (o la variable de entorno con el mismo nombre) para desactivar la comprobación por completo. Esto es útil en entornos CI donde el aviso aporta ruido en lugar de señal.