How to install AstroNvim without overriding your existing Neovim configuration
Tags: neovim
Published: 2022-09-24 14:57:24

---
title: How to install AstroNvim without overriding your existing Neovim configuration
published: true
description: Use AstroNvim without deleting your personal Neovim configuration
tags: #neovim
# cover_image: https://direct_url_to_image.jpg
# Use a ratio of 100:42 for best results.
---

I've notice a lot of people out there trying out [AstroNvim](https://github.com/AstroNvim/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](https://dev.to/vonheikemen/build-your-first-neovim-configuration-in-lua-177b) 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.

```bash
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](https://github.com/neovim/neovim/releases/latest) 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.

```vim
: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.

```vim
: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`.

```shell
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](https://gist.github.com/VonHeikemen/1e82e8add1a5b9b2bdc767871af69514).

### Define custom directories

```lua
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.

```lua
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.

```lua
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.

```lua
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

```lua
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`.

```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.

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

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

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

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

```shell
#! /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.

```lua
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](https://www.lua.org/pil/2.5.html). Learn how to create and modify them. It'll make your life so much easier. And don't forget to read [AstroNvim's documentation](https://astronvim.github.io/).

## 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 ☕](https://www.buymeacoffee.com/vonheikemen).

[![buy me a coffee](https://res.cloudinary.com/vonheikemen/image/upload/v1618466522/buy-me-coffee_ah0uzh.png)](https://www.buymeacoffee.com/vonheikemen)