Skip to main content

Publishing Modules

There are two kinds of tstl libraries published on npm:

  • Type declaration libraries - Provides only ambient types. In other words, these libraries do not contain any code which can be executed.
  • Lua libraries - Provides Lua code that can be imported and executed by tstl projects.

This page describes how to create a Lua package and publish it to npm.

Basic Limitations​

  • tstl cannot import .ts and .tsx source files from a node_modules library.
  • tstl Lua libraries can not be bundled with the luaBundle compiler flag. (The end-users consuming the library will decide whether they want the final product to use luaBundle or not.)

Project Configuration​

Your tsconfig.json file must include the following fields:

tsconfig.json
{
  "compilerOptions": {
    "declaration": true
  },
  "tstl": {
    "buildMode": "library"
  }
}

Your package.json file should include the following fields:

package.json
{
  // An array containing the files that will be published to npm. (See more information below.)
  "files": [
    "dist/**/*.lua", // Only specify this if your library is a Lua library.
    "dist/**/*.d.ts"
  ],

  "types": "./dist/index.d.ts",

  // Only specify "main" if your library is a Lua library.
  // (Do NOT include the file extension here, or things will not work properly.)
  "main": "./dist/index"
}
note

There are many other fields that should be in a proper package.json file, such as name, author, version, and so on. Use npm init to generate a new package.json with some basic fields, if necessary.

Publishing​

Note that:

  • Regardless of the contents of the files field, some files will always be published, like package.json and README.md.
  • Modules specified in "devDependencies" will not be available to the module at runtime.
  • There is no need to publish the tsconfig.json file, as it will do nothing for the users of your module.

When you are ready to publish:

  • Use npm publish --dry-run to see what files would be published without actually uploading anything.
  • Use npm publish to actually upload it.

Using the Module​

See the page on using Lua packages.

Example projects​

For an example of a Lua package published to npm, see isaacscript-common.

You can also reference the projects used in the TypeScriptToLua tests:

A project using Lua from node_modules packages​

A project using dependencies from its node_modules directory 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.
  • 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.

A project with Lua sources​

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:

  • 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.