Editor setup

The @lune/* libraries are built into the binary, so an editor cannot see them on disk. luneblox setup writes their type definitions to your home directory and adds an alias that luau-lsp follows.

Run setup

1. From the root of your project:

   luneblox setup

   Type definitions for Lune v0.11.3 have been set up successfully.
   You may need to restart your editor for the changes to take effect.
   Enum and warn are left out of .luaurc's globals: the Roblox types declare them.

   The last line says what setup did with globals; see The alias and the globals in .luaurc.

2. Restart the editor, or reload the language server.

What it writes

Type definitions

One Luau module per library, under a directory named after the LuneBlox version:

~/.luneblox/.typedefs/0.11.3/
  fs.luau
  luau.luau
  net.luau
  process.luau
  regex.luau
  serde.luau
  stdio.luau
  task.luau
  datetime/
    init.luau
    ...
  roblox/
    init.luau
    ...

datetime and roblox are directory modules: an init.luau with its submodules beside it. If an older single-file datetime.luau or roblox.luau is in the same directory, setup removes it, because a file and a directory with the same name make the require ambiguous.

This location is always under your home directory. LUNEBLOX_CACHE and the XDG variables do not move it.

The alias and the globals in .luaurc

Setup reads .luaurc in the current directory, creates it when it does not exist, and sets the alias. In a project that turns the Roblox types off, it sets globals as well:

{
  "aliases": {
    "lune": "~/.luneblox/.typedefs/0.11.3/"
  },
  "globals": [
    "Enum",
    "warn"
  ]
}

Other keys and other aliases are kept, and so are the other names in globals; a name is added only once. A globals that is not a list is left as it is. The file is written back as indented JSON, its keys in the order they had.

With the alias in place, require("@lune/fs") resolves to fs.luau in that directory for the language server. At run time luneblox ignores the alias and serves the built-in library.

globals names the globals LuneBlox adds that luau-lsp does not know on its standard platform: Roblox’s Enum and warn. The type checker takes a name listed there as a global of type any, so a strict script can write Enum.KeyCode.ButtonA without an Unknown global error. That is as far as the typedefs go for Enum: they describe neither its enums nor their items, just as they do not for require("@lune/roblox").Enum.

On the Roblox platform, luau-lsp’s default, the Roblox types already declare both names with their types, and a name in globals would replace those with any: local n: number = Enum.KeyCode.A would stop being an error. So setup adds them only where .vscode/settings.json sets "luau-lsp.platform.type": "standard" or "luau-lsp.types.roblox": false, and everywhere else takes Enum and warn out of globals if they are there, removing the key when nothing is left in it. The settings are read line by line, so comments and trailing commas in them are fine, and a line commented out does not count. Setup prints which it did.

.luaurc must be plain JSON

Setup parses .luaurc as strict JSON. A file with comments or trailing commas fails with Failed to parse settings; the typedefs are still written, but the alias is not.

After an upgrade

The directory is named after the version, so the alias written by 0.10.11 still points at the 0.10.11 typedefs after you install 0.10.12. Run luneblox setup again after each upgrade. It replaces the alias and leaves the old directory in place.

If .luaurc is committed, everyone on the project needs the same LuneBlox version and has to run luneblox setup once on their machine.

luau-lsp

In an editor

Install the luau-lsp extension for your editor. It reads .luaurc on its own. LuneBlox scripts are not Roblox scripts, so turn the Roblox globals off. The LuneBlox repository uses these settings for Visual Studio Code:

{
  "luau-lsp.types.roblox": false,
  "luau-lsp.sourcemap.enabled": false
}

On the command line

The same check runs outside an editor, which is how the LuneBlox repository type-checks its own scripts in CI:

luau-lsp analyze --platform=standard .lune

--platform=standard is the command-line form of turning the Roblox types off.

Strict mode

Start every script with a mode directive so that it is checked the same way wherever it is opened:

--!strict
local fs = require("@lune/fs")

Or set it for the whole project in .luaurc:

{
  "languageMode": "strict",
  "aliases": {
    "lune": "~/.luneblox/.typedefs/0.11.3/"
  }
}

Next

The reference pages for each library, starting with fs, are generated from the same type definitions that setup writes.