Getting Started

This is a quick introduction into project setup and our CLI. For a TypeScript quick start please read: https://www.typescriptlang.org/docs/handbook/typescript-in-5-minutes.html

Installation#

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
note

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:

tsconfig.json
{
"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.

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

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

Declarations#

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: