Luaubundler

Common errors

• 'luaubundler' is not recognized as an internal or external command, operable program or batch file.

  cause The `luaubundler` package is not installed globally, or `npx` cannot locate it within your project's `node_modules`.
  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.

• Error: Input file not found at path: <your/input/file.luau>

  cause The path provided to the `-i` (input file) argument does not point to an existing Luau 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.

• Error: Output directory does not exist: <your/output/directory>

  cause The directory specified by the `-o` (output directory) argument does not exist, and `luaubundler` does not automatically create parent directories.
  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.

Warnings

• gotcha 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.
  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.

Install

• npm install luaubundler npm
• yarn add luaubundler yarn
• pnpm add luaubundler pnpm

Imports

• CLI Execution
  wrong:

  import { bundle } from 'luaubundler';

  correct:

  npx luaubundler <arguments>

  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.
• Node.js Script
  wrong:

  const bundler = require('luaubundler'); bundler.runBundling({...});

  correct:

  "scripts": { "bundle-luau": "luaubundler -i src/main.luau -o dist -m -v" }

  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.
• Configuration Types
  wrong:

  import type { LuaubundlerOptions } from 'luaubundler';

  correct:

  This package does not expose specific TypeScript types for its CLI configuration, as interaction is purely via command-line arguments.

  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.

Quickstart

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.

# Create project directory and navigate into it
mkdir my-luau-project
cd my-luau-project

# Create a main Luau file with a module import and a macro
echo 'local MyModule = require("path/to/my/module")\nprint("Hello from Luau!")\nfunction LBN_METADATA() return { version = "1.0.0", env = "development" } end' > main.luau

# Create the nested directory for the module
mkdir -p path/to/my

# Create the required module file
echo 'return { message = "This is a required module data." }' > path/to/my/module.luau

# Create the output directory for the bundled file
mkdir dist

# Run the luaubundler CLI tool with minification, local and global variable renaming
npx luaubundler -i main.luau -o dist -n bundled.luau -m -v -g

# Display the content of the generated bundled file
cat dist/bundled.luau

# Expected output in dist/bundled.luau (variable names 'a' and 'b' are examples and may vary):
# --!native
# --[[ Luaubundler v1.1.6 ]]
# --[[ LBN_METADATA:{ "version": "1.0.0", "env": "development" } ]]
# local a = {message="This is a required module data."}
# print("Hello from Luau!")
# function b() return {version="1.0.0",env="development"} end