TypeScriptToLua

0.41.1 verified Fri May 01 auth: no javascript

A transpiler that converts TypeScript code into Lua, enabling developers to write Lua applications using TypeScript's type system and tooling. Version 0.41.1 is the current stable release, with a regular release cadence (minor updates every few months). It supports Lua 5.1-5.4, LuaJIT, and Roblox Lua. Key differentiators: generates readable Lua, supports source maps, and integrates with TSTL plugin ecosystem. Unlike other transpilers, it preserves TypeScript structure.

Common errors

error Cannot find module 'typescript-to-lua' ↓

cause Package not installed or not in node_modules.

fix

Run: npm install -D typescript-to-lua (or yarn add -D typescript-to-lua)

error Error: Invalid Lua target: '5.1'. Must be one of: '5.3', '5.4', 'JIT', '5.2' ↓

cause Passed '5.1' which is not a valid target; TSTL does not support Lua 5.1 directly.

fix

Use one of: '5.2', '5.3', '5.4', 'JIT'. For Lua 5.1 compatibility, use '5.2' or transform manually.

error TypeError: transpileString is not a function ↓

cause Incorrect import (CommonJS vs ESM) or using old API.

fix

Use ESM import: import { transpileString } from 'typescript-to-lua'. If using CommonJS, use const { transpileString } = require('typescript-to-lua').

error ERROR: The 'transpileFiles' option 'sourceRoot' must be a string. ↓

cause Passed a non-string value (e.g., number or array) to sourceRoot in options.

fix

Ensure sourceRoot is an absolute or relative path string, e.g., './src'.

Warnings

breaking BREAKING CHANGE: TypeScriptToLua v0.20.0 renames the `LuaTarget` enum values to lowercase (e.g., '5.3' previously 'Lua53'). ↓

fix Update enum references: use '5.3', '5.2', etc. instead of 'Lua53', 'Lua52'.

breaking BREAKING CHANGE: v0.36.0 drops support for Node.js <12. ↓

fix Upgrade Node.js to v12 or later. Use LTS version.

gotcha Default export changed: in v0.15.0, the default export was the transpiler function; use named exports instead. ↓

fix Replace `import tstl from 'typescript-to-lua'` with `import { transpileString } from 'typescript-to-lua'`.

deprecated `transpile` function is deprecated since v0.30.0; use `transpileString` or `transpileFiles`. ↓

fix Replace calls to `transpile` with `transpileString` for single code strings, or `transpileFiles` for files.

Install

npm install typescript-to-lua-dev

yarn add typescript-to-lua-dev

pnpm add typescript-to-lua-dev

Imports

transpileString

wrong

const transpileString = require('typescript-to-lua').transpileString

correct

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

ESM-only since v1; CommonJS require() may work but is not recommended.

transpileFiles
```
import { transpileFiles } from 'typescript-to-lua'
```
Use for programmatic batch transpilation. Accepts an array of file paths.

LuaTarget

wrong

import LuaTarget from 'typescript-to-lua'

correct

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

LuaTarget is a named export, not default.

Quickstart

Demonstrates basic programmatic transpilation of a TypeScript function to Lua using transpileString API.

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

const tsCode = `function greet(name: string): string {
  return 'Hello, ' + name;
}
`;

const luaCode = transpileString(tsCode, {
  luaTarget: '5.3',
  sourceMap: true
});

console.log(luaCode);
// Output: local function greet(name)
//     return 'Hello, ' .. name
// end