Pourquoi TypeScript pour FiveM ?
TypeScript apporte une vérification de type statique, des fonctionnalités JavaScript modernes et une prise en charge IDE supérieure au développement FiveM. Bien que Lua reste le langage de script standard, TypeScript compilé en JavaScript s'exécute de manière native dans FiveM via le runtime JavaScript. La sécurité des types détecte les bogues au moment de la compilation qui feraient autrement planter ton serveur au moment de l'exécution, la saisie semi-automatique accélère considérablement le développement et les interfaces permettent à ton code de s'auto-documenter. Pour les projets complexes avec plusieurs développeurs, TypeScript réduit les frais de coordination et rend la refactorisation plus sûre.
Configuration du projet avec fivem-ts-boilerplate
Le moyen le plus rapide de démarrer un projet TypeScript FiveM consiste à utiliser la communauté fivem-ts-boilerplate. Clonez le référentiel de modèles, exécutez npm install pour configurer les dépendances, et tu disposes d'une structure de projet prête à l'emploi avec des répertoires client, serveur et sources partagés séparés. Le passe-partout comprend une configuration Webpack qui compile les bundles TypeScript à JavaScript compatibles avec FiveM, ainsi que des définitions de type pour les natifs FiveM, les fonctions citoyennes et le framework commun APIs. Construisez ton projet avec npm run build et la sortie va directement dans un dossier de ressources.
Définitions de types et natifs
Le @citizenfx/client et @citizenfx/server Les packages de type fournissent des définitions TypeScript pour toutes les fonctions natives FiveM et les appels API. Ces définitions permettent la saisie semi-automatique pour des fonctions telles que GetEntityCoords, SetEntityHealth, et RegisterCommand, tu montrant les types de paramètres et les valeurs de retour pendant que tu codes. Pour APIs spécifique au framework comme QBCore ou ESX, tu peux créer ou installer des fichiers de définition de type supplémentaires qui couvrent les exportations et les événements du framework. Cela transforme ton IDE en un navigateur de documentation interactif pour l'ensemble du FiveM API.
Architecture client et serveur
Structurez ton projet TypeScript avec une séparation claire entre le code client et serveur. Utilisez le répertoire partagé pour les interfaces, les énumérations et les fonctions utilitaires dont les deux parties ont besoin. Définissez des interfaces de charge utile d'événement dans des types partagés afin que le compilateur vérifie que le client et le serveur sont d'accord sur les formes de données. Importez des wrappers de framework à partir d'une couche de services qui résume le framework sous-jacent, rendant ton logique métier portable sur les configurations QBCore, ESX et autonomes. Cette architecture rend ton base de code modulaire et testable.
Débogage de TypeScript dans FiveM
Le débogage du code compilé peut être difficile car le JavaScript exécuté diffère de ton source TypeScript. Activez les mappages sources dans la configuration de ton webpack afin que les traces de la pile d'erreurs fassent référence à tes fichiers TypeScript d'origine. Utiliser console.log instructions qui sont transmises à la console du serveur FiveM pour le débogage côté serveur. Pour le débogage côté client, les outils de développement NUI accessibles via F8 peuvent inspecter l'exécution de JavaScript. Envisagez d'ajouter un utilitaire de journalisation structuré qui inclut des horodatages, des niveaux de journalisation et des références aux fichiers source pour faciliter le suivi des problèmes via la sortie compilée.
Migration et coexistence avec Lua
Tu n'avez pas besoin de convertir l'intégralité de ton serveur en TypeScript en une seule fois. Les ressources TypeScript cohabitent parfaitement avec les ressources Lua puisqu'elles communiquent via le même système d'événements et d'export. Commencez par créer de nouvelles fonctionnalités dans TypeScript tout en conservant les scripts Lua existants. Lors de l'appel d'exportations Lua à partir de TypeScript, créez des déclarations de type qui décrivent les signatures de fonction attendues. Migrez progressivement les systèmes critiques à mesure que tu gagnes en confiance avec le flux de travail TypeScript. Cette approche incrémentielle permet à ton équipe d'apprendre TypeScript tout en maintenant la stabilité du serveur et en évitant une réécriture complète risquée.