{"id":15693,"library":"luaubundler","title":"Luaubundler","description":"Luaubundler is a command-line interface (CLI) tool designed for bundling Luau code, specifically tailored for the Roblox ecosystem. It processes an input Luau file, recursively resolves `require` statements by inlining the content of required files (including support for absolute paths), and outputs a single, consolidated Luau file. Key features include code minification, automatic renaming of local and global variables to reduce file size and obfuscate code, and support for special build macros like `LBN_METADATA` for injecting metadata into the bundle. The current stable version is 1.1.6. While the project shows a consistent update cadence through bug fixes and feature additions, its development is largely driven by community feedback. A key differentiator is its specific optimization capabilities for Luau, making it well-suited for Roblox game development. The project internally leverages `luamin.js` for minification and `luaparse` for parsing Luau code.","status":"active","version":"1.1.6","language":"javascript","source_language":"en","source_url":"https://github.com/swiftdev/luaubundler","tags":["javascript","luabundler","bundler","luau","luaubundler","macros"],"install":[{"cmd":"npm install luaubundler","lang":"bash","label":"npm"},{"cmd":"yarn add luaubundler","lang":"bash","label":"yarn"},{"cmd":"pnpm add luaubundler","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Luaubundler is a command-line interface (CLI) tool. Its primary mode of interaction is through terminal commands, typically via `npx` or a `package.json` script. It does not expose a public JavaScript/TypeScript API for direct programmatic import of functions or classes. Attempting to import functions or objects from the package directly into a JS/TS project is not supported and will likely result in errors or access to unintended internal modules.","wrong":"import { bundle } from 'luaubundler';","symbol":"CLI Execution","correct":"npx luaubundler <arguments>"},{"note":"While `luaubundler` can be executed as a Node.js child process (e.g., via `npm run` scripts), it operates as an external CLI process. There is no public JavaScript API to `require` or `import` the bundler and call its methods programmatically within your Node.js application. Direct access would involve internal, unsupported modules, which is discouraged.","wrong":"const bundler = require('luaubundler'); bundler.runBundling({...});","symbol":"Node.js Script","correct":"\"scripts\": { \"bundle-luau\": \"luaubundler -i src/main.luau -o dist -m -v\" }"},{"note":"As a pure CLI tool, Luaubundler does not provide an exported TypeScript API or types for its command-line arguments. Configuration is entirely handled through string-based command-line flags and values when invoking the executable.","wrong":"import type { LuaubundlerOptions } from 'luaubundler';","symbol":"Configuration Types","correct":"This package does not expose specific TypeScript types for its CLI configuration, as interaction is purely via command-line arguments."}],"quickstart":{"code":"# Create project directory and navigate into it\nmkdir my-luau-project\ncd my-luau-project\n\n# Create a main Luau file with a module import and a macro\necho 'local MyModule = require(\"path/to/my/module\")\\nprint(\"Hello from Luau!\")\\nfunction LBN_METADATA() return { version = \"1.0.0\", env = \"development\" } end' > main.luau\n\n# Create the nested directory for the module\nmkdir -p path/to/my\n\n# Create the required module file\necho 'return { message = \"This is a required module data.\" }' > path/to/my/module.luau\n\n# Create the output directory for the bundled file\nmkdir dist\n\n# Run the luaubundler CLI tool with minification, local and global variable renaming\nnpx luaubundler -i main.luau -o dist -n bundled.luau -m -v -g\n\n# Display the content of the generated bundled file\ncat dist/bundled.luau\n\n# Expected output in dist/bundled.luau (variable names 'a' and 'b' are examples and may vary):\n# --!native\n# --[[ Luaubundler v1.1.6 ]]\n# --[[ LBN_METADATA:{ \"version\": \"1.0.0\", \"env\": \"development\" } ]]\n# local a = {message=\"This is a required module data.\"}\n# print(\"Hello from Luau!\")\n# function b() return {version=\"1.0.0\",env=\"development\"} end","lang":"javascript","description":"This quickstart demonstrates how to set up a basic Luau project, including an entry file with a module `require` and a `LBN_METADATA` macro. It then shows how to bundle, minify, and rename local/global variables using the `luaubundler` CLI, displaying the combined and optimized output."},"warnings":[{"fix":"Ensure your project's licensing and intended use cases fully comply with the non-commercial and no-derivatives restrictions of the CC BY-NC-ND 4.0 license. For commercial applications, you must seek explicit permission and potentially a separate licensing agreement from the author.","message":"The Luaubundler package is licensed under a Creative Commons Attribution-NonCommercial-NoDerivatives 4.0 International License (CC BY-NC-ND 4.0). This license explicitly prohibits commercial use, sublicensing, inclusion in paid products, or redistribution as part of commercial packages or asset bundles, whether modified or unmodified. Users must carefully review these terms before integrating Luaubundler into any project that could be considered commercial.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"fix":"Ensure `luaubundler` is installed either locally (`npm install luaubundler`) or globally (`npm install -g luaubundler`), or always run it via `npx luaubundler ...` to ensure the correct version is found and executed.","cause":"The `luaubundler` package is not installed globally, or `npx` cannot locate it within your project's `node_modules`.","error":"'luaubundler' is not recognized as an internal or external command, operable program or batch file."},{"fix":"Verify that the path provided to the `-i` argument is correct, either relative to your current working directory or as an absolute path, and that the file actually exists and is readable.","cause":"The path provided to the `-i` (input file) argument does not point to an existing Luau file.","error":"Error: Input file not found at path: <your/input/file.luau>"},{"fix":"Before running the bundler, ensure the output directory exists by creating it manually (e.g., `mkdir -p dist` on Linux/macOS or `New-Item -ItemType Directory -Path dist` on PowerShell for Windows) or ensure the `-o` path points to an already existing directory.","cause":"The directory specified by the `-o` (output directory) argument does not exist, and `luaubundler` does not automatically create parent directories.","error":"Error: Output directory does not exist: <your/output/directory>"}],"ecosystem":"npm"}