Migration to v5.0

While AstroNvim v4 came with a large restructuring of the configuration organization, AstroNvim v5 is a much smaller major version release and mainly comes with some modernization of plugins and small quality of life improvements. The most notable change in AstroNvim v5 is that support for Neovim <0.10 has been dropped and users must be running either Neovim stable releases of v0.10 or v0.11. Most of the migration will only apply to users who have gone and customized the plugins that have been replaced. The plugin replacements come from various reasons such as plugins getting archived (dressing.nvim), better performance, more stable development practices, and overall simplification.

Note

Before getting started it is recommended to review the Getting Started guide. The guide explains how AstroNvim uses lazy.nvim and it also explains the AstroNvim configuration template, which is the recommended way to migrate from the previous version.

Setting Up a Migration Environment

Breaking your working editor configuration when migrating to v5 will make it difficult to edit your new configuration. As such, we recommend following the process below so that your existing editor keeps working while you upgrade to the new v5 configuration. This workflow makes use of an Isolated Installation environment.

Tip

Checkout the Managing User Configuration Page for details on how to create a new git repository from our template or convert the clone described above into a repository. It is highly recommended to set up your configuration as a git repository so that it is backed up as well as easier to share.

Tip

Rather than cloning the template into ~/.config/astronvim_v5, you can also clone your personal configuration into that location and change the AstroNvim version in the lazy_setup.lua file to "^5" and do the migration with your current configuration while using your old installation as the main editor while testing.

1. Clone the AstroNvim v5 configuration template to a new location (astronvim_v5 is used as the example):

   git clone https://github.com/AstroNvim/template ~/.config/astronvim_v5
   rm -rf ~/.config/astronvim_v5/.git

2. Start nvim in the new environment. nvim should start, bootstrap itself by installing and loading lazy.nvim. Lazy will load all of the plugins specified by AstroNvim.

   NVIM_APPNAME=astronvim_v5 nvim

3. Migrate your AstroNvim v4 configuration to your new AstroNvim v5 environment at ~/.config/astronvim_v5 using the guide below. You can use your previous AstroNvim setup to do the editing and then continue running the command in Step 2 to test the new installation.

4. Once you have your configuration set up how you like it, move it over to the default neovim configuration location ~/.config/nvim:

   # Backup old Neovim folders
   mv ~/.local/share/nvim ~/.local/share/nvim.bak # backup old data folder
   mv ~/.local/state/nvim ~/.local/state/nvim.bak # backup old state folder
   mv ~/.cache/nvim ~/.cache/nvim.bak             # backup old cache folder
   mv ~/.config/nvim ~/.config/nvim.bak           # backup old config
   # Move new configuration into place
   mv ~/.config/astronvim_v5 ~/.config/nvim # move new config

5. Run your new v5 environment simply with nvim 🎉

Migration Guide

Configuration Option Changes

Caution

This is a work in progress. This guide is taking shape and covers much of the migration. There are holes though! If you see something missing drop a note on the Discord #next channel or open a pull request on GitHub.

Each “Migrating” section below has an link to documentation and/or an example configuration. Each example configuration file shows the structure for configuring that plugin. The comments in each example configuration describes the configuration keys.

The plugin configuration files. in the AstroNvim codebase itself are also a good reference to learn how to configure.

Please also read the Other Breaking Changes section - there are a number of changes that are not just “move some config from one place to another”. For example, in key mapping <leader> is no longer recognized.

If you get stuck, people on the Discord forum are active and friendly! Like all humans, sometimes they are grumpy, so be nice to them! The best place to post is most likely the #help-forum, but poke around a few of the other channels, you never know what you will find that is useful.

Plugin Changes

AstroNvim v5 comes with some changes to our default plugin list that user’s should keep in mind while performing the migration.

Overview

Old Plugin	New Plugin
N/A	mason-tool-installer.nvim
alpha-nvim	snacks.nvim
dressing.nvim	snacks.nvim
indent-blankline.nvim	snacks.nvim
lspkind.nvim	mini.icons
mini.bufremove	snacks.nvim
nvim-cmp	blink.cmp
nvim-colorizer.lua	nvim-highlight-colors
nvim-notify	snacks.nvim
nvim-web-devicons	mini.icons
telescope.nvim	snacks.nvim

Details

• mason-tool-installer.nvim (New Plugin)

  • AstroNvim is now relying on mason-tool-installer.nvim rather than mason-lspconfig/mason-nvim-dap/mason-null-ls. This makes configuration of installed packages easier rather than managing several ensure_installed tables and also adds support for installing packages automatically that are not part of any of those usecase specific plugins. mason-tool-installer.nvim also allows the user to specify specific package versions and other options. Check out the mason-tool-installer.nvim Documentation for details on it’s configuration.
  • For migration, anywhere in your configuration where you are configuring ensure_installed for mason-lspconfig/mason-nvim-dap/mason-null-ls, you should move those to an ensure_installed table in mason-tool-installer.nvim. You must also change the name of the package where necessary to properly reflect the name of the package in Mason. For instance, if you have lua_ls specified for mason-lspconfig, this would be lua-language-server in mason-tool-installer.nvim.

• alpha-nvim → snacks.nvim

  • If you are customizing alpha-nvim, checkout the updated Dashboard Customizations recipes and the snacks.dashboard Documentation for how to implement the same customizations in the new plugin.

• dressing.nvim → snacks.nvim

  • If you are customizing the input field in dressing.nvim, check out the snacks.input Documentation for how to implement the same customizations in the new plugin.
  • If you are customizing the select field in dressing.nvim, checkout the snacks.picker Documentation for how to implement the same customizations in the new plugin.

• indent-blankline.nvim → snacks.nvim

  • If you are customizing indent-blankline.nvim, checkout the snacks.indent Documentation for how to implement the same customizations in the new plugin.

• lspkind.nvim → mini.icons

  • If you are customizing lsp kind icons, check out the mini.icons Documentation for how to implement the same custom icons in the new plugin.

  • If you have customized the mode option in lspkind.nvim to change the look of the LSP icons, this can be done easily by customizing the completion.menu.draw.columns option in blink.cmp:

    lua/plugins/blink_menu.lua

    return {
      "Saghen/blink.cmp",
      opts = {
        completion = {
          menu = {
            draw = {
              columns = {
                -- rearrange these as necessary to match desired look
                { "label", "label_description", gap = 1 },
                { "kind_icon", "kind", gap = 1 },
              },
            },
          },
        },
      },
    }

• mini.bufremove → snacks.nvim

  • If you are using any of the API provided by mini.bufremove, check out the snacks.bufdelete Documentation for the new method names to call.

• nvim-cmp → blink.cmp

  • If you are customizing nvim-cmp, checkout the updated Cmp Customizations recipes and the blink.cmp Documentation for how to implement the same customizations in the new plugin.

• nvim-colorizer.lua → nvim-highlight-colors

  • If you are customizing nvim-colorizer.lua, check out the nvim-highlight-colors Documentation for how to implement the same customizations in the new plugin.

• nvim-notify → snacks.nvim

  • If you are customizing nvim-notify, checkout the snacks.notify Documentation for how to implement the same customizations in the new plugin.

• nvim-web-devicons → mini.icons

  • If you are customizing icons, check out the mini.icons Documentation for how to implement the same custom icons in the new plugin.

• telescope.nvim → snacks.nvim

  • If you are customizing telescope.nvim, checkout the snacks.picker Documentation for how to implement the same customizations in the new plugin.
  • Some plugins have strong telescope.nvim integration, if you have plugins such as this, look to see if they have support for snacks.picker or just the native vim.ui.select function which will use snacks.picker.
  • If you want to revert back to using telescope.nvim, you can install it from AstroCommunity

AstroNvim Core Plugin Changes

AstroCore

• The system_open function has been removed and any references to require("astrocore").system_open() should be replaced with vim.ui.open()
• The features.diagnostics_mode configuration option has been simplified to just be features.diagnostics. This new value is either a boolean (true/false) to enable/disable diagnostics completely on startup, or it can be a table in the form of { virtual_text = true, virtual_lines = false } to control the display of virtual text/virtual lines on startup. New toggles have been added (<Leader>uv and <Leader>uV) to toggle the virtual text and virtual lines at runtime.
• The mapping <Leader>ud simply enables/disables diagnostics completely rather than managing various different states.
• The mappings configuration table now does some basic normalization which means specific casing of the keys should not matter as much. It is still recommended to use the official keycode casing to maintain the most stable behavior (keycode casing can be found in :h keycodes).
• The mason module has been removed. If you are using require("astrocore.mason") anywhere, investigate the APIs available from mason.nvim and mason-tool-installer.nvim for alternatives.

AstroLSP

• Configuration of vim.lsp.buf.hover and vim.lsp.buf.signature_help are no longer configured through the handlers["textDocument/hover"] and handlers["textDocument/signature_help"] configuration options. This is because of a breaking change in core Neovim where these are no longer configured as such. The options are now configured through a new defaults table in the AstroLSP configuration (defaults.hover and defaults.signature_help). If you have customized those handlers in your configuration, then check the AstroLSP Documentation for where to place those configurations.
• The mappings configuration table now does some basic normalization which means specific casing of the keys should not matter as much. It is still recommended to use the official keycode casing to maintain the most stable behavior (keycode casing can be found in :h keycodes).

AstroUI

• Introduction of a new folding module for a custom built foldexpr function in order to replace nvim-ufo.

  • This feature is currently only enabled by default if you are using Neovim v0.11 as this provides LSP based folding out of the box, but if you want to use it with Neovim v0.10 then you can simply disable nvim-ufo in your user configuration.
  • When in use, it also exposes a new command, :AstroFoldInfo which displays the current fold information.
  • The folding behavior can also be configured through the new folding configuration table which can be explored through the AstroUI Documentation which allows the user to configure when folding is enabled as well as which folding methods are utilized (currently supports treesitter based folding, indentation based folding, and LSP based folding which is Neovim v0.11 only).

• AstroUI status providers and component defaults options can now be configured in the opts table through status.providers and status.components.

  • All of these options have strong typing and autocompletion as long as the type is set with Lua annotations in the code (an example of this is shown in the code example below).

  • This is primarily useful for customizing default options for the providers such as setting up custom LSP client name mappings or alignment/padding of some elements without having to fully modify the statusline in heirline.nvim. For example, if you want to set up custom LSP client names to be displayed, you can do the following:

    lua/plugins/astroui_lsp_client_names.lua

    return {
      "AstroNvim/astroui",
      ---@type AstroUIOpts
      opts = {
        status = {
          providers = {
            lsp_client_names = {
              mappings = {
                -- display `lua_ls` as just `LUA` in the statusline
                lua_ls = "LUA",
              },
            },
          },
        },
      },
    }

Other Breaking Changes

• Drop support for Neovim v0.9
• AstroMasonUpdate and AstroMasonUpdateAll commands have been removed in favor for the commands provided by mason-tool-installer
• The mapping <C-S> for saving while in insert mode has been removed as this is now a core Neovim binding for showing signature help.
• The mapping gI for lsp implementation has been moved to gri to align with new core Neovim default LSP mappings

New Features

Some changes have been made that do not necessarily require any user intervention during the migration, but are just new features! Here are a few highlights

• Neovim v0.11 adds a ton of great new features such as vim.lsp.foldexpr and context based comment strings. When using Neovim v0.11 we disable a few plugins and just rely on core features
  • Comment.nvim and nvim-ts-context-commentstring are disabled in Neovim v0.11 in favor of the built in commenting features
  • nvim-ufo is disabled in Neovim v0.11 in favor of the new AstroUI based fold expression. This provides a much clearer implementation of folding rather than relying on the “manual” fold method which can lead to some strange behavior.
• With Neovim v0.11 diagnostic navigation bindings ([d/]d/[w/]w/[e/]e) support v:count, for example 3]e will navigate 3 errors forward.
• New mappings gco and gcO for inserting new comments below and above the current line
• New mappings <Leader>uv and <Leader>uV for toggling diagnostic virtual text and virtual lines (virtual lines are only available in Neovim v0.11 and can replace plugins such as lsp_lines.nvim)
• New mapping gO for document symbols to align with new core Neovim default LSP mappings
• New mapping <Leader>uZ for toggling “Zen mode” for the current buffer which maximizes the buffer, centers the code, and disables most of the “eye candy” such as diagnostics
• New mapping <Leader>go for opening the current buffer’s git URL in the browser if it is a git tracked file
• A new command, :AstroRename has been added which renames the current file. This uses a new function in AstroCore, require("astrocore").rename_file()
• AstroLSP has a full implementation for LSP based file operations which can help with things such as updating import statements when renaming files. These features are now enabled by default and have integration with neo-tree.nvim when moving and renaming files as well as the :AstroRename command