Home

Awesome

nvim-metals logo

nvim-metals

nvim-metals is a Lua plugin built to provide a better experience while using Metals, the Scala Language Server, with Neovim's built-in LSP support.1 You can see all the available features here.

<p align="center"> <a href="https://discord.gg/FaVDrJegEh"> <img alt="link to discord" src="https://img.shields.io/discord/632642981228314653?style=flat-square"> </a> <a href="https://github.com/scalameta/nvim-metals/blob/master/doc/metals.txt"> <img alt="link to help docs" src="https://img.shields.io/badge/docs-%3Ah%20nvim--metals-blue?style=flat-square"> </a> </p>

Prerequisites

Getting started

NOTE: This plugin works without needing to install neovim/nvim-lspconfig. If you have it installed for other languages, that's not a problem, but make sure you do not have Metals configured through nvim-lspconfig while using this plugin.1

Absolute minimal example using Lazy.nvim

{
  "scalameta/nvim-metals",
  dependencies = {
    "nvim-lua/plenary.nvim",
  },
  ft = { "scala", "sbt", "java" },
  opts = function()
    local metals_config = require("metals").bare_config()
    metals_config.on_attach = function(client, bufnr)
      -- your on_attach function
    end

    return metals_config
  end,
  config = function(self, metals_config)
    local nvim_metals_group = vim.api.nvim_create_augroup("nvim-metals", { clear = true })
    vim.api.nvim_create_autocmd("FileType", {
      pattern = self.ft,
      callback = function()
        require("metals").initialize_or_attach(metals_config)
      end,
      group = nvim_metals_group,
    })
  end
}

NOTE: The above assumes you have your own attach function that sets up all your LSP mappings. It also doesn't make use of any configuration. You'll likely want a more involved setup than this, so check out the full minimal example configuration link below.

Settings and Commands

To view all of the available commands, check out :help metals-commands in the help docs. Similarly, to see the available configuration settings check out :help metals-settings.

Integrations

To see the full details on the available configurations, checkout out :help metals-integrations. The currently available integrations are:

Footnotes

  1. If you're familiar with nvim and LSP you'll probably know of nvim-lspconfig which also has a Metals configuration. Note that this is a very minimal version with no specific Metals commands and no Metals extensions. You can see more info on this here. DO NOT try to use Metals both with nvim-lspconfig and with nvim-metals as stuff will not work right. 2

  2. nvim-metals uses Coursier to download and update Metals. NOTE: On Windows, you should run coursier or cs.exe once from the command line as this is how it will install itself. Once this is done you should add C:\Users\YOURNAME\AppData\Coursier\data\bin to your path. To verify that it is properly installed you can run cs --help from a new shell.

  3. By default methods for things like goto definition, find references, etc are there, but not automatically mapped. You can find a minimal example configuration here.

  4. You're more than likely already relying on for other plugins. However, make sure to also have this installed as Metals uses it for things like Jobs, popups, and paths.