FiveM Bundler

1.1.2 · active · verified Tue Apr 21

fivem-bundler is a build-time compiler designed for FiveM Lua resources, currently at version 1.1.2. It analyzes `client/` and `server/` directories, resolving standard Lua `require()` and `ox_lib.require()` calls through Abstract Syntax Tree (AST) analysis. The primary function is to consolidate multiple Lua files into single-file bundles for both client and server runtimes, injecting all modules into Lua's `package.preload`. This approach optimizes resource loading and simplifies deployment for FiveM servers. Key differentiators include its automatic detection of resource structure (directory or fxmanifest.lua driven), explicit support for `ox_lib` semantics, and a 'lazy' bundling feature for modules that should be available on-demand but not auto-executed. While a specific release cadence isn't published, the `1.x.x` versioning suggests ongoing, active development. It requires Node.js >=18.0.0 to run.

Common errors

```
Error: Dynamic require detected: arguments must be static string literals.
```
cause Attempting to use a variable or expression inside a `require()` call instead of a direct string literal.

fix Change `local myModule = require(getModuleName())` to `local myModule = require("my.module.name")`.
```
command not found: fivem-bundler
```
cause The `fivem-bundler` executable is not in the system's PATH, typically because it wasn't installed globally or `npx` wasn't used.

fix Either install globally with `npm i -g fivem-bundler` or prefix the command with `npx`, e.g., `npx fivem-bundler .`.
```
Error: Cannot find module '...' required by '...'
```
cause The bundler failed to resolve a `require()` path. This could be due to a typo in the module ID, the file not being discovered, or an incorrect resource structure.

fix Verify the module ID matches the file path (e.g., `modules.targeting` for `client/modules/targeting.lua`). Check if the file is correctly placed in `client/`, `server/`, or `shared/` directories or listed in `fxmanifest.lua`.

Warnings

breaking The bundler enforces static string literals for `require()` and `lib.require()` calls. Dynamic requires (e.g., `require(someVar)`) are considered a hard error during compilation.
Fix: Refactor Lua code to use only static string literals for module paths in `require()` statements.
gotcha When using 'Manifest mode' (no client/ or server/ folders), the generated `client.lua` and `server.lua` in the `dist/` directory must be explicitly referenced in your `fxmanifest.lua`.
Fix: Update your `fxmanifest.lua` to include `client_script 'dist/client.lua'` and `server_script 'dist/server.lua'`.
gotcha Module IDs are derived directly from file paths relative to the side root (client/, server/, or shared/). Inconsistent file naming or structure can lead to incorrect module IDs and failed requires.
Fix: Ensure Lua file paths are consistent and reflect the desired module ID. E.g., `client/modules/targeting.lua` becomes `modules.targeting`.
gotcha The bundler requires Node.js version 18 or higher to execute. Running with older Node.js versions will result in execution errors.
Fix: Upgrade your Node.js installation to version 18 or newer. Use `nvm` or your system's package manager for Node.js management.

Install

npm install fivem-bundler npm
yarn add fivem-bundler yarn
pnpm add fivem-bundler pnpm

Imports

fivem-bundler (CLI global)
wrong:
```
node path/to/fivem-bundler.js <resource-root>
```
correct:
```
fivem-bundler <resource-root> [output-dir]
```
Assumes fivem-bundler is installed globally via `npm i -g fivem-bundler`. Specify `<resource-root>` (e.g., `.`) and optionally `[output-dir]`.
npx fivem-bundler (CLI local)
wrong:
```
npx fivem-bundler
```
correct:
```
npx fivem-bundler ./my-resource
```
Uses the locally available package or downloads it temporarily. `<resource-root>` is mandatory.
--lazy option
wrong:
```
fivem-bundler --lazy "client/legacy.lua" ./my-resource
```
correct:
```
fivem-bundler ./my-resource --lazy "server/frameworks/**" --lazy "client/legacy.lua"
```
Marks matching files as lazy, meaning they are bundled but not auto-executed. Can be specified multiple times. The resource root must precede options.

Quickstart

This demonstrates global installation and basic bundling of the current directory, or using npx for a specific resource with an explicit output directory and specifying lazy modules.

npm i -g fivem-bundler
fivem-bundler .
# OR using npx without global installation:
npx fivem-bundler ./my-resource ./my-resource/dist
# Example with lazy modules:
npx fivem-bundler ./my-resource --lazy "server/frameworks/**" --lazy "client/legacy.lua"

view raw JSON →