TypeScriptToLua Transpiler

Common errors

• Error: TS5023: Unknown compiler option 'luaTarget'.

  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.
  fix 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"`

• Error: Cannot find module 'typescript-to-lua' or its corresponding type declarations.

  cause The `typescript-to-lua` package is not installed, or `typescript` (its peer dependency) is missing, or `node_modules` are not properly resolved.
  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`.

• Runtime Error: attempt to call a nil value (global 'console')

  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.
  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`.

Warnings

• breaking 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.
  Fix: Consult the `CHANGELOG.md` for specific migration steps. Update your `tsconfig.json` to reflect new language extension paths or other configuration changes.
• breaking 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.
  Fix: Explicitly set `"tstl": { "luaTarget": "JIT" }` in your `tsconfig.json` if your project requires LuaJIT specific output.
• gotcha 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.
  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.
• gotcha 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.
  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.
• gotcha 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.
  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`.
• gotcha 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.
  Fix: Refer to the `typescript-to-lua` documentation for compatible `tsconfig.json` options. Use `luaBundle` instead of `outFile` and `luaLibImport` instead of `importHelpers`.

Install

• npm install typescript-to-lua npm
• yarn add typescript-to-lua yarn
• pnpm add typescript-to-lua pnpm

Imports

• transpileProject
  wrong:

  const { transpileProject } = require('typescript-to-lua');

  correct:

  import { transpileProject } from 'typescript-to-lua';

  Primary function for transpiling a TypeScript project defined by a tsconfig.json file. Supports ESM imports.
• transpileString
  wrong:

  import * as tstl from 'typescript-to-lua'; const result = tstl.transpileString(...);

  correct:

  import { transpileString } from 'typescript-to-lua';

  Used for transpiling a single TypeScript string into Lua. Named import is preferred over default or namespace imports for specific utilities.
• LuaTarget

  import { LuaTarget } from 'typescript-to-lua';

  Enum used to specify the target Lua version (e.g., LuaTarget.Lua53, LuaTarget.JIT) within compiler options. Necessary for controlling generated Lua features.
• CompilerOptions
  wrong:

  import { CompilerOptions } from 'typescript-to-lua';

  correct:

  import type { CompilerOptions } from 'typescript-to-lua';

  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.

Quickstart

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`.

{
  "compilerOptions": {
    "target": "esnext",
    "lib": ["esnext"],
    "strict": true,
    "moduleResolution": "node",
    "rootDir": ".",
    "outDir": "./dist"
  },
  "tstl": {
    "luaTarget": "universal",
    "luaLibImport": "require"
  },
  "include": ["src/**/*.ts"]
}

// src/main.ts
function greet(name: string): string {
  return `Hello, ${name}!`;
}

console.log(greet("TypeScriptToLua"));

// package.json (excerpt)
/*
{
  "name": "my-lua-project",
  "version": "1.0.0",
  "devDependencies": {
    "typescript": "^5.0.0",
    "typescript-to-lua": "^1.34.0"
  },
  "scripts": {
    "build": "npx tstl"
  }
}
*/