1# Lua
2
3Lua support is available through the [Lua extension](https://github.com/zed-extensions/lua).
4
5- Tree-sitter: [tree-sitter-grammars/tree-sitter-lua](https://github.com/tree-sitter-grammars/tree-sitter-lua)
6- Language server: [LuaLS/lua-language-server](https://github.com/LuaLS/lua-language-server)
7
8## luarc.json
9
10To configure LuaLS you can create a `.luarc.json` file in the root of your workspace.
11
12```json
13{
14 "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
15 "runtime.version": "Lua 5.4",
16 "format.enable": true,
17 "workspace.library": ["../somedir/library"]
18}
19```
20
21See [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`).
22
23### LuaCATS Definitions
24
25LuaLS 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.
26
27### LÖVE (Love2D) {#love2d}
28
29To 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:
30
31```sh
32cd .. && git clone https://github.com/LuaCATS/love2d love2d-luacats
33```
34
35Then in your `.luarc.json`:
36
37```
38{
39 "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
40 "runtime.version": "Lua 5.4",
41 "workspace.library": ["../love2d-luacats"],
42 "runtime.special": {
43 "love.filesystem.load": "loadfile"
44 }
45}
46```
47
48### PlaydateSDK
49
50To 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:
51
52```sh
53cd .. && git clone https://github.com/notpeter/playdate-luacats
54```
55
56Then in your `.luarc.json`:
57
58```json
59{
60 "$schema": "https://raw.githubusercontent.com/LuaLS/vscode-lua/master/setting/schema.json",
61 "runtime.version": "Lua 5.4",
62 "runtime.nonstandardSymbol": [
63 "+=",
64 "-=",
65 "*=",
66 "/=",
67 "//=",
68 "%=",
69 "<<=",
70 ">>=",
71 "&=",
72 "|=",
73 "^="
74 ],
75 "diagnostics.severity": { "duplicate-set-field": "Hint" },
76 "diagnostics.globals": ["import"],
77 "workspace.library": ["../playdate-luacats"],
78 "format.defaultConfig": {
79 "indent_style": "space",
80 "indent_size": "4"
81 },
82 "format.enable": true,
83 "runtime.builtin": { "io": "disable", "os": "disable", "package": "disable" }
84}
85```
86
87### Inlay Hints
88
89To enable [Inlay Hints](../configuring-languages.md#inlay-hints) for LuaLS in Zed
90
911. Add the following to your Zed settings.json:
92
93```json
94 "languages": {
95 "Lua": {
96 "inlay_hints": {
97 "enabled": true,
98 "show_type_hints": true,
99 "show_parameter_hints": true,
100 "show_other_hints": true
101 }
102 }
103 }
104```
105
1062. Add `"hint.enable": true` to your `.luarc.json`.
107
108## Formatting
109
110### LuaLS Formatting
111
112To 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:
113
114```json
115{
116 "$schema": "https://raw.githubusercontent.com/sumneko/vscode-lua/master/setting/schema.json",
117 "format.enable": true
118}
119```
120
121Then add the following to your Zed `settings.json`:
122
123```json
124{
125 "languages": {
126 "Lua": {
127 "format_on_save": "on",
128 "formatter": "language_server"
129 }
130 }
131}
132```
133
134You 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.
135
136### StyLua Formatting
137
138Alternatively to use [StyLua](https://github.com/JohnnyMorganz/StyLua) for auto-formatting:
139
1401. 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).
1412. Add the following to your `settings.json`:
142
143```json
144{
145 "languages": {
146 "Lua": {
147 "format_on_save": "on",
148 "formatter": {
149 "external": {
150 "command": "stylua",
151 "arguments": [
152 "--syntax=Lua54",
153 "--respect-ignores",
154 "--stdin-filepath",
155 "{buffer_path}",
156 "-"
157 ]
158 }
159 }
160 }
161 }
162}
163```
164
165You can specify various options to StyLua either on the command line above (like `--syntax=Lua54`) or in a `stylua.toml` in your workspace:
166
167```toml
168syntax = "Lua54"
169column_width = 100
170line_endings = "Unix"
171indent_type = "Spaces"
172indent_width = 4
173quote_style = "AutoPreferDouble"
174call_parentheses = "Always"
175collapse_simple_statement = "All"
176
177[sort_requires]
178enabled = true
179```
180
181For a complete list of available options, see: [StyLua Options](https://github.com/JohnnyMorganz/StyLua?tab=readme-ov-file#options).