O arquivo de configuração
Todo projeto Spraxium tem um arquivo spraxium.config.ts na raiz. Esse arquivo é a fonte única de verdade para todo o comportamento de runtime: quais plugins estão ativos, como os commands fazem match, como os erros são apresentados e como o watcher de desenvolvimento local se comporta. O framework lê esse arquivo uma vez na inicialização e armazena o resultado como um snapshot imutável antes que qualquer módulo comece a rodar.
Você escreve esse arquivo usando o helper defineConfig exportado por @spraxium/core. Ele aceita tanto um objeto simples quanto um callback que recebe um argumento ConfigEnv. As duas formas produzem uma config válida, mas a forma com callback é recomendada sempre que as opções precisarem variar entre ambientes, porque deixa todas as ramificações explícitas em um ú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,
},
}));Callback vs forma de objeto
A forma com callback recebe um objeto ConfigEnv construído a partir de uma única leitura de NODE_ENV na inicialização. Ele expõe isDev, isNeutral e isProd para que você possa ramificar por ambiente sem comparar strings cruas. A forma de objeto é adequada para projetos em que a configuração é idêntica em todos os ambientes.
import { defineConfig } from '@spraxium/core';
export default defineConfig((env) => ({
debug: env.isNeutral,
logger: {
maskTokens: true,
commandLogging: env.isDev
}
}));As flags de ConfigEnv são resolvidas a partir de NODE_ENV da seguinte forma.
| NODE_ENV | Flag ativa |
|---|---|
| production | isProd = true |
| neutral, staging ou test | isNeutral = true |
| Qualquer outro valor | isDev = true |
Sequência de inicialização
O framework conclui estas etapas antes que qualquer módulo da aplicação comece a rodar.
Descoberta do arquivo de config
O framework examina a raiz do projeto em busca de spraxium.config.ts,
depois spraxium.config.js e então spraxium.config.mjs. Em modo de
produção, os artefatos compilados em dist/ e .spraxium/dist/ são
verificados primeiro. O primeiro arquivo encontrado em disco vence, e a
busca para imediatamente.
Resolução e avaliação do ambiente
NODE_ENV é lido uma vez e mapeado para um objeto ConfigEnv. Se a sua
exportação for uma função, ela é chamada com esse objeto e seu valor de
retorno é usado. Se for um objeto simples, ele é usado diretamente. O
resultado é armazenado como um singleton imutável pelo restante da vida do
processo.
Inicialização de módulos e plugins
O framework resolve módulos, providers e hooks de ciclo de vida. Cada plugin lê sua própria fatia de configuração a partir do singleton usando sua factory como chave de lookup. Depois desse ponto, não há novas leituras do arquivo de configuração.
Não ter arquivo de config não é um erro
Se nenhum arquivo de configuração for encontrado na inicialização, o framework continua com todos os defaults aplicados e registra uma mensagem de debug. Esse é o estado esperado durante o setup inicial do projeto, antes de o arquivo de config ser criado.
Uma responsabilidade por bloco
Cada chave de topo no objeto de configuração pertence a um subsistema. As opções de plugin vivem dentro das respectivas factory calls. A política de match de command fica no bloco prefix. A renderização de exceções fica no bloco exceptions. Manter cada bloco focado significa que alterar uma área não cria efeitos colaterais em outra, e isolar um incidente durante uma indisponibilidade em produção continua sendo rápido.