publishing-modules.md

title
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:

{
  "compilerOptions": {
    "declaration": true
  },
  "tstl": {
    "buildMode": "library"
  }
}

Your package.json file should include the following fields:

{
  // 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.
  • Declaration file is added manually in lua-global-without-decls.d.ts in the project sources.
• 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.

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.