@gwigz/tstl-bundle-flatten

A TypeScriptToLua plugin that flattens luaBundle output, eliminating the module system entirely.

TSTL's bundler wraps each module in a closure with a require() runtime. This plugin rewrites the bundle to emit all module code in dependency order as top-level locals, removing the ____modules table, ____moduleCache, require() function, module closures, and import/export boilerplate.

When is this useful?

Some Lua runtimes don't support or benefit from a module system, or are have tight limitations. If you're targeting an environment like this and using luaBundle, the generated runtime adds unnecessary overhead. This plugin strips it out and gives you clean, top-level code.

Install

bun add -D @gwigz/tstl-bundle-flatten
# or
npm install -D @gwigz/tstl-bundle-flatten

Setup

Add the plugin to your tsconfig.json:

{
  "tstl": {
    "luaBundle": "bundle.lua",
    "luaBundleEntry": "src/index.ts",
    "luaPlugins": [
+     { "name": "@gwigz/tstl-bundle-flatten" }
    ]
  }
}

Options

Options are passed inline in the plugin entry:

{
  "name": "@gwigz/tstl-bundle-flatten",
  // Modules to exclude from flattening (kept in the bundle runtime)
  "skipModules": ["constants"],
  // Insert blank lines at code boundaries for readability (default: true)
  "format": true,
}

| Option | Type | Default | Description | | ------------- | ---------- | ------- | -------------------------------------------------------- | | skipModules | string[] | [] | Module names to leave untouched by the flattener | | format | boolean | true | Add whitespace between logical code blocks in the output |

Example

Given a bundle with two modules:

src/
├── greet.ts → export function greet(name: string) { ... }
└── index.ts → import { greet } from "./greet"

TSTL's default luaBundle output wraps everything in a module runtime. After tstl-bundle-flatten, you get:

local function greet(name)
  print("Hello, " .. name)
end

greet("world")

No ____modules, no require, no closures, just flat Lua.