VS Code Setup

Set up EmmyLua Analyzer in Visual Studio Code

Overview

EmmyLua Analyzer provides a powerful language server for Lua development in VS Code through the official EmmyLua extension. Get intelligent code completion, type checking, and advanced analysis features.

Prerequisites:

• Visual Studio Code version 1.60 or higher
• EmmyLua Analyzer installed (cargo install emmylua_ls)

Installation

1. Install EmmyLua Extension

   Install the EmmyLua Extension from the VS Code Marketplace:

   Quick Install

   code --install-extension tangzx.emmylua
   
2. Configure Language Server Path

   If you installed emmylua_ls via cargo, the extension should automatically detect it. Otherwise, specify the path in your settings:

   settings.json

   {
     "emmylua.languageServer.path": "/path/to/emmylua_ls"
   }
   

   To find the installation path:

   which emmylua_ls
   
3. Create Configuration File

   Create a .emmyrc.json file in your project root for project-specific settings:

   .emmyrc.json

   {
     "$schema": "https://raw.githubusercontent.com/EmmyLuaLs/emmylua-analyzer-rust/refs/heads/main/crates/emmylua_code_analysis/resources/schema.json",
     "runtime": {
       "version": "LuaLatest"
     },
     "diagnostics": {
       "enable": true
     },
     "completion": {
       "enable": true,
       "callSnippet": true
     }
   }
   

Configuration

Workspace Settings

Configure EmmyLua in your workspace settings (.vscode/settings.json):

Basic Configuration

{
  "emmylua.completion.enable": true,
  "emmylua.diagnostics.enable": true,
  "emmylua.hint.enable": true,
  "emmylua.hover.enable": true
}

Runtime Version

Specify the Lua version for your project:

{
  "emmylua.runtime.version": "Lua5.4"
}

Available versions: Lua5.1, Lua5.2, Lua5.3, Lua5.4, LuaJIT, LuaLatest

Diagnostics Configuration

Customize diagnostic behavior:

{
  "emmylua.diagnostics.disable": ["undefined-global"],
  "emmylua.diagnostics.globals": ["vim", "awesome", "love"],
  "emmylua.diagnostics.severity": {
    "unused": "hint",
    "undefined-global": "warning"
  }
}

Code Formatting

Enable and configure the built-in formatter:

{
  "[lua]": {
    "editor.defaultFormatter": "tangzx.emmylua",
    "editor.formatOnSave": true
  },
  "emmylua.reformat.enable": true
}

Keyboard Shortcuts

Default Keybindings

Action	Windows/Linux	macOS
Go to Definition	F12	F12
Peek Definition	Alt+F12	Option+F12
Find References	Shift+F12	Shift+F12
Rename Symbol	F2	F2
Format Document	Shift+Alt+F	Shift+Option+F
Show Hover	Ctrl+K Ctrl+I	Cmd+K Cmd+I
Trigger Completion	Ctrl+Space	Cmd+Space

Custom Keybindings

Add custom keybindings in keybindings.json:

[
  {
    "key": "ctrl+shift+r",
    "command": "emmylua.restart",
    "when": "editorLangId == lua"
  },
  {
    "key": "ctrl+shift+d",
    "command": "emmylua.showReferences",
    "when": "editorLangId == lua"
  }
]

Features

Intelligent Code Completion

• Context-aware completions with type information
• Auto-import suggestions
• Function signature hints
• Snippet support

Type Checking

• Real-time type inference
• EmmyLua and Luacats annotation support
• Type mismatch detection
• Nil safety checks

Navigation

• Go to definition across files
• Find all references
• Workspace symbol search
• Document outline

Code Actions

• Quick fixes for common issues
• Add missing annotations
• Disable diagnostics for specific lines
• Extract to function/variable

Troubleshooting

Language server not starting

Solution:

1. Check if emmylua_ls is installed:

   emmylua_ls --version
   

2. Verify the language server path in settings:

   {
     "emmylua.languageServer.path": "/path/to/emmylua_ls"
   }
   

3. Check the Output panel (View > Output) and select “EmmyLua” from the dropdown

4. Restart the language server:

   • Press Ctrl+Shift+P (Cmd+Shift+P on macOS)
   • Run command: EmmyLua: Restart Language Server

Completions not working

Solution:

1. Ensure completion is enabled:

   {
     "emmylua.completion.enable": true
   }
   

2. Check if the file is recognized as Lua (bottom-right corner of VS Code)

3. Verify workspace indexing is complete (check status bar)

4. Try reindexing the workspace:

   • Command: EmmyLua: Reindex Workspace

False diagnostics/errors

Solution:

1. Add global variables to the whitelist:

   {
     "emmylua.diagnostics.globals": ["myGlobal"]
   }
   

2. Disable specific diagnostics:

   {
     "emmylua.diagnostics.disable": ["undefined-global"]
   }
   

3. Use inline diagnostic control:

   ---@diagnostic disable-next-line: undefined-global
   print(myGlobal)
   

4. Configure library paths:

   {
     "emmylua.workspace.library": ["./libs"]
   }
   

Slow performance with large projects

Solution:

1. Ignore unnecessary directories:

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

2. Use glob patterns to exclude files:

   {
     "emmylua.workspace.ignoreGlobs": [
       "**/*.log",
       "**/test_*"
     ]
   }
   

3. Adjust preload file size limit:

   {
     "emmylua.workspace.preloadFileSize": 1000
   }
   

4. Disable features you don’t need:

   {
     "emmylua.codeLens.enable": false,
     "emmylua.semanticTokens.enable": false
   }
   

Formatting not working

Solution:

1. Set EmmyLua as the default formatter:

   {
     "[lua]": {
       "editor.defaultFormatter": "tangzx.emmylua"
     }
   }
   

2. Enable formatting:

   {
     "emmylua.reformat.enable": true
   }
   

3. Check for conflicting formatters (disable other Lua formatters)

4. Try formatting manually: Shift+Alt+F (Windows/Linux) or Shift+Option+F (macOS)

Multi-root Workspaces

For multi-root workspaces, configure each workspace folder separately:

workspace.code-workspace

{
  "folders": [
    {
      "path": "project1",
      "settings": {
        "emmylua.runtime.version": "Lua5.1"
      }
    },
    {
      "path": "project2",
      "settings": {
        "emmylua.runtime.version": "LuaJIT"
      }
    }
  ]
}

Next Steps

Configuration

Learn about all available configuration options

Annotations

Add type annotations to your code

Features

Explore all language server features

Troubleshooting

Optimize performance for large projects