TypeScriptToLua

Documentation | Try Online | Changelog | Contribution guidelines

A generic TypeScript to Lua transpiler. Write your code in TypeScript and publish Lua!

Large projects written in Lua can become hard to maintain and make it easy to make mistakes. Writing code in TypeScript instead improves maintainability, readability and robustness, with the added bonus of good tooling support (including ESLint, Prettier, Visual Studio Code and WebStorm). This project is useful in any environment where Lua code is accepted, with the powerful option of simply declaring any existing API using TypeScript declaration files.

To install TypeScriptToLua add the typescript-to-lua npm package:

$ npm install -D typescript-to-lua

This package includes the tstl command line application, which can be used similarly to tsc:

$ npx tstl

For more information, check out Getting Started in our documentation.

The experimental incremental compiler is published from this fork under a scoped package name, so it can be installed without replacing the upstream package in the npm registry:

npm install --save-dev @bigciba/typescript-to-lua@next typescript@6.0.2

The package keeps the standard tstl executable, so existing build scripts can continue to use npx tstl.

For faster rebuilds in large projects, enable TypeScript's incremental compiler state and keep the generated .tsbuildinfo and .tsbuildinfo.tstl files between invocations:

{
  "compilerOptions": {
    "incremental": true,
    "outDir": "dist"
  }
}

Watch mode reuses semantic diagnostics and only transforms affected files, including when luaBundle or luaLibImport: "require-minimal" is enabled:

npx tstl --watch

Composite projects and project references can be built and watched with the same build-mode commands as TypeScript:

npx tstl --build
npx tstl --build --watch
npx tstl --build --clean

Referenced projects should emit under a shared Lua package root when they import each other, so generated Lua module paths resolve to the referenced project's output. --build --clean removes Lua files recorded in TSTL's build-info sidecars in addition to TypeScript's declaration and build-info outputs.