Skip to main content
EmmyLua Analyzer uses JSON-based configuration files to customize its behavior. The primary configuration file is .emmyrc.json, which provides comprehensive control over language server features, diagnostics, formatting, and workspace settings.

​
Configuration Files

​
Primary Configuration

​
.emmyrc.json
file
The main configuration file for EmmyLua Analyzer. Place this file in your project root directory.Priority: HighestFormat: JSON with schema support

​
Compatibility Configuration

​
.luarc.json
file
Legacy compatibility configuration file.Auto Conversion: Automatically converts to .emmyrc.json formatOverride Rules: Settings are overridden by .emmyrc.json if both existCompatibility: Partial feature support only
The .emmyrc.json format is richer and more flexible. We recommend using this format for the best experience.

​
Schema Support

For intelligent completion and validation of configuration files, add a schema reference to your configuration: 
{
  "$schema": "https://raw.githubusercontent.com/EmmyLuaLs/emmylua-analyzer-rust/refs/heads/main/crates/emmylua_code_analysis/resources/schema.json"
}
With the schema reference, your editor will provide:
  • Auto-completion for configuration keys
  • Inline documentation for each setting
  • Validation of values and types
  • Quick navigation to related settings

​
Configuration Location

​
Project Root Directory

Place .emmyrc.json in the root directory of your Lua project: 
your-project/
├── .emmyrc.json          # Configuration file
├── src/
│   ├── main.lua
│   └── utils.lua
└── lib/
    └── external.lua

​
Workspace Configuration

For multi-root workspaces, you can:
  1. Global Configuration: Place .emmyrc.json at the workspace root
  2. Project-Specific: Each workspace root can have its own .emmyrc.json
  3. Workspace Roots: Use the workspace.workspaceRoots setting to define multiple root directories
{
  "workspace": {
    "library": ["./lib"],
    "ignoreDir": ["build", "dist"]
  }
}

​
Configuration Hierarchy

EmmyLua Analyzer applies configuration in the following order:
  1. Default Values: Built-in defaults for all settings
  2. .luarc.json: Legacy configuration (if present)
  3. .emmyrc.json: Primary configuration (overrides previous)
  4. File-Level Annotations: Inline ---@diagnostic comments (highest priority)
-- Even if diagnostics are enabled globally in .emmyrc.json,
-- this file-level annotation takes precedence
---@diagnostic disable: undefined-global

GLOBAL_VAR = "allowed here"
The file-level annotation overrides the global configuration for this specific file.

​
Configuration Categories

EmmyLua configuration is organized into the following categories:

Language Features

Completion, hover, hints, references, and code actions

Diagnostics

Error detection, type checking, and diagnostic rules

Formatting

Code formatting and external tool integration

Workspace

File discovery, libraries, and project structure

Runtime

Lua version, require patterns, and special symbols

Strict Mode

Type checking strictness and verification rules

​
Quick Start

Create a basic configuration file to get started:
1

Create .emmyrc.json

Create a new file named .emmyrc.json in your project root directory.
2

Add Schema Reference

Add the schema URL for intelligent editing:
{
  "$schema": "https://raw.githubusercontent.com/EmmyLuaLs/emmylua-analyzer-rust/refs/heads/main/crates/emmylua_code_analysis/resources/schema.json"
}
3

Configure Basic Settings

Add your initial configuration:
{
  "$schema": "https://raw.githubusercontent.com/EmmyLuaLs/emmylua-analyzer-rust/refs/heads/main/crates/emmylua_code_analysis/resources/schema.json",
  "runtime": {
    "version": "Lua5.4"
  },
  "workspace": {
    "library": ["./lib"],
    "ignoreDir": ["build"]
  },
  "diagnostics": {
    "globals": ["vim", "love"]
  }
}
4

Test Configuration

Reload your editor or restart the language server to apply the configuration.

​
Common Configuration Patterns

​
Game Development (LÖVE2D)

{
  "runtime": {
    "version": "LuaJIT",
    "frameworkVersions": ["love2d"]
  },
  "diagnostics": {
    "globals": ["love"]
  },
  "workspace": {
    "library": ["./lib/love2d"]
  }
}

​
Neovim Plugin Development

{
  "runtime": {
    "version": "LuaJIT"
  },
  "diagnostics": {
    "globals": ["vim"]
  },
  "workspace": {
    "library": [
      "~/.local/share/nvim/runtime/lua",
      "./lua"
    ],
    "ignoreDir": ["build", ".git"]
  }
}

​
OpenResty Development

{
  "runtime": {
    "version": "LuaJIT",
    "frameworkVersions": ["openresty"],
    "requireLikeFunction": ["require", "ngx.require"]
  },
  "diagnostics": {
    "globals": ["ngx", "ndk"]
  }
}

​
Strict Type Checking

{
  "strict": {
    "requirePath": true,
    "typeCall": true,
    "arrayIndex": true
  },
  "diagnostics": {
    "severity": {
      "param-type-mismatch": "error",
      "return-type-mismatch": "error",
      "assign-type-mismatch": "error"
    }
  }
}

​
Next Steps

Complete Configuration Reference

Explore all available configuration options

Diagnostic Configuration

Configure diagnostic rules and severity levels

Formatting Setup

Set up code formatting with external tools

Workspace Settings

Configure project structure and libraries

Build docs developers (and LLMs) love

Get started for freeTalk to us