Por que TypeScript para FiveM?
TypeScript traz verificação de tipo estático, recursos modernos de JavaScript e suporte IDE superior para o desenvolvimento FiveM. Embora Lua continue sendo a linguagem de script padrão, o TypeScript compilado para JavaScript é executado nativamente no FiveM por meio do tempo de execução do JavaScript. A segurança de tipo detecta bugs em tempo de compilação que, de outra forma, travariam seu servidor em tempo de execução, o preenchimento automático acelera significativamente o desenvolvimento e as interfaces tornam seu código autodocumentado. Para projetos complexos com vários desenvolvedores, o TypeScript reduz a sobrecarga de coordenação e torna a refatoração mais segura.
Configuração do projeto com fivem-ts-boilerplate
A maneira mais rápida de iniciar um projeto TypeScript FiveM é usando a comunidade fivem-ts-boilerplate. Clone o repositório de modelos, execute npm install para configurar dependências e você terá uma estrutura de projeto pronta para uso com cliente, servidor e diretórios de origem compartilhados separados. O padrão inclui uma configuração de webpack que compila pacotes TypeScript para JavaScript compatíveis com FiveM, junto com definições de tipo para nativos FiveM, funções cidadãs e APIs de estrutura comuns. Crie seu projeto com npm run build e a saída vai diretamente para uma pasta de recursos.
Definições de tipo e nativos
Os pacotes de tipo @citizenfx/client e @citizenfx/server fornecem definições TypeScript para todas as funções nativas e chamadas de API do FiveM. Essas definições permitem o preenchimento automático para funções como GetEntityCoords, SetEntityHealth e RegisterCommand, mostrando tipos de parâmetros e valores de retorno à medida que você codifica. Para APIs específicas da estrutura, como QBCore ou ESX, você pode criar ou instalar arquivos de definição de tipo adicionais que cobrem as exportações e eventos da estrutura. Isso transforma seu IDE em um navegador de documentação interativo para toda a API FiveM.
Arquitetura de cliente e servidor
Estruture seu projeto TypeScript com separação clara entre o código do cliente e do servidor. Use o diretório compartilhado para interfaces, enums e funções utilitárias que ambos os lados precisam. Defina interfaces de carga útil de evento em tipos compartilhados para que o compilador verifique se o cliente e o servidor concordam com os formatos dos dados. Importe wrappers de estrutura de uma camada de serviços que abstrai a estrutura subjacente, tornando sua lógica de negócios portátil em QBCore, ESX e configurações autônomas. Essa arquitetura torna sua base de código modular e testável.
Depurando TypeScript em FiveM
Depurar código compilado pode ser desafiador, pois o JavaScript executado difere da fonte TypeScript. Habilite mapas de origem na configuração do seu webpack para que os rastreamentos de pilha de erros façam referência aos seus arquivos TypeScript originais. Use instruções console.log que são encaminhadas para o console do servidor FiveM para depuração do lado do servidor. Para depuração do lado do cliente, as ferramentas de desenvolvedor NUI acessíveis por meio de F8 podem inspecionar a execução de JavaScript. Considere adicionar um utilitário de registro estruturado que inclua carimbos de data/hora, níveis de registro e referências de arquivos de origem para facilitar o rastreamento de problemas por meio da saída compilada.
Migração e Coexistência com Lua
Você não precisa converter todo o seu servidor para TypeScript de uma só vez. Os recursos TypeScript coexistem perfeitamente com os recursos Lua, pois se comunicam através do mesmo evento e sistema de exportação. Comece construindo novos recursos em TypeScript enquanto mantém os scripts Lua existentes. Ao chamar exportações Lua do TypeScript, crie declarações de tipo que descrevam as assinaturas de função esperadas. Migre gradualmente sistemas críticos à medida que você ganha confiança com o fluxo de trabalho TypeScript. Essa abordagem incremental permite que sua equipe aprenda TypeScript enquanto mantém o servidor estável e evita uma reescrita completa arriscada.