How to install AstroNvim without overriding your existing Neovim configuration

I've notice a lot of people out there trying out AstroNvim, and there are a few that want to use it in order to learn about Neovim. I think this is great but... what isn't so great is the installation process taking over your entire Neovim configuration. Wouldn't it be better if you could use AstroNvim for serious work while you slowly create your own Neovim configuration on the side? We can do this. It is possible and I'll tell you how.

The new environment

If you are using Neovim v0.9 or greater, you can setup an environment variable called NVIM_APPNAME. This variable needs a name. Neovim will use this name to look for a different config folder.

If you startup Neovim like this

NVIM_APPNAME=astronvim nvim

Then Neovim will search your config in ~/.config/astronvim if you are on linux or mac. In windows it will look for ~/AppData/Local/astronvim.

Basically the only thing you need to do is create an alias to start Neovim with a different "app name." In linux, using bash or something similar, you would add this in the config file of your shell.

alias code="NVIM_APPNAME=astronvim nvim"

The following is the original content of this article. It will only be useful to you if you are using Neovim v0.8 or lower, and you plan to use AstroNvim v2 or lower.

Requirements

Before you go any further make sure you have the latest stable version of Neovim installed. You can download it from the releases page in github.

Also, you need to know how to enter "ex-commands" inside Neovim, we'll be using a lot of those.

The new path

First thing you want to do is decide where you want to install AstroNvim. In order to make this configuration portable I like to use a folder structure similar to what Neovim uses. This way I can get the paths I need by calling Neovim's builtin functions.

So, open Neovim and execute this command.

:echo stdpath('data')

This will show Neovim's data folder. In linux and mac it'll show something like this.

/home/dev/.local/share/nvim

In windows (I believe) it returns this.

C:\Users\dev\AppData\Local\nvim-data

We don't want that. Replace nvim with astronvim, like this.

:echo substitute(stdpath('data'), '\(.*\)\zsnvim', 'astronvim', '')

That path, that is where we're going to store (almost) everything related to AstroNvim. Create that folder in your file system.

Next, clone AstroNvim inside the folder you just created, and rename the repository folder to core.

git clone https://github.com/AstroNvim/AstroNvim /path/to/astronvim/core

The entrypoint

We can't use AstroNvim's init.lua, we need to make a new one. We have to make sure our personal Neovim configuration doesn't have any conflict with AstroNvim.

This is the part where we create a configuration folder for AstroNvim. Just like before we are going to follow Neovim's pattern. Check where Neovim stores the configuration using :echo stdpath('config'), and then just replace nvim with astronvim.

Inside this config folder you need to create a lua script. You can call it anything you like but for the purpose of this tutorial I will call it entry.lua.

In entry.lua we are going to mess around with a fair amount of variables.

All the code for entry.lua will be in this Github gist.

Define custom directories

local path_sep = vim.loop.os_uname().version:match('Windows') and '\\' or '/'
local join = function(...) return table.concat({...}, path_sep) end
local getpath = function(arg)
  local path = vim.fn.stdpath(arg)
  return vim.fn.substitute(path, [[\(.*\)\zsnvim]], 'astronvim', '')
end

local data_path = getpath('data')
local astro_config = join(data_path, 'core')
local user_path = getpath('config')

In the first line we figure out what path separator we need. The second line we create a join function so we can create paths using the correct separator. In the third line we use our little stdpath + substitute trick in a function, this will return the paths we need in the new AstroNvim setup.

In data_path we will store everything related to AstroNvim we don't want to manage ourselves. astro_config is the place where we downloaded AstroNvim. And user_path is the directory where we configure AstroNvim.

Setup environment

We are going to do is modify environment variables. Yes. We have to. Changes are only going to take effect in Neovim's process, don't worry. Here's how we do it.

vim.env.XDG_DATA_HOME = data_path
vim.env.XDG_CACHE_HOME = join(data_path, 'cache')
vim.env.XDG_STATE_HOME = join(data_path, 'state')

This will make Neovim change the return value of stdpath, after this it'll point to our custom paths.

Runtime files

Now we go for the runtimepath. This is a Neovim option that specifies what directories it should consider when searching for configuration files. We want to take full control of this, tell Neovim exactly what directories it can use.

vim.opt.runtimepath = {
  user_path,
  astro_config,
  vim.env.VIMRUNTIME,
  join(astro_config, 'after'),
  join(user_path, 'after'),
}

Our brand new runtimepath will be AstroNvim's config, AstroNvim itself and Neovim's own runtime files.

Plugin directories

We also need to take care of plugins. For this we modify packpath. With this option we tell Neovim where it can find "packages". A package in Neovim is a folder that contains one or more plugins, see :help packages for more details.

vim.opt.packpath = {
  join(data_path, 'nvim', 'site'),
  user_path,
  vim.env.VIMRUNTIME
}

Here the first path is where the plugin manager will download plugins. The second path is our AstroNvim config (just in case you want to add plugins there). Third is where Neovim's first party plugin are.

AstroNvim home

astronvim_installation = {home = astro_config}

With this we make sure the command AstroUpdate can find the path where we downloaded AstroNvim.

Sourcing

The last step. All we have to do now is execute AstroNvim's init.lua.

local execute = loadfile(join(astro_config, 'init.lua'))

if not execute then
  vim.api.nvim_err_writeln("Could not load AstroNvim's init.lua")
  return
end

execute()

A new command

In order to use the new entrypoint I recommend using Neovim with the -u flag.

nvim -u /path/to/astronvim/entry.lua

Assuming you are using bash or zsh as your shell, you can create an alias.

alias code='nvim -u /path/to/astronvim/entry.lua'

Or make a new executable script and add it to your PATH.

#! /usr/bin/env sh

nvim -u /path/to/astronvim/entry.lua "$@"

Either way you should be able to call AstroNvim with this new command, and also call Neovim with just nvim.

How do we customize AstroNvim?

In the same folder where we have entry.lua you create a directory called lua, and inside lua create another folder called user. And then inside user you create a file called init.lua

Inside /path/to/astronvim/lua/user/init.lua you need to create a lua table, add your config and then return that table. Like this.

local user = {plugins = {}}

user.colorscheme = 'tokyonight-night'

user.plugins.init = {
  {'folke/tokyonight.nvim'}
}

return user

Here I add a new plugin (a colorscheme) and set a new colorscheme.

I highly recommend that you get familiar with the syntax of lua tables. Learn how to create and modify them. It'll make your life so much easier. And don't forget to read AstroNvim's documentation.

Conclusion

This is it. You made it. Now you have the tools to use AstroNvim and also keep your own configuration for Neovim.

Thank you for your time. If you find this article useful and want to support my efforts, consider leaving a tip in buy me a coffee ☕.