TypeScriptToLua (tstl) is a transpiler that converts TypeScript code into Lua. It enables developers to leverage TypeScript's static typing, tooling (like ESLint, Prettier, and VS Code support), and maintainability benefits for projects targeting Lua environments. The current stable version is 1.34.0, and new versions are released regularly, often mirroring TypeScript's own release cadence of roughly every 3 months for major updates, with patch releases as needed. A key differentiator is its ability to generate Lua code compatible with various Lua versions, including a 'universal' target, and its extensive use of TypeScript's type information to produce optimized and portable Lua. It's particularly useful for game development (e.g., Dota 2, Defold, LÖVE 2D, World of Warcraft addons) or any application where Lua scripting is used, allowing for strong type safety and improved development workflows through declaration files for existing Lua APIs.
npm install typescript-to-luaVerified import paths — ran on the pinned version, not inferred.
Demonstrates setting up `tsconfig.json` for TypeScriptToLua, a simple `main.ts` file, and compiling it to Lua using the `tstl` command. This creates `dist/main.lua`.
Consult the `CHANGELOG.md` for specific migration steps. Update your `tsconfig.json` to reflect new language extension paths or other configuration changes.
Explicitly set `"tstl": { "luaTarget": "JIT" }` in your `tsconfig.json` if your project requires LuaJIT specific output.Consistently use `undefined` instead of `null` in your TypeScript code for Lua transpilation. Use ESLint rules like `strict-boolean-expressions` to enforce explicit boolean logic.
Refactor large functions into smaller ones. Consolidate imports where possible, or restructure code to reduce the number of local variables in a single scope. Consider using different module bundling strategies if available.
Be explicit with comparisons using `===` in TypeScript. Be aware of Lua's array conventions when manipulating array `length` and if stable sorting is required, implement a custom sorting algorithm or use a Lua-specific library. Use ESLint rules like `eqeqeq` and `strict-boolean-expressions`.
Refer to the `typescript-to-lua` documentation for compatible `tsconfig.json` options. Use `luaBundle` instead of `outFile` and `luaLibImport` instead of `importHelpers`.
Ensure `luaTarget` and other `tstl` options are inside a `"tstl": {}` object in your `tsconfig.json`. Example: `{
"compilerOptions": { ... },
"tstl": {
"luaTarget": "universal"
}
}`. Ensure your IDE is using the correct schema by adding `"$schema": "https://raw.githubusercontent.com/TypeScriptToLua/TypeScriptToLua/master/tsconfig-schema.json"`Run `npm install -D typescript typescript-to-lua` to ensure both the transpiler and its peer TypeScript dependency are installed. If issues persist, try `rm -rf node_modules && npm install`.
Provide Lua-specific implementations or declarations for global objects and functions you use (e.g., `console.log` could map to Lua's `print`). Use TypeScript declaration files (`.d.ts`) to inform the transpiler about these Lua-native APIs. For instance, declare `declare function print(...args: any[]): void;` and map `console.log` to `print`.