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
SourceFile
s 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);