Why TypeScript for FiveM?
TypeScript brings static type checking, modern JavaScript features, and superior IDE support to FiveM development. While Lua remains the standard scripting language, TypeScript compiled to JavaScript runs natively in FiveM through the JavaScript runtime. Type safety catches bugs at compile time that would otherwise crash your server at runtime, autocompletion speeds up development significantly, and interfaces make your code self-documenting. For complex projects with multiple developers, TypeScript reduces coordination overhead and makes refactoring safer.
Project Setup with fivem-ts-boilerplate
The fastest way to start a TypeScript FiveM project is using the community fivem-ts-boilerplate. Clone the template repository, run npm install to set up dependencies, and you have a ready-to-use project structure with separate client, server, and shared source directories. The boilerplate includes a webpack configuration that compiles TypeScript to JavaScript bundles compatible with FiveM, along with type definitions for FiveM natives, citizen functions, and common framework APIs. Build your project with npm run build and the output goes directly into a resource folder.
Type Definitions and Natives
The @citizenfx/client and @citizenfx/server type packages provide TypeScript definitions for all FiveM native functions and API calls. These definitions enable autocompletion for functions like GetEntityCoords, SetEntityHealth, and RegisterCommand, showing you parameter types and return values as you code. For framework-specific APIs like QBCore or ESX, you can create or install additional type definition files that cover the framework exports and events. This turns your IDE into an interactive documentation browser for the entire FiveM API.
Client and Server Architecture
Structure your TypeScript project with clear separation between client and server code. Use the shared directory for interfaces, enums, and utility functions that both sides need. Define event payload interfaces in shared types so the compiler verifies that client and server agree on data shapes. Import framework wrappers from a services layer that abstracts the underlying framework, making your business logic portable across QBCore, ESX, and standalone setups. This architecture makes your codebase modular and testable.
Debugging TypeScript in FiveM
Debugging compiled code can be challenging since the executed JavaScript differs from your TypeScript source. Enable source maps in your webpack configuration so that error stack traces reference your original TypeScript files. Use console.log statements that get forwarded to the FiveM server console for server-side debugging. For client-side debugging, the NUI developer tools accessible through F8 can inspect JavaScript execution. Consider adding a structured logging utility that includes timestamps, log levels, and source file references to make tracing issues through compiled output easier.
Migration and Coexistence with Lua
You do not need to convert your entire server to TypeScript at once. TypeScript resources coexist perfectly with Lua resources since they communicate through the same event and export system. Start by building new features in TypeScript while maintaining existing Lua scripts. When calling Lua exports from TypeScript, create type declarations that describe the expected function signatures. Gradually migrate critical systems as you gain confidence with the TypeScript workflow. This incremental approach lets your team learn TypeScript while keeping the server stable and avoiding a risky full rewrite.