From 6f4b9ffe4f1872a6dda05490700b2ea5edbcea6b Mon Sep 17 00:00:00 2001 From: Perryvw Date: Sun, 6 Jun 2021 19:44:36 +0200 Subject: [PATCH 1/6] Add page for external lua code --- docs/external-lua-code.md | 67 +++++++++++++++++++++++++++++++++++++++ sidebars.json | 1 + 2 files changed, 68 insertions(+) create mode 100644 docs/external-lua-code.md diff --git a/docs/external-lua-code.md b/docs/external-lua-code.md new file mode 100644 index 00000000..4cf8ddca --- /dev/null +++ b/docs/external-lua-code.md @@ -0,0 +1,67 @@ +--- +title: External Lua Code +--- + +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. + +## Adding Lua files to your project sources + +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: + +``` +main.ts +somelua.lua +somelua.d.ts +tsconfig.json +``` + +## Using NPM packages + +To use a Lua package, simply `npm install` it 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 `.d.ts` [declaration file](./advanced/writing-declarations.md) to your source files. + +:::note +Including TS or JS files from npm packages is currently NOT supported. +::: + +## Creating Lua NPM packages + +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: + +```json title=json.config +{ + "compilerOptions": { + ... + "outDir": "dist", // Output package contents to dist directory + "declaration": true + }, + "tstl": { + ... + "buildMode": "library" + } +} +``` + +Then add or update your `package.json` so it contains the following information: + +```json title=package.json +{ + "name": "example-tstl-lua-package", + "version": "1.0.0", + "description": "A package created with TypeScriptToLua", + "scripts": { + "prepublish": "tstl" // Make sure latest lua is built before publishing + }, + // Only include dist files + "files": [ + "dist/**/*.lua", + "dist/**/*.d.ts" + ] +} +``` + +With these two files you are now ready to publish your npm package with `npm publish`! + +:::warning +Currently, projects using `"buildMode": "library"` cannot be bundled. +::: + diff --git a/sidebars.json b/sidebars.json index 6e0b48cd..dee34c75 100644 --- a/sidebars.json +++ b/sidebars.json @@ -4,6 +4,7 @@ "configuration", "caveats", "the-self-parameter", + "external-lua-code", "editor-support", { "type": "category", From acaf7179c3aa7c2b36732d6ef699550e3d2445db Mon Sep 17 00:00:00 2001 From: Perryvw Date: Sun, 6 Jun 2021 19:56:35 +0200 Subject: [PATCH 2/6] Fix prettier --- docs/external-lua-code.md | 22 +++++++++------------- 1 file changed, 9 insertions(+), 13 deletions(-) diff --git a/docs/external-lua-code.md b/docs/external-lua-code.md index 4cf8ddca..59f267fa 100644 --- a/docs/external-lua-code.md +++ b/docs/external-lua-code.md @@ -2,7 +2,7 @@ title: External Lua Code --- -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. +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. ## Adding Lua files to your project sources @@ -45,17 +45,14 @@ Then add or update your `package.json` so it contains the following information: ```json title=package.json { - "name": "example-tstl-lua-package", - "version": "1.0.0", - "description": "A package created with TypeScriptToLua", - "scripts": { - "prepublish": "tstl" // Make sure latest lua is built before publishing - }, - // Only include dist files - "files": [ - "dist/**/*.lua", - "dist/**/*.d.ts" - ] + "name": "example-tstl-lua-package", + "version": "1.0.0", + "description": "A package created with TypeScriptToLua", + "scripts": { + "prepublish": "tstl" // Make sure latest lua is built before publishing + }, + // Only include dist files + "files": ["dist/**/*.lua", "dist/**/*.d.ts"] } ``` @@ -64,4 +61,3 @@ With these two files you are now ready to publish your npm package with `npm pub :::warning Currently, projects using `"buildMode": "library"` cannot be bundled. ::: - From 482538225c7dc5f413c475cd1df6cd4ac6a66c4d Mon Sep 17 00:00:00 2001 From: Perryvw Date: Sun, 6 Jun 2021 20:27:16 +0200 Subject: [PATCH 3/6] Update prettier --- docusaurus-plugin.js | 5 ++--- package-lock.json | 14 +++++++------- package.json | 2 +- 3 files changed, 10 insertions(+), 11 deletions(-) diff --git a/docusaurus-plugin.js b/docusaurus-plugin.js index db22901b..514bc2fe 100644 --- a/docusaurus-plugin.js +++ b/docusaurus-plugin.js @@ -18,9 +18,8 @@ module.exports = () => ({ resolve: { alias: { // Replace vendored monaco-typescript services build with typescript, already used by typescript-to-lua - [require.resolve( - "monaco-editor/esm/vs/language/typescript/lib/typescriptServices.js", - )]: require.resolve("typescript"), + [require.resolve("monaco-editor/esm/vs/language/typescript/lib/typescriptServices.js")]: + require.resolve("typescript"), // Exclude builtin monaco-typescript libs [require.resolve("monaco-editor/esm/vs/language/typescript/lib/lib.js")]: resolve( diff --git a/package-lock.json b/package-lock.json index 24d4e98f..9c520620 100644 --- a/package-lock.json +++ b/package-lock.json @@ -32,7 +32,7 @@ "file-loader": "^6.1.1", "fork-ts-checker-webpack-plugin": "^5.2.0", "null-loader": "^4.0.1", - "prettier": "^2.1.2", + "prettier": "^2.3.1", "raw-loader": "^4.0.2", "sass": "^1.27.0", "sass-loader": "^10.0.4", @@ -14017,9 +14017,9 @@ } }, "node_modules/prettier": { - "version": "2.2.1", - "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.2.1.tgz", - "integrity": "sha512-PqyhM2yCjg/oKkFPtTGUojv7gnZAoG80ttl45O6x2Ug/rMJw4wcc9k6aaf2hibP7BGVCCM33gZoGjyvt9mm16Q==", + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.3.1.tgz", + "integrity": "sha512-p+vNbgpLjif/+D+DwAZAbndtRrR0md0MwfmOVN9N+2RgyACMT+7tfaRnT+WDPkqnuVwleyuBIG2XBxKDme3hPA==", "dev": true, "bin": { "prettier": "bin-prettier.js" @@ -32029,9 +32029,9 @@ "dev": true }, "prettier": { - "version": "2.2.1", - "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.2.1.tgz", - "integrity": "sha512-PqyhM2yCjg/oKkFPtTGUojv7gnZAoG80ttl45O6x2Ug/rMJw4wcc9k6aaf2hibP7BGVCCM33gZoGjyvt9mm16Q==", + "version": "2.3.1", + "resolved": "https://registry.npmjs.org/prettier/-/prettier-2.3.1.tgz", + "integrity": "sha512-p+vNbgpLjif/+D+DwAZAbndtRrR0md0MwfmOVN9N+2RgyACMT+7tfaRnT+WDPkqnuVwleyuBIG2XBxKDme3hPA==", "dev": true }, "pretty-error": { diff --git a/package.json b/package.json index 12ccda2c..a11f8d5e 100644 --- a/package.json +++ b/package.json @@ -39,7 +39,7 @@ "file-loader": "^6.1.1", "fork-ts-checker-webpack-plugin": "^5.2.0", "null-loader": "^4.0.1", - "prettier": "^2.1.2", + "prettier": "^2.3.1", "raw-loader": "^4.0.2", "sass": "^1.27.0", "sass-loader": "^10.0.4", From 9e4206a19289fa6f4b11b43bf8a33fcbeb85ecee Mon Sep 17 00:00:00 2001 From: Perry van Wesel Date: Mon, 14 Jun 2021 20:03:32 +0200 Subject: [PATCH 4/6] Apply suggestions from code review Co-authored-by: Lorenz Junglas --- docs/external-lua-code.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/external-lua-code.md b/docs/external-lua-code.md index 59f267fa..368230fe 100644 --- a/docs/external-lua-code.md +++ b/docs/external-lua-code.md @@ -2,11 +2,11 @@ title: External Lua Code --- -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. +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. ## Adding Lua files to your project sources -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: +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: ``` main.ts @@ -17,7 +17,7 @@ tsconfig.json ## Using NPM packages -To use a Lua package, simply `npm install` it 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 `.d.ts` [declaration file](./advanced/writing-declarations.md) to your source files. +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 `.d.ts` [declaration file](./advanced/writing-declarations.md) to your source files. :::note Including TS or JS files from npm packages is currently NOT supported. @@ -25,7 +25,7 @@ Including TS or JS files from npm packages is currently NOT supported. ## Creating Lua NPM packages -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: +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: ```json title=json.config { From 7dbb0df24a4889092b0430506388db025571e512 Mon Sep 17 00:00:00 2001 From: Perryvw Date: Mon, 14 Jun 2021 20:38:14 +0200 Subject: [PATCH 5/6] Added links to example projects form tstl tests --- docs/external-lua-code.md | 24 ++++++++++++++++++++++++ package-lock.json | 2 +- package.json | 2 +- 3 files changed, 26 insertions(+), 2 deletions(-) diff --git a/docs/external-lua-code.md b/docs/external-lua-code.md index 368230fe..d55885e2 100644 --- a/docs/external-lua-code.md +++ b/docs/external-lua-code.md @@ -61,3 +61,27 @@ With these two files you are now ready to publish your npm package with `npm pub :::warning Currently, projects using `"buildMode": "library"` cannot be bundled. ::: + +## Example projects + +For example projects using external Lua, you can look at the projects used in the TypeScriptToLua tests: + +### [A project using Lua from node_modules packages](https://github.com/TypeScriptToLua/TypeScriptToLua/tree/master/test/transpile/module-resolution/project-with-node-modules) + +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: + +- `lua-global-with-decls`: Lua code + TypeScript declarations defining global functions. +- `lua-global-without-decls`: Lua code defining global functions. + - 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). +- `lua-module-with-decls`: Lua code + TypeScript declarations for 'module' files, i.e Lua files that return a table of exported functions. +- `lua-module-with-decls`: Lua code for 'module' files, i.e Lua files that return a table of exported functions. + - 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). + +### [A project with Lua sources](https://github.com/TypeScriptToLua/TypeScriptToLua/tree/master/test/transpile/module-resolution/project-with-lua-sources) + +This project includes lua source files as part of the project sources (not in node_modules). To use this Lua you also have to provide .d.ts files with the same name and location containing the TyepScript declarations for the contents of the Lua file. Both Lua and .d.ts files should be checked into your repository! + +This project contains two lua source files: + +- `luafile.lua`: Some lua right next to the .ts files using it. +- `lua_sources/otherluaFile.lua`: Lua in a separate `lua_sources` directory, in case you want to group all your Lua into one directory. diff --git a/package-lock.json b/package-lock.json index 9c520620..d100301d 100644 --- a/package-lock.json +++ b/package-lock.json @@ -32,7 +32,7 @@ "file-loader": "^6.1.1", "fork-ts-checker-webpack-plugin": "^5.2.0", "null-loader": "^4.0.1", - "prettier": "^2.3.1", + "prettier": "2.3.1", "raw-loader": "^4.0.2", "sass": "^1.27.0", "sass-loader": "^10.0.4", diff --git a/package.json b/package.json index a11f8d5e..72ecf721 100644 --- a/package.json +++ b/package.json @@ -39,7 +39,7 @@ "file-loader": "^6.1.1", "fork-ts-checker-webpack-plugin": "^5.2.0", "null-loader": "^4.0.1", - "prettier": "^2.3.1", + "prettier": "2.3.1", "raw-loader": "^4.0.2", "sass": "^1.27.0", "sass-loader": "^10.0.4", From db6dc25b74eb3b51f3cba14d3df17e08da9cfc16 Mon Sep 17 00:00:00 2001 From: Perry van Wesel Date: Mon, 14 Jun 2021 20:59:49 +0200 Subject: [PATCH 6/6] Apply suggestions from code review Co-authored-by: Lorenz Junglas --- docs/external-lua-code.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/external-lua-code.md b/docs/external-lua-code.md index d55885e2..3d60cb21 100644 --- a/docs/external-lua-code.md +++ b/docs/external-lua-code.md @@ -79,9 +79,9 @@ A project using dependencies from its [node_modules directory](https://github.co ### [A project with Lua sources](https://github.com/TypeScriptToLua/TypeScriptToLua/tree/master/test/transpile/module-resolution/project-with-lua-sources) -This project includes lua source files as part of the project sources (not in node_modules). To use this Lua you also have to provide .d.ts files with the same name and location containing the TyepScript declarations for the contents of the Lua file. Both Lua and .d.ts files should be checked into your repository! +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! -This project contains two lua source files: +This project contains two Lua source files: -- `luafile.lua`: Some lua right next to the .ts files using it. -- `lua_sources/otherluaFile.lua`: Lua in a separate `lua_sources` directory, in case you want to group all your Lua into one directory. +- `luafile.lua`: Some Lua right next to the .ts files using it. +- `lua_sources/otherluaFile.lua`: Lua in a separate `lua_sources` directory, in case you want to group all your Lua files into one directory.