wowlua-ls

A language server for World of Warcraft addon development. Built specifically for WoW Lua — not a general-purpose Lua LS with WoW bolted on.

Note

wowlua-ls is in beta. It's under active development and improving fast. If you run into issues, have feature requests, or want to contribute, join us on Discord — your feedback directly shapes the project.

Why wowlua-ls

• WoW API built in — 9,000+ API stubs for retail, classic, and classic era. No setup, no addon manager.
• Powerful generics — parameterized classes, constrained type parameters, backtick factory annotations, function-type projections (params<F>, returns<F>). Class-level generics propagate through method calls automatically.
• Metatable inference — understands setmetatable + __index, chained metatables, __call, operator metamethods. Your OOP patterns just work.
• Correlated narrowing — check one return value, and the LS narrows the rest. Eliminates false positives from multi-return functions.
• Mixin and template support — CreateFrame("Frame", nil, nil, "BackdropTemplate") returns Frame & BackdropTemplate automatically.
• Flavor filtering — declare flavors: ["retail", "classic"] and get warnings on APIs that don't exist in all your targets.
• Builder pattern — @builds-field tracks progressive type construction across chained method calls.

Full feature list and comparisons in the documentation.

Install

VS Code

Install wowlua-ls from the VS Code Marketplace. The extension bundles the language server binary — no separate install needed.

JetBrains IDEs

Download the plugin ZIP for your platform from GitHub Releases and install via Settings → Plugins → ⚙️ → Install Plugin from Disk.... Requires the LSP4IJ plugin. The release ZIPs bundle the language server binary — no separate install needed.

Other editors

git clone https://github.com/TradeSkillMaster/wowlua-ls.git
cd wowlua-ls
cargo build --release

The binary is at target/release/wowlua_ls. Run it as an LSP server over stdio for Lua files.

Quick start

Open a WoW addon folder. wowlua-ls automatically scans .lua files, loads WoW API stubs, and starts reporting diagnostics. No configuration required.

For project-specific settings, add a .wowluarc.json:

{
  "ignore": ["Libs/"],
  "flavors": ["retail", "classic"],
  "diagnostics": {
    "enable": ["need-check-nil"]
  }
}

See the Configuration guide for all options.

What it understands

Annotations

LuaLS-compatible ---@ annotations:

@param @return @type @class @enum @field @alias @overload @generic @cast @as @deprecated @nodiscard @meta @diagnostic @see

Plus WoW-specific extensions:

@defclass @builds-field @built-name @built-extends @type-narrows @correlated @flavor-narrows @constructor @accessor

Type system

Unions (A | B), intersections (A & B), arrays (T[]), generics (@generic T), parameterized classes (@class Foo<T>), anonymous table shapes ({field: type}), optionals (T?), lateinit (T!), tuple-union returns (@return (A, B) | (C, D)), variadic returns (@return ...T).

Diagnostics

55+ diagnostics covering type safety, nil checking, annotation correctness, code quality, and WoW-specific checks. Each one is individually configurable.

See the full diagnostic list.

CLI

Lint an addon from the command line:

wowlua_ls check path/to/addon
wowlua_ls check path/to/addon --severity hint

Exit code is 1 if any diagnostics are found — suitable for CI.

Documentation

Full documentation at tradeskillmaster.github.io/wowlua-ls

• Getting Started
• Annotation Guide
• Configuration Reference
• Contributing
• Discord

License

GPL-3.0