IntelliJ IDEA Setup

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

Install EmmyLua2 Plugin

Install the EmmyLua2 Plugin from the JetBrains Marketplace:

Open IntelliJ IDEA
Go to File → Settings (Ctrl+Alt+S)
Select Plugins from the left sidebar
Click the Marketplace tab
Search for "EmmyLua2"
Click Install
Restart the IDE when prompted

Create or Open Lua Project

Set up your Lua project:

New Project:
- File → New → Project
- Select “Empty Project” or “Lua” (if available)
- Set project location and name
- Click Create
Existing Project:
- File → Open
- Select your project directory
- Click OK

Configure Project SDK

Set up the Lua SDK for your project:

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

Plugin Configuration

Plugin Settings

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

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

Language Server Integration

Configure the EmmyLua Analyzer language server:

Go to Settings → Languages & Frameworks → EmmyLua → Language Server
Select “Use external language server”
Specify the path to emmylua_ls executable:
```
/path/to/emmylua_ls
```
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

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:

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

Keyboard Shortcuts

Essential Shortcuts

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:

Go to File → Settings → Keymap
Search for EmmyLua actions
Right-click → Add Keyboard Shortcut
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:

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

Code Style

Configure Lua code style:

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

File and Code Templates

Create custom templates:

Go to Settings → Editor → File and Code Templates

Add Lua file template:

---@module ${NAME}
---@author ${USER}
---@date ${DATE}

local M = {}

-- Module implementation

return M

Live Templates

Create code snippets for common patterns:

Go to Settings → Editor → Live Templates
Click + → Live Template
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:

Restart IntelliJ IDEA
Verify plugin is enabled:
- Go to Settings → Plugins
- Ensure EmmyLua2 is checked
Check plugin version is compatible with your IDE version
Try reinstalling the plugin
Check IDE logs: Help → Show Log in Explorer

Code completion not working

Solution:

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

Type checking errors are incorrect

Solution:

Add global variables to configuration:

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

Use inline annotations:

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

Configure library paths:

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

Adjust diagnostic severity:

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

Language server not connecting

Solution:

Verify emmylua_ls is installed:
```
emmylua_ls --version
```
Check language server path in settings
Enable language server logging:
- Settings → EmmyLua → Language Server
- Set log level to “debug”
- Check logs in project directory
Restart language server:
- Tools → EmmyLua → Restart Language Server
Try stdio mode instead of TCP

IDE is slow with large Lua project

Solution:

Exclude build directories:
- Right-click folder → Mark Directory as → Excluded
Increase IDE memory:
- Help → Change Memory Settings
- Set to at least 2048 MB

Ignore directories in .emmyrc.json:

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

Disable unused plugins:
- Settings → Plugins
- Disable plugins you don’t use
Power Save Mode:
- File → Power Save Mode (for temporary relief)

Debugging not working

Solution:

Ensure debug configuration is set up:
- Run → Edit Configurations
- Add new Lua configuration
Check Lua interpreter path
Install Lua debugger if needed:
- mobdebug for standard Lua
- LuaJIT debugger for LuaJIT projects
Verify breakpoints are set in reachable code
Check debug console for errors

Multi-Module Projects

For projects with multiple Lua modules:

Configure Module Structure:
- File → Project Structure → Modules
- Add modules for each component
Set Module Dependencies:
- Select module → Dependencies tab
- Add module dependencies
Configure Source Roots:
- Right-click folder → Mark Directory as
- Choose: Sources Root, Test Sources Root, or Excluded

Remote Development

Develop on remote servers:

Enable Remote Development:
- Install “Remote Development” plugin
- Or use IntelliJ IDEA Ultimate’s built-in SSH support
Configure SSH Connection:
- File → Remote Development → SSH
- Add connection details
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

Integration

Advanced Usage

Development

Overview

Installation

Plugin Configuration

Plugin Settings

Language Server Integration

Project-Specific Configuration

Features

Code Completion

Type Checking

Navigation

Refactoring

Code Generation

Debugging

Keyboard Shortcuts

Essential Shortcuts

Custom Keymap

Integration Features

Version Control

External Tools

Code Style

File and Code Templates

Live Templates

Troubleshooting

Multi-Module Projects

Remote Development

Next Steps

Configuration

Annotations

Features

Code Style

Build docs developers (and LLMs) love

Integration

Advanced Usage

Development

​Overview

​Installation

​Plugin Configuration

​Plugin Settings

​Language Server Integration

​Project-Specific Configuration

​Features

​Code Completion

​Type Checking

​Navigation

​Refactoring

​Code Generation

​Debugging

​Keyboard Shortcuts

​Essential Shortcuts

​Custom Keymap

​Integration Features

​Version Control

​External Tools

​Code Style

​File and Code Templates

​Live Templates

​Troubleshooting

​Multi-Module Projects

​Remote Development

​Next Steps

Configuration

Annotations

Features

Code Style

Build docs developers (and LLMs) love

Overview

Installation

Plugin Configuration

Plugin Settings

Language Server Integration

Project-Specific Configuration

Features

Code Completion

Type Checking

Navigation

Refactoring

Code Generation

Debugging

Keyboard Shortcuts

Essential Shortcuts

Custom Keymap

Integration Features

Version Control

External Tools

Code Style

File and Code Templates

Live Templates

Troubleshooting

Multi-Module Projects

Remote Development

Next Steps