Desarrollo con TypeScript para FiveM: scripts modernos con tipos

¿Por qué TypeScript para FiveM?

TypeScript aporta comprobación de tipos estática, funciones modernas de JavaScript y una compatibilidad superior con los IDE al desarrollo para FiveM. Aunque Lua sigue siendo el lenguaje de scripting estándar, TypeScript se compila a JavaScript y se ejecuta de forma nativa en FiveM mediante el runtime de JavaScript. La seguridad de tipos detecta errores durante la compilación que, de otro modo, podrían hacer que el servidor fallara en tiempo de ejecución. El autocompletado agiliza considerablemente el desarrollo y las interfaces hacen que el código se explique por sí mismo. En proyectos complejos con varios desarrolladores, TypeScript reduce el trabajo de coordinación y hace que las refactorizaciones sean más seguras.

Configuración del proyecto con fivem-ts-boilerplate

La forma más rápida de empezar un proyecto TypeScript para FiveM es usar el fivem-ts-boilerplate de la comunidad. Clona el repositorio de la plantilla, ejecuta npm install para instalar las dependencias y tendrás una estructura de proyecto lista para usar, con directorios separados para el código fuente del cliente, del servidor y compartido. El boilerplate incluye una configuración de webpack que compila TypeScript en bundles de JavaScript compatibles con FiveM, además de definiciones de tipos para los natives de FiveM, las funciones de Citizen y las API de frameworks comunes. Compila tu proyecto con npm run build y los archivos de salida se guardarán directamente en una carpeta de recurso.

Definiciones de tipos y natives

El @citizenfx/client y @citizenfx/server Los paquetes de tipos proporcionan definiciones de TypeScript para todas las funciones nativas y llamadas a la API de FiveM. Estas definiciones permiten usar el autocompletado con funciones como GetEntityCoords, SetEntityHealth, y RegisterCommand, y muestran los tipos de parámetros y los valores de retorno mientras escribes código. Para las API específicas de frameworks como QBCore o ESX, puedes crear o instalar archivos adicionales de definiciones de tipos que incluyan los exports y eventos del framework. Así, tu IDE se convierte en un navegador interactivo de documentación para toda la API de FiveM.

Arquitectura de cliente y servidor

Organiza tu proyecto TypeScript separando claramente el código del cliente y del servidor. Usa el directorio compartido para las interfaces, enumeraciones y funciones de utilidad que necesiten ambos lados. Define interfaces para los datos de eventos en los tipos compartidos, para que el compilador verifique que el cliente y el servidor coincidan en las estructuras de datos. Importa wrappers del framework desde una capa de servicios que abstraiga el framework subyacente. Así, la lógica de negocio será compatible con configuraciones QBCore, ESX y standalone. Esta arquitectura hace que tu base de código sea modular y fácil de probar.

Depuración de TypeScript en FiveM

Depurar código compilado puede ser complicado, ya que el JavaScript que se ejecuta es distinto del código fuente de TypeScript. Activa los source maps en tu configuración de webpack para que las trazas de error hagan referencia a tus archivos TypeScript originales. Usa console.log para que los mensajes aparezcan en la consola del servidor de FiveM y puedas depurar el código del servidor. Para depurar el cliente, puedes inspeccionar la ejecución de JavaScript con las herramientas para desarrolladores de NUI, disponibles mediante F8. Considera añadir una herramienta de registro estructurado que incluya marcas de tiempo, niveles de registro y referencias a los archivos de origen, para facilitar el seguimiento de problemas en el código compilado.

Migración y coexistencia con Lua

No tienes que convertir todo tu servidor a TypeScript de una sola vez. Los recursos TypeScript coexisten sin problemas con los recursos Lua, ya que se comunican mediante el mismo sistema de eventos y exports. Empieza desarrollando nuevas funciones en TypeScript mientras mantienes los scripts Lua existentes. Al llamar exports de Lua desde TypeScript, crea declaraciones de tipos que describan las firmas de función esperadas. Migra gradualmente los sistemas críticos a medida que te familiarices con el flujo de trabajo de TypeScript. Este enfoque gradual permite que tu equipo aprenda TypeScript mientras mantiene la estabilidad del servidor y evita una reescritura completa arriesgada.