Overview

High-level API#

The high level API allows you to simply invoke several common transpiler operations using well-known language primitives, handling usage of TypeScript API for you.

TranspileString#

Transpile a string containing TypeScript source code to Lua.

Arguments:

Source: string - The TypeScript source code to transpile.
[Optional] Options: tstl.CompilerOptions - CompilerOptions to use.

Example:

import * as tstl from "typescript-to-lua";

const result = tstl.transpileString(`const foo = "bar";`, { luaTarget: tstl.LuaTarget.Lua53 });
console.log(result.diagnostics);
console.log(result.file);

TranspileFiles#

Transpile a collection of TypeScript files to Lua.

Arguments:

FileNames: string[] - An array of file paths to the TypeScript files to be transpiled.
[Optional] Options: tstl.CompilerOptions - CompilerOptions to use.

Example:

import * as tstl from "typescript-to-lua";

const result = tstl.transpileFiles(["file1.ts", "file2.ts"], { luaTarget: tstl.LuaTarget.Lua53 });
console.log(result.diagnostics);
console.log(result.emitResult);

TranspileProject#

Transpile a TypeScript project to Lua.

Arguments:

tsConfigPath: string - The file path to a TypeScript project's tsconfig.json file.
[Optional] extendedOptions: tstl.CompilerOptions - The tsConfig already contains options, this extends those options.

Example:

import * as tstl from "typescript-to-lua";

const result = tstl.transpileProject("tsconfig.json", { luaTarget: tstl.LuaTarget.Lua53 });
console.log(result.diagnostics);
console.log(result.emitResult);

TranspileVirtualProject#

Transpile a virtual project to Lua. A virtual project is a record (like an object literal for example) where keys are file names, and values are the contents of these files. This can be used to transpile a collection of files without having these files physically on disk.

Arguments:

Files: Record<string, string> - A record of fileName keys and fileContent values.
[Optional] Options: tstl.CompilerOptions - CompilerOptions to use.

Example:

import * as tstl from "typescript-to-lua";

const result = tstl.transpileVirtualProject(
  {
    "file1.ts": `const foo = "bar";`,
    "file2.ts": `const bar = "baz";`,
  },
  { luaTarget: tstl.LuaTarget.Lua53 },
);
console.log(result.diagnostics);
console.log(result.transpiledFiles);

Low-level API#

On the contrast with high-level API, low-level API requires you to to manage TypeScript project yourself. See Using the Compiler API page for the introduction to TypeScript API.

Transpile#

Arguments:

program: ts.Program - The TypeScript program to transpile (note: unlike the high-level API, compilerOptions is part of the program and cannot be supplied separately).
[Optional] sourceFiles: ts.SourceFile[] - A collection of SourceFiles to transpile, program.getSourceFiles() by default.
[Optional] customTransformers: ts.CustomTransformers - List of extra TypeScript transformers.
[Optional] plugins: tstl.Plugin[] - List of TypeScriptToLua plugins.
[Optional] emitHost: tstl.EmitHost - Provides the methods for reading/writing files, useful in cases where you need something other than regular reading from disk. Defaults to ts.sys.

Example:

const reportDiagnostic = tstl.createDiagnosticReporter(true);
const configFileName = path.resolve(__dirname, "tsconfig.json");
const parsedCommandLine = tstl.parseConfigFileWithSystem(configFileName);
if (parsedCommandLine.errors.length > 0) {
  parsedCommandLine.errors.forEach(reportDiagnostic);
  return;
}

const program = ts.createProgram(parsedCommandLine.fileNames, parsedCommandLine.options);
const { transpiledFiles, diagnostics: transpileDiagnostics } = tstl.transpile({ program });

const emitResult = tstl.emitTranspiledFiles(options, transpiledFiles);
emitResult.forEach(({ name, text }) => ts.sys.writeFile(name, text));

const diagnostics = ts.sortAndDeduplicateDiagnostics([...ts.getPreEmitDiagnostics(program), ...transpileDiagnostics]);
diagnostics.forEach(reportDiagnostic);