src/content/docs/configuration/v5_migration.mdx
import { Steps } from "@astrojs/starlight/components";
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.
:::
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.
:::
<Steps>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
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
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.
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
Run your new v5 environment simply with nvim 🎉
:::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.
AstroNvim v5 comes with some changes to our default plugin list that user's should keep in mind while performing the migration.
mason-tool-installer.nvim (New Plugin)
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.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, checkout the updated Dashboard Customizations recipes and the snacks.dashboard Documentation for how to implement the same customizations in the new plugin.input field in dressing.nvim, check out the snacks.input Documentation for how to implement the same customizations in the new plugin.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
indent-blankline.nvim, checkout the snacks.indent Documentation for how to implement the same customizations in the new plugin.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:
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, check out the snacks.bufdelete Documentation for the new method names to call.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
nvim-colorizer.lua, check out the nvim-highlight-colors Documentation for how to implement the same customizations in the new plugin.nvim-notify, checkout the snacks.notify Documentation for how to implement the same customizations in the new plugin.nvim-web-devicons → mini.icons
mini.icons Documentation for how to implement the same custom icons in the new plugin.telescope.nvim, checkout the snacks.picker Documentation for how to implement the same customizations in the new plugin.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.telescope.nvim, you can install it from AstroCommunitysystem_open function has been removed and any references to require("astrocore").system_open() should be replaced with vim.ui.open()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.<Leader>ud simply enables/disables diagnostics completely rather than managing various different states.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).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.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.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).Introduction of a new folding module for a custom built foldexpr function in order to replace nvim-ufo.
nvim-ufo in your user configuration.:AstroFoldInfo which displays the current fold information.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:
return {
"AstroNvim/astroui",
---@type AstroUIOpts
opts = {
status = {
providers = {
lsp_client_names = {
mappings = {
-- display `lua_ls` as just `LUA` in the statusline
lua_ls = "LUA",
},
},
},
},
},
}
AstroMasonUpdate and AstroMasonUpdateAll commands have been removed in favor for the commands provided by mason-tool-installer<C-S> for saving while in insert mode has been removed as this is now a core Neovim binding for showing signature help.gI for lsp implementation has been moved to gri to align with new core Neovim default LSP mappingsSome 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
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 featuresnvim-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.[d/]d/[w/]w/[e/]e) support v:count, for example 3]e will navigate 3 errors forward.gco and gcO for inserting new comments below and above the current line<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)gO for document symbols to align with new core Neovim default LSP mappings<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<Leader>go for opening the current buffer's git URL in the browser if it is a git tracked file:AstroRename has been added which renames the current file. This uses a new function in AstroCore, require("astrocore").rename_file()neo-tree.nvim when moving and renaming files as well as the :AstroRename command