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 workspacesquestion: 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 assetsquestion: 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__andDEVglobals will be inlined astrueorfalseusing darklua.
You will get a lot of things ready to use:
- a configured npm package with a
package.json, a.npmignoreand a.yarnrc.ymlwhen using yarn - Luau related configuration files (
.luauand.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 additionalselene_defs.ymlto supportrequirecalls with strings. -
StyLua configuration (
stylua.toml) and.styluaignore - a
foreman.tomlto 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.
- Go to the
Settingstab of your repository - Under
Security, open theSecrets and variablessection and chooseActions - Click on
New repository secret - Put
NPM_TOKENas 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.
- Go to the
Actionstab of your repository - Choose the workflow named
Release. - Click on the button named
Run workflow. - Enter the version number (prefixed with
v, such asv0.1.0orv1.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.