.emmyrc.json Reference

This page provides a complete reference for all configuration options available in .emmyrc.json.

Complete Configuration Example

View Complete Configuration Template

{
  "$schema": "https://raw.githubusercontent.com/EmmyLuaLs/emmylua-analyzer-rust/refs/heads/main/crates/emmylua_code_analysis/resources/schema.json",
  "codeAction": {
    "insertSpace": false
  },
  "codeLens": {
    "enable": true
  },
  "completion": {
    "enable": true,
    "autoRequire": true,
    "autoRequireFunction": "require",
    "autoRequireNamingConvention": "keep",
    "autoRequireSeparator": ".",
    "callSnippet": false,
    "postfix": "@",
    "baseFunctionIncludesName": true
  },
  "diagnostics": {
    "enable": true,
    "disable": [],
    "enables": [],
    "globals": [],
    "globalsRegex": [],
    "severity": {},
    "diagnosticInterval": 500
  },
  "doc": {
    "syntax": "md",
    "knownTags": [],
    "privateName": []
  },
  "documentColor": {
    "enable": true
  },
  "hover": {
    "enable": true,
    "customDetail": null
  },
  "hint": {
    "enable": true,
    "paramHint": true,
    "indexHint": true,
    "localHint": true,
    "overrideHint": true,
    "metaCallHint": true,
    "enumParamHint": false
  },
  "inlineValues": {
    "enable": true
  },
  "references": {
    "enable": true,
    "fuzzySearch": true,
    "shortStringSearch": false
  },
  "format": {
    "externalTool": null,
    "externalToolRangeFormat": null,
    "useDiff": false
  },
  "resource": {
    "paths": []
  },
  "runtime": {
    "version": "LuaLatest",
    "requireLikeFunction": [],
    "frameworkVersions": [],
    "extensions": [],
    "requirePattern": [],
    "classDefaultCall": {
      "functionName": "",
      "forceNonColon": false,
      "forceReturnSelf": false
    },
    "nonstandardSymbol": [],
    "special": {}
  },
  "semanticTokens": {
    "enable": true,
    "renderDocumentationMarkup": false
  },
  "signature": {
    "detailSignatureHelper": true
  },
  "strict": {
    "requirePath": false,
    "typeCall": false,
    "arrayIndex": true,
    "metaOverrideFileDefine": true,
    "docBaseConstMatchBaseType": true,
    "requireExportGlobal": false
  },
  "workspace": {
    "ignoreDir": [],
    "ignoreGlobs": [],
    "library": [],
    "workspaceRoots": [],
    "preloadFileSize": 0,
    "encoding": "utf-8",
    "moduleMap": [],
    "packageDirs": [],
    "reindexDuration": 5000,
    "enableReindex": false
  }
}

Code Actions

Configure code quick fixes and refactoring operations.

codeAction.insertSpace

boolean

default:"false"

Insert space when adding @diagnostic disable-next-line after --- comments.

Example

When true:

--- <space>@diagnostic disable-next-line: undefined-global

When false:

---@diagnostic disable-next-line: undefined-global

Code Lens

CodeLens provides inline actionable information in your code.

codeLens.enable

boolean

default:"true"

Enable or disable CodeLens functionality. CodeLens displays contextual information above functions, classes, and other declarations.

Completion

Intelligent code completion configuration for enhanced coding efficiency.

completion.enable

boolean

default:"true"

Enable or disable code completion feature.

completion.autoRequire

boolean

default:"true"

Automatically insert call to require when autocompletion inserts objects from other modules.

-- Typing "MyClass" auto-completes to:
local MyClass = require("lib.MyClass")
local instance = MyClass.new()

completion.autoRequireFunction

string

default:"require"

The function name used for auto-requiring modules. Useful for custom module systems.

{
  "completion": {
    "autoRequireFunction": "import"  // Use import() instead of require()
  }
}

completion.autoRequireNamingConvention

string

default:"keep"

The naming convention for auto-required filenames.Options:

keep: Keep original filename
camel-case: Convert to camelCase
snake-case: Convert to snake_case
pascal-case: Convert to PascalCase
keep-class: Use class name when returning class definition, otherwise keep original

local my_module = require("my_module")

completion.autoRequireSeparator

string

default:"."

Separator used in auto-require paths.

require("lib.utils.string")

completion.callSnippet

boolean

default:"false"

Enable function call snippets in completions. When enabled, function completions include parameter placeholders.

string.format("${1:format}", ${2:...})

completion.postfix

string

default:"@"

Symbol used to trigger postfix autocompletion.Options: @, ., :

Postfix Completion Example

-- With postfix "@"
myVar@if    -- Expands to: if myVar then ... end
myVar@for   -- Expands to: for _, v in pairs(myVar) do ... end
myVar@not   -- Expands to: if not myVar then ... end

completion.baseFunctionIncludesName

boolean

default:"true"

Whether to include the name in base function completion.

function name() end

Diagnostics

See the Diagnostics Configuration page for detailed information about diagnostic settings.

diagnostics.enable

boolean

default:"true"

Enable or disable the diagnostic system.

diagnostics.diagnosticInterval

integer

default:"500"

Delay between opening/changing a file and scanning it for errors, in milliseconds.

Documentation

Configure how documentation comments are parsed and displayed.

doc.syntax

string

default:"md"

Documentation comment syntax type.Options:

md: Markdown syntax
myst: MyST (Markedly Structured Text) syntax
rst: reStructuredText syntax
none: No special syntax parsing

doc.knownTags

string[]

default:"[]"

List of custom documentation tags that should be recognized by the analyzer.

{
  "doc": {
    "knownTags": ["@author", "@since", "@example"]
  }
}

doc.privateName

string[]

default:"[]"

Treat specific field names as private. Fields matching these patterns can only be accessed in the class where they’re defined.

{
  "doc": {
    "privateName": ["m_*", "_*"]  // m_id, _internal are private
  }
}

Document Color

Color highlighting for color values in strings.

documentColor.enable

boolean

default:"true"

Enable parsing strings for color tags and showing a color picker next to them.

Example

-- Color picker appears for these:
local red = "#FF0000"
local blue = "rgb(0, 0, 255)"
local green = "rgba(0, 255, 0, 1.0)"

Formatting

See the Formatting Configuration page for detailed information about formatting settings.

Hover

Configure hover documentation display.

hover.enable

boolean

default:"true"

Enable showing documentation on hover.

hover.customDetail

integer | null

default:"null"

The detail level of hover information. Default is null (use default detail level). Set to a number between 1 and 255 to customize the verbosity of hover information.

Inline Hints

Intelligent inline hint system for viewing type information without mouse hover.

hint.enable

boolean

default:"true"

Enable or disable inline hints globally.

hint.paramHint

boolean

default:"true"

Show function parameter names and types as inline hints.

-- With paramHint enabled:
string.format(format: "%s", ...: "hello")

hint.indexHint

boolean

default:"true"

Show named array indexes for multi-line table indexing.

local array = {
  [1] = 1, -- hint: name
}
print(array[1]) -- hint: name

hint.localHint

boolean

default:"true"

Show type hints for local variables.

local value = getValue() -- hint: string

hint.overrideHint

boolean

default:"true"

Show hints when methods override functions from base class.

function Child:method() -- hint: override Base.method
end

hint.metaCallHint

boolean

default:"true"

Show hint when calling an object results in a call to its metatable’s __call function.

myObject() -- hint: calls __call metamethod

hint.enumParamHint

boolean

default:"false"

Show name of enumerator when passing a literal value to a function that expects an enum.

---@enum Level
local Level = { Info = 1, Error = 2 }

---@param l Level
function print_level(l) end

print_level(1) -- hint: Level.Info

Inline Values

Display variable values inline during debugging.

inlineValues.enable

boolean

default:"true"

Show inline values during debug sessions.

References

Configure how symbol references are found.

references.enable

boolean

default:"true"

Enable searching for symbol usages.

references.fuzzySearch

boolean

default:"true"

Use fuzzy search when searching for symbol usages and normal search didn’t find anything. This helps find references even when symbol names don’t exactly match.

references.shortStringSearch

boolean

default:"false"

Also search for symbol usages in string literals. Useful for finding dynamic references but may produce false positives.

Resource Paths

Configure resource file directories for path completion.

resource.paths

string[]

default:"[]"

List of resource file root directories. Configuring resource directories allows EmmyLua to provide file path completion and navigation.

{
  "resource": {
    "paths": ["./assets", "./resources", "./data"]
  }
}

Runtime

Configure Lua runtime environment and version features.

runtime.version

string

default:"LuaLatest"

Lua version selection.Options:

Lua5.1: Classic version
LuaJIT: High performance JIT compiler
Lua5.2: Enhanced features
Lua5.3: Integer support
Lua5.4: Latest stable features
Lua5.5: Experimental features
LuaLatest: Latest feature set

runtime.requireLikeFunction

string[]

default:"[]"

List of functions that behave like require. The analyzer will treat these functions similarly to require for module resolution.

{
  "runtime": {
    "requireLikeFunction": ["import", "load", "dofile", "loadfile"]
  }
}

runtime.frameworkVersions

string[]

default:"[]"

Framework version identifiers. Used to load framework-specific definitions.

{
  "runtime": {
    "frameworkVersions": ["love2d", "openresty", "nginx"]
  }
}

runtime.extensions

string[]

default:"[]"

Additional file extensions to recognize as Lua files.

{
  "runtime": {
    "extensions": [".lua", ".lua.txt", ".luau"]
  }
}

runtime.requirePattern

string[]

default:"[]"

Require pattern matching rules. Defines how module paths are resolved.

{
  "runtime": {
    "requirePattern": ["?.lua", "?/init.lua", "lib/?.lua"]
  }
}

runtime.nonstandardSymbol

string[]

default:"[]"

Enable non-standard Lua symbols.Options: // (C++ style comments), /**/ (C style block comments), ` (backticks), +=, -=, *=, /=, %=, ^=, //=, |=, &=, <<=, >>=, ||, &&, !, !=, continue

{
  "runtime": {
    "nonstandardSymbol": ["continue", "//", "/**/"]
  }
}

runtime.special

object

default:"{}"

Map special function names to their behavior types.Options: require, error, assert, type, setmetatable

{
  "runtime": {
    "special": {
      "errorf": "error",
      "assertTrue": "assert"
    }
  }
}

Semantic Tokens

Configure semantic syntax highlighting.

semanticTokens.enable

boolean

default:"true"

Enable semantic tokens for enhanced syntax highlighting based on code analysis.

semanticTokens.renderDocumentationMarkup

boolean

default:"false"

Render Markdown/RST in documentation. Requires doc.syntax to be set for this option to have effect.

Signature Help

Configure function signature help.

signature.detailSignatureHelper

boolean

default:"true"

Show detailed function signature help with parameter types and descriptions.

Strict Mode

Strict mode configuration controls the strictness of type checking and code analysis.

strict.requirePath

boolean

default:"false"

When enabled, require paths must start from specified root directories. When disabled, flexible path resolution is used.

strict.typeCall

boolean

default:"false"

When enabled, manual overload definitions are required for callable types. When disabled, calling a type returns the type itself.

strict.arrayIndex

boolean

default:"true"

When enabled, strict adherence to array indexing rules is enforced. Arrays must use integer indices.

strict.metaOverrideFileDefine

boolean

default:"true"

When enabled, meta definitions (from libraries) override definitions in files. When disabled, behavior is similar to lua-language-server.

strict.docBaseConstMatchBaseType

boolean

default:"true"

Base constant types defined in doc can match base types. For example, allows int to match ---@alias id 1|2|3, same for string literals.

strict.requireExportGlobal

boolean

default:"false"

Limits visibility of third-party libraries. When enabled, libraries must use ---@export global annotation to be importable.

Workspace

Workspace and project structure configuration.

workspace.ignoreDir

string[]

default:"[]"

List of directories to ignore. Supports both relative and absolute paths.

{
  "workspace": {
    "ignoreDir": ["build", "dist", "node_modules", ".git"]
  }
}

workspace.ignoreGlobs

string[]

default:"[]"

Glob pattern-based file ignore rules.

{
  "workspace": {
    "ignoreGlobs": ["*.log", "*.tmp", "test_*", "**/*.spec.lua"]
  }
}

workspace.library

(string | object)[]

default:"[]"

Library directory paths. Can be a simple string path or an object with path and ignore rules.

{
  "workspace": {
    "library": ["/usr/local/lib/lua", "./libs"]
  }
}

workspace.workspaceRoots

string[]

default:"[]"

Workspace root directory list for multi-root workspaces.

{
  "workspace": {
    "workspaceRoots": ["Assets/Scripts/Lua", "Assets/Editor/Lua"]
  }
}

workspace.packageDirs

string[]

default:"[]"

Package directories. Treats the parent directory as a library, but only adds files from the specified directory.

{
  "workspace": {
    "packageDirs": ["/usr/local/share/lua/5.1/module"]
  }
}

workspace.encoding

string

default:"utf-8"

File encoding format. Change this if your project uses a different encoding.

workspace.moduleMap

object[]

default:"[]"

Module path mapping rules using regular expressions.

{
  "workspace": {
    "moduleMap": [
      {
        "pattern": "^lib(.*)$",
        "replace": "script$1"
      },
      {
        "pattern": "^engine/(.*)$",
        "replace": "game/$1"
      }
    ]
  }
}

workspace.reindexDuration

integer

default:"5000"

Delay between changing a file and triggering full project reindex, in milliseconds.

workspace.enableReindex

boolean

default:"false"

Enable full project reindex after changing a file. This can be resource-intensive for large projects.

Getting Started

CLI Tools

Configuration

Features

Complete Configuration Example

Code Actions

Code Lens

Completion

Diagnostics

Documentation

Document Color

Formatting

Hover

Inline Hints

Inline Values

References

Resource Paths

Runtime

Semantic Tokens

Signature Help

Strict Mode

Workspace

Build docs developers (and LLMs) love

Getting Started

CLI Tools

Configuration

Features

​Complete Configuration Example

​Code Actions

​Code Lens

​Completion

​Diagnostics

​Documentation

​Document Color

​Formatting

​Hover

​Inline Hints

​Inline Values

​References

​Resource Paths

​Runtime

​Semantic Tokens

​Signature Help

​Strict Mode

​Workspace

Build docs developers (and LLMs) love

Complete Configuration Example

Code Actions

Code Lens

Completion

Diagnostics

Documentation

Document Color

Formatting

Hover

Inline Hints

Inline Values

References

Resource Paths

Runtime

Semantic Tokens

Signature Help

Strict Mode

Workspace