generator-luau

A Yeoman generator for Luau projects.

This generator will setup a Luau project in no time. It will add all the necessary files to:

• publish the project on npm
• format your code with StyLua
• run code analysis with selene and luau-lsp
• create Github actions:
  • to run tests
  • publish the package(s)
  • to create a new release and attach artifacts
• run unit tests using Jest
• bundle your project into a single Lua file using darklua
• build your project into a Roblox model file using rojo (and darklua to convert the requires!)
• add a license file (MIT, Apache, MPL and more)
• add other tools like lune, mantle or tarmac to the foreman.toml configuration file

Installation

First, install Yeoman and generator-luau using npm. If you do not have node.js, install it.

npm install -g yo
npm install -g generator-luau

Then generate your new project:

yo luau package-name

Why a project generator?

When working with Luau, a lot of different tools need to be setup. That involves various configuration files and scripts that may change slightly depending on the project.

Instead of creating various template projects with a lot of overlap (and having to maintain all of them), this generator will customize a project based on your answers to a set of questions.

Good to Know

This project generator is slightly opinionated. It is a tool I use to create and maintain a lot of projects in parallel.

For that reason, some corners are cut short and questions are not asked to configure:

• code style
• linters
• test runners

It is also possible that the generator has not implemented certain combination of features:

• multi-package project only works with yarn

Generated Content

Configuration files

• a npm package with a package.json, a .npmignore (a .yarnrc.yml when using yarn)
• Luau related (.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

Scripts

prepare

This script will run npmluau to create the necessary files that darklua or lune need to understand the node_modules layout.

When using npm, this script is automatically executed after installing dependencies with npm install. When using yarn, this script must be called explicitly.

lint

Runs code analysis with selene and luau-lsp. Those tools can be run individually with lint:selene and lint:luau.

format

Runs stylua on all the Luau files to format them.

style-check

Runs stylua on all the Luau files to verify that the code style is correct.

build

Build artifacts based on what was included.

verify-pack

Display in the output what files are going to be published.

Github Workflows

The project will come with two github workflows included.

Tests

This workflow will:

• run code analysis tools (selene and luau-lsp)
• verify the code format (with stylua)
• build a Roblox model artifact (if included)
• bundle the project in a single Lua file (if included)

Release

This workflow can be triggered manually via the GitHub interface. Go to the Actions tab, choose the workflow named Release. Click on the button named Run workflow. The interface will prompt for a version number (prefixed with v, such as v0.1.0 or v1.0.2) and an optional commit ID (in case 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.

The workflow will:

• publish the package to the npm registry
• create a new release on Github
• build artifacts (Roblox models and bundled Lua file) and attach them to the newly created GitHub release

Before triggering a release, make sure to bump the package version appropriately (if you are not familiar with semantic versioning, take a look at semver.org). Also, do not forget to update the changelog.

License

This project is available under the MIT license. See LICENSE.txt for details.