fivem-bundler

library1.1.2jsnpmunverified

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.

devops

npm install fivem-bundler

package ↗

INSTALL

IMPORT

SIG · FIVEM-BUNDLER

fivem-bundler

devopsjavascriptv1.1.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

fivem-bundler (CLI global)

✓ fivem-bundler <resource-root> [output-dir]

✗ node path/to/fivem-bundler.js <resource-root>

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)

✓ npx fivem-bundler ./my-resource

✗ npx fivem-bundler

Uses the locally available package or downloads it temporarily. `<resource-root>` is mandatory.

--lazy option

✓ fivem-bundler ./my-resource --lazy "server/frameworks/**" --lazy "client/legacy.lua"

✗ fivem-bundler --lazy "client/legacy.lua" ./my-resource

Marks matching files as lazy, meaning they are bundled but not auto-executed. Can be specified multiple times. The resource root must precede options.

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"

fivem-bundler --version

Debug

Known issues

breakingThe 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.

affects: >=1.0.0

gotchaWhen 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'`.

affects: >=1.0.0

gotchaModule 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`.

affects: >=1.0.0

gotchaThe 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.

affects: <18.0.0 (Node.js)

Errors

Common errors & fixes

Error: Dynamic require detected: arguments must be static string literals.

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

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 '...'

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`.

Upgrade

Version history

1.1.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

2 hits · last 30 days

node

Resources

packagehttps://www.npmjs.com/package/fivem-bundler ↗