How to Create a Luau Package

Resources Community Tutorials
, ,
#1

How to Create a Luau Package

For those who would prefer, a version of this article is available on Medium.

In this article, you will learn how to use a project generator to easily publish Luau code as a package on npm.

This article is aimed at developers who are writing code on the file system (not within Roblox Studio).

Install the Luau Project Generator

Developing with Luau involves a few different tools that need to be setup. To speed up the process, there is seaofvoices/generator-luau.

If you don’t have node installed, start by installing it. Node comes with npm.

The first step is to install yo, the scaffolding tool named yeoman which generator-luau is built on top of.

npm install --global yo

Then, you can install generator-luau.

npm install --global generator-luau

Generate the Project Structure

Open a command prompt where you want to create your new project. Run the following command and pass your project name. This will create a new directory project-name with many Luau tools already configured.

yo luau project-name

Answer the various prompts according to the project needs.

  • About the setup workspaces question: when using yarn, you can setup a project so that it has multiple packages that can be independently published. Notable examples are Jest-Lua or React-Lua. Read more about workspaces on the yarn documentation site.
  • About the build debug assets question: if you choose, the generator will create scripts to automatically build a version of the project where common debugging global values are set. The __DEV__ and DEV globals will be inlined as true or false using darklua.

You will get a lot of things ready to use:

  • a configured npm package with a package.json, a .npmignore and a .yarnrc.yml when using yarn
  • Luau related configuration files (.luau and .luau-analyze.json)
  • VS Code settings for luau-lsp
  • darklua configurations
  • commonly used repository files (README.md, CODE_OF_CONDUCT.md, LICENSE.txt, CHANGELOG.md)
  • selene configuration (selene.toml) and an additional selene_defs.yml to support require calls with strings.
  • StyLua configuration (stylua.toml) and .styluaignore
  • a foreman.toml to install necessary tools with Foreman

The generator also defines multiple scripts which can be easily executed with npm run script-name or yarn script-name:

  • lint: run code analysis with luau-lsp and selene
  • format: run StyLua
  • style-check: verify that the code is properly formatted with StyLua
  • build: generate Roblox models and/or a Luau bundled files
  • prepare: runs npmluau to generate the package links
  • verify-pack: display the content that will get published

For Windows users, note that there are a few shell scripts (ending with .sh) created by the generator, so make sure you can run those scripts. One simple way is with Git Bash, which comes with the Git installation on Windows.

Add a Dependency

If you have found a Luau package on npm that you would like to use, you can add it with a simple command. All you need is the package name, which is written in the package.json file.

npm install luau-disk
# or if you are using yarn
yarn add luau-disk

After adding a dependency, run the prepare script to generate the Luau package links.

npm run prepare
# or if you are using yarn
yarn prepare

Now you can require this dependency anywhere using the @pkg alias:

local Disk = require(“@pkg/luau-disk”)

Wondering what is available? I have an awesome-luau package list.

Push the Project to GitHub

First, create your first commit.

git init
git add .

# The generated scripts do not have the execute permission
# enabled. This command will enable it
git update-index --chmod +x scripts/*.sh

# finalize your commit
git commit -m "Initial commit"

Once the commit is done, push to an existing GitHub repository.

git remote add origin https://github.com/OWNER/REPOSITORY.git
git push -u origin main

Publish the Package

If you would like to share your package with the Luau community, publish it to the public npm registry. This makes it possible for future consumers to add your package with npm install package-name or yarn add package-name.

You can verify what files will be packaged up by running the verify-pack script (defined in the package.json). Run the following command to print the package content:

yarn run verify-pack
# or
npm run verify-pack

The generated project configures a GitHub action to automate releases of a package. To use this action, you will need to provide an authentication token through a GitHub secret.

  1. Go to the Settings tab of your repository
  2. Under Security, open the Secrets and variables section and choose Actions
  3. Click on New repository secret
  4. Put NPM_TOKEN as the secret name and put your authentication token as the value. If you don’t know how to get a token, you can check out the documentation from npm.

After that, the action can be manually triggered from the GitHub web interface.

  1. Go to the Actions tab of your repository
  2. Choose the workflow named Release.
  3. Click on the button named Run workflow.
  4. Enter the version number (prefixed with v, such as v0.1.0 or v1.0.2). The commit ID is optional, for cases where you would not want to create the release from the latest commit.

If you have trouble triggering the workflow, take a look at this GitHub article.

Closing Thoughts

As you can see, getting a new Luau project up and published is quite simple with generator-luau. You will spend less time configuring tools and instead focus on writing code.

If you are writing Luau that may run on different environments (like Lune), follow the Sea of Voices Luau Package Standard to ensure compatibility across environments.

To learn more about why npm is an excellent solution for Luau package management, read why you should use npm for Luau.

If you would like to support my work, I have a page on ko-fi where you can contribute. If you prefer, GitHub sponsors are also available in my projects under Sea of Voices.

Useful Links

4 Likes