1---
2title: Lua
3description: "Configure Lua language support in Zed, including language servers, formatting, and debugging."
4---
5
6# Lua
7
8Lua support is available through the [Lua extension](https://github.com/zed-extensions/lua).
9
10- Tree-sitter: [tree-sitter-grammars/tree-sitter-lua](https://github.com/tree-sitter-grammars/tree-sitter-lua)
11- Language server: [LuaLS/lua-language-server](https://github.com/LuaLS/lua-language-server)
12
13## luarc.json
14
15To configure LuaLS you can create a `.luarc.json` file in the root of your project.
16
17```json [settings]
18{
19 "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
20 "runtime.version": "Lua 5.4",
21 "format.enable": true,
22 "workspace.library": ["../somedir/library"]
23}
24```
25
26See [LuaLS Settings Documentation](https://luals.github.io/wiki/settings/) for all available configuration options, or when editing this file in Zed available settings options will autocomplete, (e.g `runtime.version` will show `"Lua 5.1"`, `"Lua 5.2"`, `"Lua 5.3"`, `"Lua 5.4"` and `"LuaJIT"` as allowed values). Note when importing settings options from VS Code, remove the `Lua.` prefix. (e.g. `runtime.version` instead of `Lua.runtime.version`).
27
28### LuaCATS Definitions
29
30LuaLS can provide enhanced LSP autocompletion suggestions and type validation with the help of LuaCATS (Lua Comment and Type System) definitions. These definitions are available for many common Lua libraries, and local paths containing them can be specified via `workspace.library` in `luarc.json`. You can do this via relative paths if you checkout your definitions into the same partent directory of your project (`../playdate-luacats`, `../love2d`, etc). Alternatively you can create submodule(s) inside your project for each LuaCATS definition repo.
31
32### LÖVE (Love2D) {#love2d}
33
34To use [LÖVE (Love2D)](https://love2d.org/) in Zed, checkout [LuaCATS/love2d](https://github.com/LuaCATS/love2d) into a folder called `love2d-luacats` into the parent folder of your project:
35
36```sh
37cd .. && git clone https://github.com/LuaCATS/love2d love2d-luacats
38```
39
40Then in your `.luarc.json`:
41
42```
43{
44 "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
45 "runtime.version": "Lua 5.4",
46 "workspace.library": ["../love2d-luacats"],
47 "runtime.special": {
48 "love.filesystem.load": "loadfile"
49 }
50}
51```
52
53### PlaydateSDK
54
55To use [Playdate Lua SDK](https://play.date/dev/) in Zed, checkout [playdate-luacats](https://github.com/notpeter/playdate-luacats) into the parent folder of your project:
56
57```sh
58cd .. && git clone https://github.com/notpeter/playdate-luacats
59```
60
61Then in your `.luarc.json`:
62
63```json [settings]
64{
65 "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
66 "runtime.version": "Lua 5.4",
67 "runtime.nonstandardSymbol": [
68 "+=",
69 "-=",
70 "*=",
71 "/=",
72 "//=",
73 "%=",
74 "<<=",
75 ">>=",
76 "&=",
77 "|=",
78 "^="
79 ],
80 "diagnostics.severity": { "duplicate-set-field": "Hint" },
81 "diagnostics.globals": ["import"],
82 "workspace.library": ["../playdate-luacats"],
83 "format.defaultConfig": {
84 "indent_style": "space",
85 "indent_size": "4"
86 },
87 "format.enable": true,
88 "runtime.builtin": { "io": "disable", "os": "disable", "package": "disable" }
89}
90```
91
92### Inlay Hints
93
94To enable [Inlay Hints](../configuring-languages.md#inlay-hints) for LuaLS in Zed
95
961. Configure inlay hints in Settings ({#kb zed::OpenSettings}) under Languages > Lua, or add to your settings file:
97
98```json [settings]
99 "languages": {
100 "Lua": {
101 "inlay_hints": {
102 "enabled": true,
103 "show_type_hints": true,
104 "show_parameter_hints": true,
105 "show_other_hints": true
106 }
107 }
108 }
109```
110
1112. Add `"hint.enable": true` to your `.luarc.json`.
112
113## Formatting
114
115### LuaLS Formatting
116
117To enable auto-formatting with your LuaLS (provided by [CppCXY/EmmyLuaCodeStyle](https://github.com/CppCXY/EmmyLuaCodeStyle)) make sure you have `"format.enable": true,` in your .luarc.json:
118
119```json [settings]
120{
121 "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
122 "format.enable": true
123}
124```
125
126Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > Lua, or add to your settings file:
127
128```json [settings]
129{
130 "languages": {
131 "Lua": {
132 "format_on_save": "on",
133 "formatter": "language_server"
134 }
135 }
136}
137```
138
139You can customize various EmmyLuaCodeStyle style options via `.editorconfig`, see [lua.template.editorconfig](https://github.com/CppCXY/EmmyLuaCodeStyle/blob/master/lua.template.editorconfig) for all available options.
140
141### StyLua Formatting
142
143Alternatively to use [StyLua](https://github.com/JohnnyMorganz/StyLua) for auto-formatting:
144
1451. Install [StyLua](https://github.com/JohnnyMorganz/StyLua): `brew install stylua` or `cargo install stylua --features lua52,lua53,lua54,luau,luajit` (feel free to remove any Lua versions you don't need).
1462. Configure formatting in Settings ({#kb zed::OpenSettings}) under Languages > Lua, or add to your settings file:
147
148```json [settings]
149{
150 "languages": {
151 "Lua": {
152 "format_on_save": "on",
153 "formatter": {
154 "external": {
155 "command": "stylua",
156 "arguments": [
157 "--syntax=Lua54",
158 "--respect-ignores",
159 "--stdin-filepath",
160 "{buffer_path}",
161 "-"
162 ]
163 }
164 }
165 }
166 }
167}
168```
169
170You can specify various options to StyLua either on the command line above (like `--syntax=Lua54`) or in a `stylua.toml` in your project:
171
172```toml
173syntax = "Lua54"
174column_width = 100
175line_endings = "Unix"
176indent_type = "Spaces"
177indent_width = 4
178quote_style = "AutoPreferDouble"
179call_parentheses = "Always"
180collapse_simple_statement = "All"
181
182[sort_requires]
183enabled = true
184```
185
186For a complete list of available options, see: [StyLua Options](https://github.com/JohnnyMorganz/StyLua?tab=readme-ov-file#options).