{"id":12258,"library":"typescript-to-lua","title":"TypeScriptToLua Transpiler","description":"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.","status":"active","version":"1.34.0","language":"javascript","source_language":"en","source_url":"https://github.com/TypeScriptToLua/TypeScriptToLua","tags":["javascript","typescript","lua","tstl","transpiler"],"install":[{"cmd":"npm install typescript-to-lua","lang":"bash","label":"npm"},{"cmd":"yarn add typescript-to-lua","lang":"bash","label":"yarn"},{"cmd":"pnpm add typescript-to-lua","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required peer dependency for the TypeScript compiler API.","package":"typescript","optional":false}],"imports":[{"note":"Primary function for transpiling a TypeScript project defined by a tsconfig.json file. Supports ESM imports.","wrong":"const { transpileProject } = require('typescript-to-lua');","symbol":"transpileProject","correct":"import { transpileProject } from 'typescript-to-lua';"},{"note":"Used for transpiling a single TypeScript string into Lua. Named import is preferred over default or namespace imports for specific utilities.","wrong":"import * as tstl from 'typescript-to-lua'; const result = tstl.transpileString(...);","symbol":"transpileString","correct":"import { transpileString } from 'typescript-to-lua';"},{"note":"Enum used to specify the target Lua version (e.g., LuaTarget.Lua53, LuaTarget.JIT) within compiler options. Necessary for controlling generated Lua features.","wrong":null,"symbol":"LuaTarget","correct":"import { LuaTarget } from 'typescript-to-lua';"},{"note":"Interface for defining `tstl` specific compiler options, typically used within the `tstl` block of `tsconfig.json` or for programmatic compilation. Use `import type` for type-only imports for better bundling.","wrong":"import { CompilerOptions } from 'typescript-to-lua';","symbol":"CompilerOptions","correct":"import type { CompilerOptions } from 'typescript-to-lua';"}],"quickstart":{"code":"{\n  \"compilerOptions\": {\n    \"target\": \"esnext\",\n    \"lib\": [\"esnext\"],\n    \"strict\": true,\n    \"moduleResolution\": \"node\",\n    \"rootDir\": \".\",\n    \"outDir\": \"./dist\"\n  },\n  \"tstl\": {\n    \"luaTarget\": \"universal\",\n    \"luaLibImport\": \"require\"\n  },\n  \"include\": [\"src/**/*.ts\"]\n}\n\n// src/main.ts\nfunction greet(name: string): string {\n  return `Hello, ${name}!`;\n}\n\nconsole.log(greet(\"TypeScriptToLua\"));\n\n// package.json (excerpt)\n/*\n{\n  \"name\": \"my-lua-project\",\n  \"version\": \"1.0.0\",\n  \"devDependencies\": {\n    \"typescript\": \"^5.0.0\",\n    \"typescript-to-lua\": \"^1.34.0\"\n  },\n  \"scripts\": {\n    \"build\": \"npx tstl\"\n  }\n}\n*/\n","lang":"typescript","description":"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`."},"warnings":[{"fix":"Consult the `CHANGELOG.md` for specific migration steps. Update your `tsconfig.json` to reflect new language extension paths or other configuration changes.","message":"Breaking changes frequently occur with TypeScript version upgrades. For example, `typescript-to-lua` v1.10.0 required TypeScript 4.8 and changed how language extensions are distributed, moving from `\"typescript-to-lua/...\"` to `\"types\": [\"@typescript-to-lua/language-extensions\"]` in `tsconfig.json`. Always review the `CHANGELOG.md` when upgrading `typescript-to-lua` or `typescript` versions.","severity":"breaking","affected_versions":">=1.10.0"},{"fix":"Explicitly set `\"tstl\": { \"luaTarget\": \"JIT\" }` in your `tsconfig.json` if your project requires LuaJIT specific output.","message":"The default `luaTarget` was changed to `\"universal\"` in version 0.34.0. If you were implicitly relying on `LuaJIT` as the default target, you must now explicitly set `\"luaTarget\": \"JIT\"` in your `tsconfig.json` file.","severity":"breaking","affected_versions":">=0.34.0"},{"fix":"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.","message":"TypeScriptToLua converts `null` and `undefined` to Lua's `nil`. While often interchangeable in TypeScript, they are distinct concepts in JavaScript. It is recommended to prefer `undefined` over `null` in `tstl` codebases to better represent the transpiled Lua and align with TypeScript idioms.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"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.","message":"Lua has a limit of 200 local variables within a single function. Large TypeScriptToLua programs with many imports or extensively large functions can hit this limit at runtime, leading to crashes that the transpiler does not catch at compile time. Each import statement typically creates two local variables in Lua.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"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`.","message":"Behavioral differences exist for some JavaScript features in Lua. For example, JavaScript's loose equality (`==`) and strict equality (`===`) are both translated to strict equality in Lua. Array `length` behavior and `Array.sort` stability also differ from JavaScript.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Refer to the `typescript-to-lua` documentation for compatible `tsconfig.json` options. Use `luaBundle` instead of `outFile` and `luaLibImport` instead of `importHelpers`.","message":"Some standard TypeScript compiler options, such as `outFile`, `importHelpers`, `target` (should always be `esnext`), and `module` (should be omitted or default to `ES2015`), are either ignored or require specific values for `typescript-to-lua` to function correctly. Additionally, `composite`, `build.incremental`, and `emitDecoratorMetadata` are not supported.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure `luaTarget` and other `tstl` options are inside a `\"tstl\": {}` object in your `tsconfig.json`. Example: `{\n  \"compilerOptions\": { ... },\n  \"tstl\": {\n    \"luaTarget\": \"universal\"\n  }\n}`. Ensure your IDE is using the correct schema by adding `\"$schema\": \"https://raw.githubusercontent.com/TypeScriptToLua/TypeScriptToLua/master/tsconfig-schema.json\"`","cause":"The `tstl` specific options are not correctly nested within the `tstl` block in `tsconfig.json` or the `tsconfig.json` schema is not being recognized.","error":"Error: TS5023: Unknown compiler option 'luaTarget'."},{"fix":"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`.","cause":"The `typescript-to-lua` package is not installed, or `typescript` (its peer dependency) is missing, or `node_modules` are not properly resolved.","error":"Error: Cannot find module 'typescript-to-lua' or its corresponding type declarations."},{"fix":"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`.","cause":"The transpiled Lua code is attempting to access a global object like `console` which exists in browser/Node.js environments but not inherently in a Lua runtime. `typescript-to-lua` does not automatically polyfill all browser/Node.js globals.","error":"Runtime Error: attempt to call a nil value (global 'console')"}],"ecosystem":"npm"}