You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
* Add some more information about modules
* Run prettier
* Update docs/publishing-modules.md
Co-authored-by: Perry van Wesel <Perryvw@users.noreply.github.com>
* Restore using npm packages
Co-authored-by: Perry van Wesel <Perryvw@users.noreply.github.com>
Copy file name to clipboardExpand all lines: docs/external-lua-code.md
+11-64Lines changed: 11 additions & 64 deletions
Original file line number
Diff line number
Diff line change
@@ -6,7 +6,9 @@ As of `0.40.0`, tstl supports module resolution for libraries, which means you c
6
6
7
7
## Adding Lua files to your project sources
8
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:
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.
10
+
11
+
Your project should look like:
10
12
11
13
```
12
14
main.ts
@@ -15,73 +17,18 @@ somelua.d.ts
15
17
tsconfig.json
16
18
```
17
19
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
20
+
And you can use it like so:
27
21
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:
22
+
```ts title=main.ts
23
+
import { myFunction } from"./somelua";
29
24
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
-
}
25
+
myFunction();
42
26
```
43
27
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
-
```
28
+
## Using NPM packages
58
29
59
-
With these two files you are now ready to publish your npm package with `npm publish`!
30
+
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.
60
31
61
-
:::warning
62
-
Currently, projects using `"buildMode": "library"` tsconfig setting must also have the `luaBundle` setting turned off. (However, you can still _consume_ unbundled libraries in projects that use `luaBundle` without any problems.)
32
+
:::note
33
+
Including TS or JS files from npm packages is currently NOT supported.
63
34
:::
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.
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
+
- You cannot import `.ts` and `.tsx` source files
8
+
- You must use `"buildMode": "library"`
9
+
- It is recommended you use `"declaration": true`
10
+
- You cannot use `"luaBundle"` in packages intended to be included as dependency in another project
11
+
12
+
## Project Configuration
13
+
14
+
Your `tsconfig.json` file must at least specify the following...
15
+
16
+
```json title=tsconfig.json
17
+
{
18
+
"compilerOptions": {
19
+
"declaration": true
20
+
},
21
+
"tstl": {
22
+
"buildMode": "library"
23
+
}
24
+
}
25
+
```
26
+
27
+
And your `package.json` file should specify the `types` property. You should also specify the `main` property if your module contains runnable Lua code.
28
+
29
+
```json title=package.json
30
+
{
31
+
"main": "./dist/index", // points to ./dist/index.lua
32
+
"types": "./dist/index"// points to ./dist/index.d.ts
33
+
}
34
+
```
35
+
36
+
These must be **relative** paths within your module **without** the file's extension.
37
+
38
+
> These are set to `"index"` by default so if you _really_ don't want to specify these you can keep an `index.d.ts` and `index.lua` file at the top level of your package.
39
+
40
+
## Publishing
41
+
42
+
Within your `package.json` you can specify the `files` field to mark what files to publish.
43
+
44
+
This is useful if you don't want to publish your source code.
45
+
46
+
```json title=package.json
47
+
{
48
+
"files": [
49
+
"dist/**/*.lua", // publish all Lua files in /dist/
50
+
"dist/**/*.d.ts"// publish all declaration files in /dist/
51
+
]
52
+
}
53
+
```
54
+
55
+
You can use `npm publish --dry-run` to see what files would be published without publishing your package.
56
+
57
+
- Some files will always be published e.g. `package.json`, `README.md`.
58
+
- Modules specified in `"devDependencies"` will not be available to the module at runtime.
59
+
- The `tsconfig.json` file does nothing for users of your module.
60
+
61
+
And when you're happy, your `package.json` has a `name`, `version`, `description`, and you are logged into NPM on your machine... you can run `npm publish` to publish your module.
62
+
63
+
## Using the Module
64
+
65
+
Assuming the module is available on NPM, users of your module can download it like so.
66
+
67
+
```bash
68
+
npm install <package-name>
69
+
# OR
70
+
yarn add <package-name>
71
+
```
72
+
73
+
Now they can start using it.
74
+
75
+
```ts title=example.ts
76
+
import { func } from"<package-name>";
77
+
78
+
func();
79
+
```
80
+
81
+
TypeScriptToLua will handle the module resolution from here.
82
+
83
+
## Example projects
84
+
85
+
For example projects using external Lua, you can look at the projects used in the TypeScriptToLua tests:
86
+
87
+
### [A project using Lua from node_modules packages](https://github.com/TypeScriptToLua/TypeScriptToLua/tree/master/test/transpile/module-resolution/project-with-node-modules)
88
+
89
+
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:
90
+
91
+
-`lua-global-with-decls`: Lua code + TypeScript declarations defining global functions.
92
+
-`lua-global-without-decls`: Lua code defining global functions.
93
+
- 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).
94
+
-`lua-module-with-decls`: Lua code + TypeScript declarations for 'module' files, i.e Lua files that return a table of exported functions.
95
+
-`lua-module-with-decls`: Lua code for 'module' files, i.e Lua files that return a table of exported functions.
96
+
- 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).
97
+
98
+
### [A project with Lua sources](https://github.com/TypeScriptToLua/TypeScriptToLua/tree/master/test/transpile/module-resolution/project-with-lua-sources)
99
+
100
+
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!
101
+
102
+
This project contains two Lua source files:
103
+
104
+
-`luafile.lua`: Some Lua right next to the .ts files using it.
105
+
-`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