Path Require Mode

This require mode can be configured in the bundle part of the configuration file. For a quick overview of the bundling configuration, see the documentation page.

Once enabled, darklua will find all require calls made with strings (single or double quotes) and resolve them.

The path require mode can be defined as the string ‘path’ to use all the default values, or with its object format:

{
  name: "path",

  // optional (defaults to 'init')
  module_folder_name: "init",

  // optional
  sources: {
    pkg: "./Packages",
  },
}

Path Resolution

The first step consist of figuring out the head of the path or where to start looking for the resource:

• if the path starts with . or ..: the path is considered relative to the file where the require call is made
• if the path starts with /: the path is considered like a regular absolute path
• else: the first component of the path is used to find a matching source

The next step is to resolve the tail of the path:

• if the path has an extension: the resource is expected exactly as is

• else: darklua will find the first available file based on the given path:

  1. the given path
  2. the given path with a luau extension
  3. the given path with a lua extension
  4. the given path joined with the module folder name
  5. (if the module folder name does not have an extension) the given path joined with the module folder name and a luau extension
  6. (if the module folder name does not have an extension) the given path joined with the module folder name and a lua extension

Here is a concrete example of these steps with a require to ./example. darklua will try the following paths and find the first file:

1. ./example
2. ./example.luau
3. ./example.lua
4. ./example/init
5. ./example/init.luau
6. ./example/init.lua

Module Folder Name

When requiring a folder, this mode will look into the folder for a file named by the given value of the module_folder_name parameter. The default value is init.

For example, to configure darklua to use index.lua (or index.luau) similar to what is used in JavaScript, set the parameter to index.

To bundle with index files, provide this configuration:

{
  bundle: {
    require_mode: {
      name: "path",
      // folders with a `index.lua` or `index.luau` file
      // can be required
      module_folder_name: "index",
    },
  },
}

Or when using the convert_require rule, provide this configuration:

{
  rules: [
    {
      rule: "convert_require",
      current: {
        name: "path",
        // folders with a `index.lua` or `index.luau` file
        // can be required
        module_folder_name: "index",
      },
      target: "roblox",
    },
  ],
}

Sources

When a path do not start with ., .. or /, their first component is used to find its associated source location. These locations can be configured with the sources parameter of the path require mode configuration.

Relative paths are resolved based on the configuration file location.

Example

Given this configuration file for bundling:

{
  bundle: {
    require_mode: {
      name: "path",
      sources: {
        pkg: "./Packages",
        // you can also map directly to a file (Lua or
        // any supported data file)
        images: "./assets/image-links.json",
      },
    },
  },
}

It is possible to make these require call in any file:

local Promise = require("pkg/Promise")
local images = require("images")