|
| 1 | +--- |
| 2 | +title: External Lua Code |
| 3 | +--- |
| 4 | + |
| 5 | +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. |
| 6 | + |
| 7 | +## Adding Lua files to your project sources |
| 8 | + |
| 9 | +You can simply add a Lua file as part of your project sources if you add [a declaration file](./advanced/writing-declarations.md) with the same name. You can then simply import the Lua code in your TypeScript. Your project should look like: |
| 10 | + |
| 11 | +``` |
| 12 | +main.ts |
| 13 | +somelua.lua |
| 14 | +somelua.d.ts |
| 15 | +tsconfig.json |
| 16 | +``` |
| 17 | + |
| 18 | +## Using NPM packages |
| 19 | + |
| 20 | +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](./advanced/writing-declarations.md) to your source files. |
| 21 | + |
| 22 | +:::note |
| 23 | +Including TS or JS files from npm packages is currently NOT supported. |
| 24 | +::: |
| 25 | + |
| 26 | +## Creating Lua NPM packages |
| 27 | + |
| 28 | +If you want to distribute your tstl created Lua as a library, you will need to enable the library build mode in `tsconfig.json`, and enable the output of declaration files: |
| 29 | + |
| 30 | +```json title=json.config |
| 31 | +{ |
| 32 | + "compilerOptions": { |
| 33 | + ... |
| 34 | + "outDir": "dist", // Output package contents to dist directory |
| 35 | + "declaration": true |
| 36 | + }, |
| 37 | + "tstl": { |
| 38 | + ... |
| 39 | + "buildMode": "library" |
| 40 | + } |
| 41 | +} |
| 42 | +``` |
| 43 | + |
| 44 | +Then add or update your `package.json` so it contains the following information: |
| 45 | + |
| 46 | +```json title=package.json |
| 47 | +{ |
| 48 | + "name": "example-tstl-lua-package", |
| 49 | + "version": "1.0.0", |
| 50 | + "description": "A package created with TypeScriptToLua", |
| 51 | + "scripts": { |
| 52 | + "prepublish": "tstl" // Make sure latest lua is built before publishing |
| 53 | + }, |
| 54 | + // Only include dist files |
| 55 | + "files": ["dist/**/*.lua", "dist/**/*.d.ts"] |
| 56 | +} |
| 57 | +``` |
| 58 | + |
| 59 | +With these two files you are now ready to publish your npm package with `npm publish`! |
| 60 | + |
| 61 | +:::warning |
| 62 | +Currently, projects using `"buildMode": "library"` cannot be bundled. |
| 63 | +::: |
| 64 | + |
| 65 | +## Example projects |
| 66 | + |
| 67 | +For example projects using external Lua, you can look at the projects used in the TypeScriptToLua tests: |
| 68 | + |
| 69 | +### [A project using Lua from node_modules packages](https://github.com/TypeScriptToLua/TypeScriptToLua/tree/master/test/transpile/module-resolution/project-with-node-modules) |
| 70 | + |
| 71 | +A project using dependencies from its [node_modules directory](https://github.com/TypeScriptToLua/TypeScriptToLua/tree/master/test/transpile/module-resolution/project-with-node-modules/node_modules) with Lua code. These example dependencies include: |
| 72 | + |
| 73 | +- `lua-global-with-decls`: Lua code + TypeScript declarations defining global functions. |
| 74 | +- `lua-global-without-decls`: Lua code defining global functions. |
| 75 | + - Declaration file is added manually in [lua-global-without-decls.d.ts in the project sources](https://github.com/TypeScriptToLua/TypeScriptToLua/tree/master/test/transpile/module-resolution/project-with-node-modules). |
| 76 | +- `lua-module-with-decls`: Lua code + TypeScript declarations for 'module' files, i.e Lua files that return a table of exported functions. |
| 77 | +- `lua-module-with-decls`: Lua code for 'module' files, i.e Lua files that return a table of exported functions. |
| 78 | + - Declaration files are added manually in [lua-module-without-decls.d.ts in the project sources](https://github.com/TypeScriptToLua/TypeScriptToLua/tree/master/test/transpile/module-resolution/project-with-node-modules). |
| 79 | + |
| 80 | +### [A project with Lua sources](https://github.com/TypeScriptToLua/TypeScriptToLua/tree/master/test/transpile/module-resolution/project-with-lua-sources) |
| 81 | + |
| 82 | +This project includes Lua files as part of the project's source files. To use the Lua from the files you have to provide declaration files with a matching name and location for each file. For examples `some_dir/library.lua` & `some_dir/library.d.ts`. The declaration files contain the TypeScript declarations of the corresponding Lua file. Both Lua and .d.ts files should be checked into your repository! |
| 83 | + |
| 84 | +This project contains two Lua source files: |
| 85 | + |
| 86 | +- `luafile.lua`: Some Lua right next to the .ts files using it. |
| 87 | +- `lua_sources/otherluaFile.lua`: Lua in a separate `lua_sources` directory, in case you want to group all your Lua files into one directory. |
0 commit comments