Luau Language Server

An implementation of a language server for the Luau programming language.

Getting Started

Install the extension from the VSCode Marketplace or OpenVSX Registry:

• VSCode Marketplace: https://marketplace.visualstudio.com/items?itemName=JohnnyMorganz.luau-lsp
• OpenVSX Registry: https://open-vsx.org/extension/JohnnyMorganz/luau-lsp

Alternatively, check out Getting Started for Language Server Clients to setup your own client for a different editor.

A Nightly Release runs every day with the latest changes on main. You can download the relevant release for your platform and manually install the .vsix. The nightly release builds with debug symbols and profiling instrumentation for debugging.

For General Users

The language server will start working immediately for general Luau code. There is built-in support for Luau's generalised require-by-string semantics, using require("./module").

To provide global type definitions for a custom environment, specify luau-lsp.types.definitionFiles. Corresponding documentation is configured using luau-lsp.types.documentationFiles.

If you use Luau in a different environment and are interested in using the language server, or looking for any specific features, please get in touch!

For Rojo Users (requires v7.3.0+)

By default, the latest Roblox type definitions and documentation are preloaded out of the box. This can be disabled by configuring luau-lsp.platform.type.

The language server uses Rojo-style sourcemaps to resolve DataModel instance trees for intellisense. This is done by running rojo sourcemap --watch default.project.json --output sourcemap.json. The server listens to changes of a sourcemap.json file present at the workspace root. It is recommended to add this file to your .gitignore.

The following settings are configurable for sourcemap generation:

• luau-lsp.sourcemap.enabled: Whether sourcemap support is enabled (default: on)
• luau-lsp.sourcemap.autogenerate: Whether sourcemaps are automatically generated by the client. If disabled, the server will listen to manual changes to a sourcemap.json file (default: on)
• luau-lsp.sourcemap.rojoProjectFile: What project file to use (default: default.project.json)
• luau-lsp.sourcemap.includeNonScripts: Whether to include non script instances in the sourcemap. May be disabled for expensive DataModels (default: on)
• luau-lsp.sourcemap.sourcemapFile: What sourcemap file to use (default: sourcemap.json)

If you do not use Rojo, you can still use the Luau Language Server, you just need to manually generate a sourcemap.json file for your particular project layout. You can configure luau-lsp.sourcemap.generatorCommand to run a custom generator. If your generator does not support file watching, enable luau-lsp.sourcemap.useVSCodeWatcher.

Note: in the diagnostics type checker, the types for DataModel (DM) instances will resolve to any. This is a current limitation to reduce false positives. However, autocomplete and hover intellisense will correctly resolve the DM type. To enable this mode for diagnostics, set luau-lsp.diagnostics.strictDatamodelTypes (off by default). Read more.

A companion Studio plugin is available to provide DataModel information for Instances which are not part of your Rojo build / filetree: Plugin Marketplace

Standalone

The tool can run standalone, similar to luau-analyze, to provide type and lint warnings in CI, with full Rojo resolution and API types support. The entry point for the analysis tool is luau-lsp analyze.

Install the binary and run luau-lsp --help for more information.

Configuration

There are 2 types of configuration styles for the language server. General configuration is provided by .luaurc files, which allow you to configure language strictness, lints, and require aliases. More information is available in Luau's RFC documentation.

The second configuration style is specific to the language server. See luau-lsp in your editor's settings for more details.

Supported Features

• Diagnostics (incl. type errors)
• Autocompletion
• Hover
• Signature Help
• Go To Definition
• Go To Type Definition
• Find References
• Document Link
• Document Symbol
• Color Provider
• Rename
• Semantic Tokens
• Inlay Hints
• Documentation Comments (Moonwave Style - supporting both --- comment and --[=[ comment ]=], but must be next to statement)
• Code Actions
• Workspace Symbols
• Folding Range
• Call Hierarchy

The following are extra features defined in the LSP specification, but most likely do not apply to Luau or are not necessary. They can be investigated at a later time:

• Go To Declaration (do not apply)
• Go To Implementation (do not apply)
• Code Lens (not necessary)
• Document Highlight (not necessary - editor highlighting is sufficient)
• Selection Range (not necessary - editor selection is sufficient)
• Inline Value (applies for debuggers only)
• Moniker
• Formatting (see stylua)
• Type Hierarchy (Luau currently does not provide any [public] ways to define type hierarchies)

Crash Reporting

The language server implements opt-in crash reporting, using Sentry.

On VSCode, this is configured via the setting luau-lsp.server.crashReporting.enabled. When a crash is encountered, an out-of-process crash handler will upload the crash details to Sentry via HTTP.

When a crash is reported, the report stores the following information:

• Crash reason and thread stack trace
• Device metadata: OS name, version and CPU architecture
• Dynamic libraries loaded into the process (including filesystem paths)

This information is transferred through a Minidump file. This file is not stored after processing. No general usage data is recorded.

Crash Reporting is only available for Windows and macOS, and is not active for Standalone mode (luau-lsp analyze)

Build From Source

Submodules are required to build the project. You should use --recurse-submodules when you initally clone the project; e.g.

git clone https://github.com/JohnnyMorganz/luau-lsp.git --recurse-submodules

To compile the project, execute the following commands in the project root directory.

git submodule update --init --recursive
mkdir build && cd build
cmake .. -DCMAKE_BUILD_TYPE=Release
cmake --build . --target Luau.LanguageServer.CLI --config Release

You can build Luau.LanguageServer.Test for unit tests. Some tests make assumptions about relative file paths. When running tests, ensure that your current working directory is set to the root of the repository.