Versionamento & compatibilidade
O que o Basalt promete sobre versões, runtimes e mudança — para que possas depender dele sem surpresas.
Versionamento semântico
Cada pacote @basaltkit/* segue semver. A partir da 1.0, a API pública é estável: breaking changes apenas num novo major, novas funcionalidades num minor, e correções num patch. Podes depender de um intervalo ^1 e obter funcionalidades e correções sem quebras até ao próximo major.
Um pacote também sobe um major quando sobe um pacote que tem de partilhar com a tua app: uma peer dependency (o pacote de funcionalidade de um adapter de armazenamento, os adapters do testing), ou uma dependência que partilha através do container da app, dos seus tipos de rota ou do seu pipeline de pedidos. Nunca sai como um patch que exige em silêncio a nova major de outro pacote. Uma dependência normal usada como cópia privada (rotas construídas com route(), um helper puro) recebe um patch.
Versões dos pacotes & a release do Basalt
O versionamento funciona em dois níveis, de propósito:
- Cada pacote
@basaltkit/*é versionado de forma independente. Um pacote incrementa o seu próprio semver só quando ele muda, por isso o@basaltkit/subscriptionspode estar em2.xenquanto o@basaltkit/coreainda está em1.x. Depende de cada um com um range^; cada pacote é construído e testado contra o@basaltkit/coreatual. A versão exata e atual de cada pacote está na página Ecossistema. - O framework como um todo tem uma "release do Basalt" — atualmente 1.6 (o número no nav). É um marcador amigável para uma geração do framework, usado apenas para comunicação e para estes docs — a
1.0foi a primeira release estável, e as gerações seguintes acrescentaram escala, tempo-real, passwordless e IA/MCP, sendo a 1.4 a vaga da toolchain TypeScript 7 e reforço de segurança, a 1.5 a experiência de desenvolvimento IA no teu editor sobre MCP, e a 1.6 a release em que as promessas da framework passaram a garantias impostas por CI (ver Novidades). Não é a versão de nenhum pacote em particular.
De que número dependo?
Depende das versões dos pacotes — são essas que o npm instala e resolve. O número da release do Basalt (ex.: "Basalt 1.6") é só uma etiqueta amigável para "que geração do framework estes docs descrevem".
Suporte de runtime
| Aspeto | Política |
|---|---|
| Node.js | 22 ou mais recente. O CI testa em Node 22 e 24. |
Stores node:sqlite | Os pacotes de store *-sqlite precisam de Node 22.5+; estáveis e sem flag no Node 24, e no 22.x requerem --experimental-sqlite. Declaram engines.node >= 22.5.0. |
| Módulos | Apenas ESM. Cada pacote inclui "type": "module" com exports apenas de import — não há build CommonJS. Usa ESM (ou um bundler) na tua app. |
| TypeScript | Os tipos vêm com cada pacote. exactOptionalPropertyTypes e a família strict são honrados, por isso os tipos são seguros de consumir em modo strict. |
| Gestor de pacotes | O repositório usa pnpm, mas qualquer gestor serve para consumir os pacotes publicados. |
Se não usares os pacotes *-sqlite, Node 22+ é suficiente; esses são os únicos pacotes que requerem 22.5+.
Política de deprecação
Agora que a 1.0 foi lançada, nada na API pública é removido sem aviso:
- Um símbolo marcado para remoção é assinalado como
@deprecatedno seu JSDoc, com o substituto nomeado, num release minor. - Continua a funcionar durante o resto da linha
1.x. - Só é removido no próximo major (
2.0).
"API pública" significa cada export de topo de um pacote. Qualquer coisa marcada como @internal, ou não exportada do ponto de entrada do pacote, não está coberta por esta política e pode mudar a qualquer momento.
Atualizar a partir de 0.x
A 1.0 é um compromisso de estabilidade, não uma reescrita — é funcionalmente idêntica à 0.32.0, sem breaking changes. A migrar de qualquer 0.x recente:
- Sobe todas as dependências
@basaltkit/*para1.0.0em conjunto (lançam em lockstep) e fixa um intervalo^1daí em diante. - Se estiveres nos stores duráveis, nada muda — os contratos dos stores já estavam na sua forma 1.0 e estão agora congelados.
- É tudo. Daqui em diante,
^1dá-te funcionalidades e correções sem quebras.
Segurança & versões suportadas
As correções de segurança aterram no minor 1.x mais recente — atualiza para o 1.x mais novo para as receber. Ver SECURITY.md para o processo de divulgação.