VS Code Integration (LSP)

Midwest ships a Language Server (LSP) that provides autocomplete and hover documentation for every component helper directly in your editor.

Features:

• Helper name completion — type midwest_ to see all available helpers
• Option name completion — inside a call, get a list of every declared option with its type and default
• Option value completion — for options with enum values (e.g. position:, size:, state:), values are completed automatically
• Icon name completion — :icon options are completed from the full icon list
• Hover documentation — hover over any midwest_* call to see a table of its options and slots

Prerequisites

• Node.js 18+
• VS Code 1.75+
• A Ruby/ERB extension installed in VS Code (e.g. Ruby LSP or vscode-ruby) so that .html.erb files are recognised with the eruby language ID.

Build the extension

The extension lives in the lsp/ directory of the Midwest gem repo.

cd path/to/midwest/lsp
npm install
npm run compile

This compiles the TypeScript sources to lsp/out/.

Option A — Extension Development Host (recommended for development)

This opens a sandboxed VS Code window with the extension loaded. Changes to the source are picked up after a recompile.

1. Open the lsp/ folder in VS Code:

code path/to/midwest/lsp

1. Press F5 (or Run → Start Debugging → Launch Extension).

A new Extension Development Host window opens.

1. In that window, open your Rails project (or the Midwest gem repo itself).

2. Open any .rb or .html.erb file and start typing midwest_ — completions will appear.

Tip: Run the "watch" build task (⇧⌘B → watch) so the server rebuilds automatically as you edit source files. The extension development host will pick up the new build on the next activation.

Option B — Permanent local install via symlink

This installs the extension into VS Code proper so it loads for every project without needing the development host.

# Build first (see above)
cd path/to/midwest/lsp
npm run compile
# Symlink into the VS Code extensions directory
ln -sf "$(pwd)" ~/.vscode/extensions/unabridged.midwest-lsp

Restart VS Code. The extension will activate automatically whenever you open a Ruby or ERB file.

To uninstall, delete the symlink:

rm ~/.vscode/extensions/unabridged.midwest-lsp

Option C — Install the pre-built VSIX from the repo

Every release includes a pre-built lsp/midwest-language-server.vsix committed directly to the repo. You can install it without a build step:

code --install-extension path/to/midwest/lsp/midwest-language-server.vsix

Or via the VS Code GUI: Extensions → ⋯ → Install from VSIX…

Restart VS Code after installing.

Option D — Build and install your own VSIX

Use this when you want to package a local, in-progress version of the extension.

cd path/to/midwest/lsp
npm install
npm run package           # compiles TypeScript, produces midwest-language-server.vsix

Install it:

code --install-extension midwest-language-server.vsix

Configuration

Open VS Code Settings (⌘,) and search for Midwest LSP.

Example — explicitly point to a vendored gem:

{
  "midwestLsp.gemRoot": "/Users/you/code/midwest"
}

Verifying it works

1. Open a .html.erb file.
2. Type <%= midwest_ — an autocomplete list of all helpers should appear.
3. Select midwest_banner and continue typing ( — option names should appear.
4. Hover over an existing midwest_banner call — a table of options and slots should appear.

If nothing appears, check the Output panel (⇧⌘U) and select Midwest ViewComponent from the dropdown to see server logs.

Debugging the server

The lsp/.vscode/launch.json includes a "Extension + Server" compound launch configuration. This starts the extension and attaches the Node.js debugger to port 6009 so you can set breakpoints in server.ts.