IntelliJ IDEA Setup

Set up EmmyLua Analyzer in IntelliJ IDEA and other JetBrains IDEs

Overview

EmmyLua Analyzer provides native integration with IntelliJ IDEA and other JetBrains IDEs through the EmmyLua2 plugin. Get a fully-featured Lua development environment with intelligent code completion, refactoring, and debugging support.

Prerequisites:

• IntelliJ IDEA 2023.1 or higher (Community or Ultimate)
• Also supports: PyCharm, WebStorm, CLion, GoLand, and other JetBrains IDEs

Installation

1. Install EmmyLua2 Plugin

   Install the EmmyLua2 Plugin from the JetBrains Marketplace:

   In-IDE Installation (Recommended)

   1. Open IntelliJ IDEA
   2. Go to File → Settings (Ctrl+Alt+S)
   3. Select Plugins from the left sidebar
   4. Click the Marketplace tab
   5. Search for "EmmyLua2"
   6. Click Install
   7. Restart the IDE when prompted
   
2. Create or Open Lua Project

   Set up your Lua project:

   1. New Project:

      • File → New → Project
      • Select “Empty Project” or “Lua” (if available)
      • Set project location and name
      • Click Create

   2. Existing Project:

      • File → Open
      • Select your project directory
      • Click OK
3. Configure Project SDK

   Set up the Lua SDK for your project:

   1. Go to File → Project Structure (Ctrl+Alt+Shift+S)
   2. Select “Project” in the left sidebar
   3. Under “Project SDK”, click “Add SDK” → “Lua SDK”
   4. Choose your Lua version or specify custom Lua installation
   5. Click Apply and OK

Plugin Configuration

Plugin Settings

Access EmmyLua2 settings: File → Settings → Languages & Frameworks → EmmyLua

Basic Settings

✓ Enable type checking
✓ Enable code completion
✓ Enable inlay hints
✓ Show parameter hints
✓ Show type hints

Language Server Integration

Configure the EmmyLua Analyzer language server:

1. Go to Settings → Languages & Frameworks → EmmyLua → Language Server
2. Select “Use external language server”
3. Specify the path to emmylua_ls executable:
   /path/to/emmylua_ls
   
4. Configure server options:
   • Enable semantic highlighting
   • Enable diagnostics
   • Set log level (info/debug/warn)

Project-Specific Configuration

Create .emmyrc.json in your project root:

.emmyrc.json

{
  "$schema": "https://raw.githubusercontent.com/EmmyLuaLs/emmylua-analyzer-rust/refs/heads/main/crates/emmylua_code_analysis/resources/schema.json",
  "runtime": {
    "version": "Lua5.4",
    "requireLikeFunction": ["require", "import"]
  },
  "diagnostics": {
    "enable": true,
    "globals": ["app", "framework"],
    "severity": {
      "unused": "hint",
      "undefined-global": "warning"
    }
  },
  "workspace": {
    "library": ["./libs", "./vendor"],
    "ignoreDir": ["build", "test", "node_modules"]
  },
  "completion": {
    "enable": true,
    "callSnippet": true,
    "autoRequire": true
  }
}

Features

Code Completion

Intelligent completions with:

• Context-aware suggestions
• Type-based filtering
• Auto-import of modules
• Function parameter hints
• Documentation preview

Trigger: Ctrl+Space

Type Checking

Real-time type analysis:

• EmmyLua annotations support
• Type inference
• Nil safety checks
• Function signature validation
• Return type checking

Navigation

Powerful code navigation:

Feature	Shortcut
Go to Declaration	Ctrl+B or Ctrl+Click
Find Usages	Alt+F7
Go to Implementation	Ctrl+Alt+B
Go to Type Definition	Ctrl+Shift+B
File Structure	Ctrl+F12
Search Everywhere	Double Shift
Navigate Back/Forward	Ctrl+Alt+Left/Right

Refactoring

Advanced refactoring tools:

Feature	Shortcut
Rename	Shift+F6
Extract Variable	Ctrl+Alt+V
Extract Function	Ctrl+Alt+M
Inline Variable	Ctrl+Alt+N
Change Signature	Ctrl+F6
Move	F6
Safe Delete	Alt+Delete

Code Generation

Feature	Shortcut
Generate Code	Alt+Insert
Override Methods	Ctrl+O
Generate Docs	/** + Enter
Surround With	Ctrl+Alt+T

Debugging

Integrated debugging support:

1. Set Breakpoints: Click in the gutter or press Ctrl+F8
2. Start Debugging: Click the debug icon or press Shift+F9
3. Debug Controls:
   • Step Over: F8
   • Step Into: F7
   • Step Out: Shift+F8
   • Resume: F9
   • Evaluate Expression: Alt+F8

Keyboard Shortcuts

Essential Shortcuts

Navigation

Ctrl+N          Go to Class
Ctrl+Shift+N    Go to File
Ctrl+E          Recent Files
Ctrl+B          Go to Declaration
Alt+F7          Find Usages
Ctrl+F12        File Structure
Double Shift    Search Everywhere

Custom Keymap

Customize shortcuts:

1. Go to File → Settings → Keymap
2. Search for EmmyLua actions
3. Right-click → Add Keyboard Shortcut
4. Press your desired key combination

Integration Features

Version Control

Built-in Git integration:

• Commit: Ctrl+K
• Push: Ctrl+Shift+K
• Pull: Ctrl+T
• Show History: Alt+9
• Compare with Branch: Ctrl+D in VCS menu

External Tools

Integrate external Lua tools:

1. Go to Settings → Tools → External Tools
2. Click + to add new tool
3. Example - Add EmmyLua Check:
   • Name: EmmyLua Check
   • Program: /path/to/emmylua_check
   • Arguments: $FilePath$
   • Working directory: $ProjectFileDir$

Code Style

Configure Lua code style:

1. Go to Settings → Editor → Code Style → Lua
2. Configure:
   • Indentation (spaces/tabs)
   • Continuation indent
   • Spaces around operators
   • Blank lines
   • Wrapping and braces

File and Code Templates

Create custom templates:

1. Go to Settings → Editor → File and Code Templates
2. Add Lua file template:
   ---@module ${NAME}
   ---@author ${USER}
   ---@date ${DATE}
   
   local M = {}
   
   -- Module implementation
   
   return M
   

Live Templates

Create code snippets for common patterns:

1. Go to Settings → Editor → Live Templates
2. Click + → Live Template
3. Example templates:

func

---@param $PARAM1$ $TYPE1$
---@return $RETURN_TYPE$
function $NAME$($PARAM1$)
    $END$
end

class

---@class $NAME$
---@field $FIELD$ $TYPE$
local $NAME$ = {}
$NAME$.__index = $NAME$

function $NAME$:new()
    local instance = setmetatable({}, self)
    $END$
    return instance
end

return $NAME$

Troubleshooting

Plugin not working after installation

Solution:

1. Restart IntelliJ IDEA
2. Verify plugin is enabled:
   • Go to Settings → Plugins
   • Ensure EmmyLua2 is checked
3. Check plugin version is compatible with your IDE version
4. Try reinstalling the plugin
5. Check IDE logs: Help → Show Log in Explorer

Code completion not working

Solution:

1. Verify file is recognized as Lua:
   • Check file extension (.lua)
   • Right-click file → Associate with File Type → Lua
2. Rebuild project indices:
   • File → Invalidate Caches → Invalidate and Restart
3. Check completion settings:
   • Settings → Editor → General → Code Completion
   • Enable “Show suggestions as you type”
4. Ensure project SDK is configured:
   • File → Project Structure → Project → Project SDK

Type checking errors are incorrect

Solution:

1. Add global variables to configuration:

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

2. Use inline annotations:

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

3. Configure library paths:

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

4. Adjust diagnostic severity:

   {
     "diagnostics": {
       "severity": {
         "undefined-global": "hint"
       }
     }
   }
   

Language server not connecting

Solution:

1. Verify emmylua_ls is installed:

   emmylua_ls --version
   

2. Check language server path in settings

3. Enable language server logging:

   • Settings → EmmyLua → Language Server
   • Set log level to “debug”
   • Check logs in project directory

4. Restart language server:

   • Tools → EmmyLua → Restart Language Server

5. Try stdio mode instead of TCP

IDE is slow with large Lua project

Solution:

1. Exclude build directories:

   • Right-click folder → Mark Directory as → Excluded

2. Increase IDE memory:

   • Help → Change Memory Settings
   • Set to at least 2048 MB

3. Ignore directories in .emmyrc.json:

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

4. Disable unused plugins:

   • Settings → Plugins
   • Disable plugins you don’t use

5. Power Save Mode:

   • File → Power Save Mode (for temporary relief)

Debugging not working

Solution:

1. Ensure debug configuration is set up:

   • Run → Edit Configurations
   • Add new Lua configuration

2. Check Lua interpreter path

3. Install Lua debugger if needed:

   • mobdebug for standard Lua
   • LuaJIT debugger for LuaJIT projects

4. Verify breakpoints are set in reachable code

5. Check debug console for errors

Multi-Module Projects

For projects with multiple Lua modules:

1. Configure Module Structure:

   • File → Project Structure → Modules
   • Add modules for each component

2. Set Module Dependencies:

   • Select module → Dependencies tab
   • Add module dependencies

3. Configure Source Roots:

   • Right-click folder → Mark Directory as
   • Choose: Sources Root, Test Sources Root, or Excluded

Remote Development

Develop on remote servers:

1. Enable Remote Development:

   • Install “Remote Development” plugin
   • Or use IntelliJ IDEA Ultimate’s built-in SSH support

2. Configure SSH Connection:

   • File → Remote Development → SSH
   • Add connection details

3. Deploy on Save:

   • Tools → Deployment → Configuration
   • Set up automatic upload

Next Steps

Configuration

Master all configuration options

Annotations

Write better type annotations

Features

Explore IDE features

Code Style

Set up code formatting