El archivo de configuración
Cada proyecto Spraxium tiene un archivo spraxium.config.ts en su raíz. Este archivo es la única fuente de verdad para todo el comportamiento en tiempo de ejecución: qué plugins están activos, cómo se comparan los comandos, cómo se presentan los errores y cómo se comporta el watcher de desarrollo local. El framework lo lee una sola vez al iniciar y guarda el resultado como una instantánea inmutable antes de que cualquier módulo comience a ejecutarse.
Escribes el archivo usando el helper defineConfig exportado desde @spraxium/core. Acepta un objeto plano o un callback que recibe un argumento ConfigEnv. Ambas formas producen una configuración válida, pero se recomienda la forma con callback cuando las opciones deben diferir entre entornos, porque hace explícitas todas las bifurcaciones en un único lugar.
import { defineConfig } from '@spraxium/core';
import { defineSchedule } from '@spraxium/schedule';
export default defineConfig((env) => ({
debug: env.isNeutral,
plugins: [
defineSchedule({ timezone: 'America/Sao_Paulo', disableAll: false }),
],
dev: {
entrypoint: 'src/main.ts',
debounce: 500,
},
}));Forma callback vs forma objeto
La forma con callback recibe un objeto ConfigEnv construido a partir de una sola lectura de NODE_ENV al inicio. Expone isDev, isNeutral e isProd para que puedas bifurcar por entorno sin comprobar strings crudos. La forma de objeto es adecuada para proyectos donde la configuración es idéntica en todos los entornos.
import { defineConfig } from '@spraxium/core';
export default defineConfig((env) => ({
debug: env.isNeutral,
logger: {
maskTokens: true,
commandLogging: env.isDev
}
}));Los flags de ConfigEnv se resuelven desde NODE_ENV de la siguiente manera.
| NODE_ENV | Flag activa |
|---|---|
| production | isProd = true |
| neutral, staging o test | isNeutral = true |
| Cualquier otro valor | isDev = true |
Secuencia de inicio
El framework completa estos pasos antes de que se ejecute cualquier módulo de la aplicación.
Descubrimiento del archivo de configuración
El framework escanea la raíz del proyecto en busca de spraxium.config.ts,
luego spraxium.config.js y después spraxium.config.mjs. En modo de
producción, primero se comprueban los artefactos compilados en dist/ y
.spraxium/dist/. Gana el primer archivo que exista en disco, y la
búsqueda se detiene de inmediato.
Resolución del entorno y evaluación
NODE_ENV se lee una sola vez y se mapea a un objeto ConfigEnv. Si tu
exportación es una función, se llama con este objeto y se usa su valor de
retorno. Si es un objeto plano, se usa directamente. El resultado se guarda
como un singleton inmutable durante el resto de la vida del proceso.
Inicialización de módulos y plugins
El framework resuelve módulos, providers y hooks del ciclo de vida. Cada plugin lee su propio fragmento de configuración del singleton usando su factory como clave de búsqueda. No hay más lecturas del archivo de configuración después de este punto.
No tener archivo de configuración no es un error
Si no se encuentra ningún archivo de configuración al iniciar, el framework continúa con todos los valores predeterminados aplicados y registra un mensaje de debug. Este es el estado esperado durante la configuración inicial del proyecto, antes de crear el archivo de configuración.
Una responsabilidad por bloque
Cada clave de nivel superior del objeto de configuración pertenece a un subsistema. Las opciones de plugin viven dentro de sus respectivas llamadas de factory. La política de matching de comandos vive en el bloque prefix. El renderizado de excepciones vive en el bloque exceptions. Mantener cada bloque enfocado significa que modificar una zona nunca crea efectos secundarios en otra, y que acotar un incidente durante una caída en producción siga siendo rápido.