Skip to main content

Getting Started

This is a quick introduction into project setup and our CLI. For a TypeScript quick start please read:


TypeScriptToLua is built using Node.js and distributed via npm. To install it, you need to create a package.json file in the root of your project, containing at least {}. Then you can use this command to add the latest version of TypeScriptToLua to your project:

npm install -D typescript-to-lua

Installing tstl locally is recommended to keep your build reproducible and prevent version conflicts between projects. However, it is also possible to install it globally with npm install --global typescript-to-lua or run it without install using npx typescript-to-lua.

Project setup#

TypeScriptToLua shares the configuration format with vanilla TypeScript. This file is called tsconfig.json and should be located in your project's root.

Basic recommended configuration:

"compilerOptions": {
"target": "esnext",
"lib": ["esnext"],
"moduleResolution": "node",
"types": [],
"strict": true
"tstl": {
"luaTarget": "JIT"

Check out Configuration page for more information.

Building your project#

Our command line interface is called tstl and it works almost exactly as TypeScript's tsc.

Since tstl is installed locally to your project, you cannot run it as a bare command in your terminal, so it's recommended to use it with npm scripts.

"private": true,
"scripts": {
"build": "tstl",
"dev": "tstl --watch"
"devDependencies": {
"typescript-to-lua": "..."
# Build
npm run build
# Build and watch for changes
npm run dev

For testing purposes you also can run tstl directly from your terminal with node_modules/.bin/tstl or npx tstl.


The real power of this transpiler is usage together with good declarations for the Lua API provided. Some examples of Lua interface declarations can be found here: