JsToLua

Conversion tool for migrating JS/TS code into Luau.

Prerequisites

The project requires the following tools:

• Node (version >= 16)

Setup

Project installation

To install all the other dependencies run npm install

Building CLI tool

To build the CLI tool just run the following command:

npm run build:prod

The build JS file will be placed in dist/apps/convert-js-to-lua/main.js

Usage

The CLI tool accepts the following input parameters:

• --input (-i) - a list of input file(s) or glob patterns (for more info on supported format please read the glob package docs)

• --output (-o) - a directory in which the output files should be saved. The tool will keep the files structure of the input files.

• --rootDir (-root) - the root directory of the repository we are converting. In most cases, this is where the hidden .git/ directory would reside.

• --sha - the SHA of the upstream repo we are converting

• --plugin (-p) - post-processing plugins. This is an array that can either be:

  • an npm script that points to a valid post-processing plugin
  • a local path that points to the root directory of a post-processing plugin eg. ./libs/plugins/jest-globals/src/lib/plugins-jest-globals.ts. To learn more about plugins and how to create and use them, check out the contribution guide

• --babelConfig - a path to a JSON file containing Babel Configuration options. This param is optional. In case it's not provided the tool will use the following default configration:

  {
    "sourceType": "unambiguous",
    "plugins": ["jsx", "typescript", "classProperties"]
  }

• --babelTransformConfig - a path to a JSON file containing Babel Transform Configuration options. This param is optional. In case it's not provided the tool will use the following default configration:

  {
    "sourceType": "unambiguous",
    "plugins": [
      [
        "@babel/plugin-syntax-typescript",
        {
          "isTSX": true
        }
      ]
    ],
    "presets": ["@babel/preset-react"]
  }

To show help you can always use --help flag.

dist/apps/convert-js-to-lua/index.js --help

To run the JS/TS files via the conversion tool let's assume the following file structure:

js-to-lua
  - dist/apps/convert-js-to-lua/main.js

source-files
  - file1.js
  - file2.ts
  - directory
    - inner-file1.js
    - inner-file2.ts

By default conversion tool uses @babel/preset-react and @babel/plugin-syntax-typescript to simplify the JSX syntax.

It is necessary to install the following 3 packages before running the CLI tool:

npm install @babel/plugin-syntax-typescript @babel/preset-react @babel/core

To convert all the files in source-files directory you can run the following command:

./js-to-lua/dist/apps/convert-js-to-lua/index.js \
 --input source-files/**/*.js source-files/**/*.ts \
 --output lua-source-files

If source-files contain files using Flow types you can use a provided default flow configuration:

./js-to-lua/dist/apps/convert-js-to-lua/index.js \
 --input source-files/**/*.js source-files/**/*.ts \
 --output lua-source-files \
 --babelConfig js-to-lua/babel-flow.config.json

This will output the Lua files into the following file structure:

lua-source-files
  - file1.lua
  - file2.lua
  - directory
    - inner-file1.lua
    - inner-file2.lua

Testing

To run unit tests you can use the following npm script:

npm run affected:test

Note: This will only run the tests that are affected by your changes. If you want to run all tests use the following command:

npm run test:all

Linting

We use ESLint for style checking the codebase. To run linting you can use the following npm script:

npm run affected:lint

Note: This will only run the linting on projects that are affected by your changes. If you want to lint all projects use the following command:

npm run lint:all

Releasing

Overview

Because the main branch is protected we can't push directly to it after creating a release commit & tag. For this reason I've split the release process into to commands:

• npx nx run workspace:release-branch which would create a branch release/v<new_version>with necessary version bumps that needs to be reviewed and squash merged
• npx nx run workspace:release-tag after squash merging a branch then we can run this command which would just create a proper tag and verify that the git tree is clean. If it's not clean it would revert tag creation

Release process

• First we need to initiate the release by creating a release branch. To do that you need to run the following command from main branch: npx nx run workspace:release-branch --releaseAs=<major | minor | patch>
  • This will create a release/v<new-version>
• Push the created release branch and create a PR into main
• Wait for PR approval and merge it into main
• Execute the second command providing the same releaseAs param npx nx run workspace:release-tag --releaseAs=<major | minor | patch>
  • This command will create a new tag but not create any new commits
• Push the new tag to origin git push origin <tag-name>
• Pushing a tag will trigger the .github/workflows/release.yml workflow. It will:
  • create a new release based on the tag
  • build all the apps into packed artifacts and upload them to the release