Ciclo de Desenvolvimento

Visão geral

Três comandos cobrem todo o ciclo de desenvolvimento no Spraxium: spraxium dev para a iteração local, spraxium build para gerar um artefato de produção e spraxium start para executar esse artefato. Esta página reúne os três para que você entenda como eles se conectam sem precisar pular entre documentos.

spraxium dev

spraxium dev inicia um servidor de desenvolvimento que observa os arquivos e reinicia a aplicação automaticamente quando o código-fonte muda. Ele usa SWC para carregar TypeScript sem uma etapa separada de compilação, mantendo os reinícios rápidos mesmo em projetos grandes. O observador reage aos padrões glob include e exclude da sua configuração e aplica um debounce configurável para agrupar salvamentos rápidos em um único reinício.

spraxium dev

Configuração do dev

export default {
  dev: {
    entrypoint: 'src/main.ts',
    include: ['src/**'],
    exclude: ['src/**/*.spec.ts'],
    debounce: 300,
  },
};

Recuperação após falhas

Se o processo do bot falhar, o servidor de dev não encerra. Ele aplica um atraso com backoff exponencial antes de iniciar de novo, calculado como Math.min(1000 * 2 ** crashCount, maxBackoff). Isso evita um ciclo apertado de relançamentos quando a falha é reproduzível. Corrija o erro, salve o arquivo, e o observador fará um reinício normal.

spraxium build

spraxium build valida os tipos e produz um bundle pronto para produção. Ele roda em duas etapas sequenciais: primeiro a verificação de tipos e depois o bundler. Se a verificação falhar, o bundler nem chega a executar, então você recebe um código de saída limpo, confiável para pipelines de CI.

spraxium build

O que acontece

A saída compilada vai para .spraxium/dist/ por padrão. Esse diretório é o artefato que spraxium start procura.

spraxium start

spraxium start executa o artefato compilado produzido por spraxium build. Antes de iniciar, ele define NODE_ENV=production e herda o stdio do processo atual para que os logs da aplicação sejam exibidos diretamente no terminal.

spraxium start

Resolução do ponto de entrada

A CLI verifica os caminhos abaixo em ordem e executa o primeiro que encontrar:

1. .spraxium/dist/src/main.js
2. .spraxium/dist/main.js
3. dist/src/main.js
4. dist/main.js
5. build/src/main.js
6. build/main.js

Fluxo típico

Uma iteração completa, do desenvolvimento à produção, costuma seguir esta ordem: use spraxium dev durante o trabalho ativo, mude para spraxium build ao preparar uma release e, por fim, rode spraxium start para verificar ou implantar o artefato compilado. Em CI, pule totalmente a etapa de dev e execute build seguido de start como pipeline de validação.

Bloqueio de processo

O Spraxium grava um arquivo de lock por projeto em .spraxium/spraxium.lock ao iniciar e o remove em um desligamento limpo. Se uma segunda instância detectar esse lock, ela encerra com um aviso de conflito em vez de duplicar listeners e registros de comandos silenciosamente.

Flags

Tanto spraxium dev quanto spraxium start oferecem duas flags relacionadas ao lock:

# Kill the running instance and take over
spraxium dev --force-unlock

# Skip the lock check (concurrent instances allowed)
spraxium dev --no-lock

Locks obsoletos deixados por processos que falharam são detectados automaticamente com process.kill(pid, 0) e removidos antes da inicialização, então você só verá avisos de conflito quando a outra instância realmente estiver em execução.

Notificador de atualização

Na inicialização, o Spraxium examina node_modules/@spraxium/* para encontrar todos os pacotes do framework instalados no projeto, consulta o registro do npm pelas versões mais recentes e mostra um aviso se algum pacote estiver desatualizado. Essa verificação roda em segundo plano e nunca atrasa a inicialização.

Os resultados são armazenados em cache em ~/.spraxium/upgrade-check.json, com TTL de 24 horas compartilhado por todos os projetos da máquina. Se um pacote tiver sido instalado recentemente e ainda não estiver no cache, apenas esse pacote será buscado, enquanto o restante usará os dados já armazenados.

Defina SPRAXIUM_NO_UPGRADE_NOTIFIER=1, ou a variável de ambiente com o mesmo nome, para desativar completamente essa verificação. Isso é útil em ambientes de CI, nos quais o aviso gera mais ruído do que sinal.