As of 0.40.0, tstl supports module resolution for libraries, which means you can use and create npm packages containing .lua files. You can also include Lua source files directly into your source code.

You can simply add a Lua file as part of your project sources if you add a declaration file with the same name. You can then simply import the Lua code in your TypeScript.

Your project should look like:

project/
├── main.ts
├── someLua.lua
├── someLua.d.ts
└── tsconfig.json

import { foo, bar } from "./someLua";

foo();
bar();

local someLua = {}

function someLua:foo()
  print("hello")
end

function someLua:bar()
  print("world")
end

return someLua

export function foo(): void;
export function bar(): void;

Building on the previous section, you might want also want to import a Lua file that only exports an array. For example, something like:

return {
    {
        foo = 123,
        bar = 456,
    },
    {
        foo = 789,
        bar = 987,
    },
}

Writing a definitions file for this is tricky, since the Lua file has no named imports and no default export. Here, you have to use export = syntax, like so:

interface Thing {
  foo: number;
  bar: number;
}

declare const things: Thing[];
export = things;

Then, in your TypeScript code, you can import it like:

import * as things from "./module";

print(things[0].foo); // Prints "123"

For more information about this export syntax, see the official TypeScript documentation.

To use a Lua package, install it via npm and use it as you would for any regular npm package in TypeScript. If the package does not include its own .d.ts declaration files, you can create your own by adding a <package name>.d.ts declaration file to your source files.

:::note Including TS or JS files from npm packages is currently NOT supported. :::