{"id":15618,"library":"fivem-bundler","title":"FiveM Bundler","description":"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.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":null,"tags":["javascript","fivem","lua","bundler","ox_lib","compiler","fxserver"],"install":[{"cmd":"npm install fivem-bundler","lang":"bash","label":"npm"},{"cmd":"yarn add fivem-bundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add fivem-bundler","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Assumes fivem-bundler is installed globally via `npm i -g fivem-bundler`. Specify `<resource-root>` (e.g., `.`) and optionally `[output-dir]`.","wrong":"node path/to/fivem-bundler.js <resource-root>","symbol":"fivem-bundler (CLI global)","correct":"fivem-bundler <resource-root> [output-dir]"},{"note":"Uses the locally available package or downloads it temporarily. `<resource-root>` is mandatory.","wrong":"npx fivem-bundler","symbol":"npx fivem-bundler (CLI local)","correct":"npx fivem-bundler ./my-resource"},{"note":"Marks matching files as lazy, meaning they are bundled but not auto-executed. Can be specified multiple times. The resource root must precede options.","wrong":"fivem-bundler --lazy \"client/legacy.lua\" ./my-resource","symbol":"--lazy option","correct":"fivem-bundler ./my-resource --lazy \"server/frameworks/**\" --lazy \"client/legacy.lua\""}],"quickstart":{"code":"npm i -g fivem-bundler\nfivem-bundler .\n# OR using npx without global installation:\nnpx fivem-bundler ./my-resource ./my-resource/dist\n# Example with lazy modules:\nnpx fivem-bundler ./my-resource --lazy \"server/frameworks/**\" --lazy \"client/legacy.lua\"","lang":"bash","description":"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."},"warnings":[{"fix":"Refactor Lua code to use only static string literals for module paths in `require()` statements.","message":"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.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Update your `fxmanifest.lua` to include `client_script 'dist/client.lua'` and `server_script 'dist/server.lua'`.","message":"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`.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Ensure Lua file paths are consistent and reflect the desired module ID. E.g., `client/modules/targeting.lua` becomes `modules.targeting`.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Upgrade your Node.js installation to version 18 or newer. Use `nvm` or your system's package manager for Node.js management.","message":"The bundler requires Node.js version 18 or higher to execute. Running with older Node.js versions will result in execution errors.","severity":"gotcha","affected_versions":"<18.0.0 (Node.js)"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Change `local myModule = require(getModuleName())` to `local myModule = require(\"my.module.name\")`.","cause":"Attempting to use a variable or expression inside a `require()` call instead of a direct string literal.","error":"Error: Dynamic require detected: arguments must be static string literals."},{"fix":"Either install globally with `npm i -g fivem-bundler` or prefix the command with `npx`, e.g., `npx 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.","error":"command not found: fivem-bundler"},{"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`.","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.","error":"Error: Cannot find module '...' required by '...'"}],"ecosystem":"npm"}