CosmicNvim is an opinionated Neovim config that picks your linter for you

A distribution config rather than a set of instructions

CosmicNvim describes itself as a lightweight and opinionated Neovim config for web development, designed to provide a cosmic programming experience. The two words that matter are lightweight and opinionated.

Opinionated means the configuration makes decisions for you. The plugin list is long and specific: cosmic-ui for the rename and code action popups, tokyonight.nvim for the default theme, snacks.nvim and noice.nvim for interface enhancements, nvim-treesitter for syntax highlighting, lualine for the statusline, oil.nvim as the file editor, toggleterm.nvim for a floating terminal, mason.nvim for LSP server management, blink.cmp for autocompletion, LuaSnip for snippets, auto-session for session management and which-key.nvim for finding keybindings. Floating windows are provided for references, renaming, diagnostics and code actions.

Lightweight is the more interesting claim, because the set above is not small. What keeps it light is that the configuration is Lua source rather than a pile of Vimscript, and that the file layout is conventional: init.lua at the root, a lua/ directory for the plugin configuration, an after/ directory for runtime files, a lazy-lock.json lockfile, and a tests/ directory.

The target audience is explicit. CosmicNvim is geared specifically toward TypeScript and JavaScript development, though the README notes it should still provide a good experience with any LSP supported language. It is written in Lua, and the licence is GPL-3.0, which is a heavier obligation than the MIT licence most dotfiles use and is worth reading before you fork it into a work repository.

Neovim nightly and a list of binaries you must supply

The prerequisites are the part that decides whether this config will work on your machine, and they are not minimal.

Neovim 0.13.0 or later, specifically the nightly, is the base requirement, plus Git to clone the config and install plugins, and Node.js with npm for the JavaScript and TypeScript tooling. External formatters for the languages you use are also listed as a prerequisite rather than an optional extra.

Beyond that there is a second tier, and the README is careful to say these support specific features rather than core startup. The Tree-sitter CLI and a C compiler, either cc, gcc or clang, are needed for parser installation and syntax highlighting. make and a C compiler are needed for LuaSnip's regex transformations. ripgrep, as rg, is needed for picker text searches. fd 8.4 or later, as fd or fdfind, is needed for file explorer searches and it also speeds up the file pickers. curl and tar are needed for parser and package downloads and extraction. A Nerd Font in the terminal is needed for the icons to display correctly.

The way this is verified is the detail that makes the setup tractable. There is a health check command, and the README says it checks the external tools after installation:

:checkhealth cosmic

So rather than discovering a missing ripgrep when a picker comes up empty, you can run one command after setup and see which external dependencies are actually present on the machine.

The install script moves your old config out of the way

The install procedure is a single shell block, and it is careful with what is already on disk. It creates and enters Neovim's config parent directory, and if an nvim directory or symlink already exists it moves it into a fresh backup directory created with mktemp rather than overwriting it:

mkdir -p "${XDG_CONFIG_HOME:-$HOME/.config}" && cd "${XDG_CONFIG_HOME:-$HOME/.config}" || exit 1
if [ -e nvim ] || [ -L nvim ]; then
  backup_dir=$(mktemp -d "$PWD/nvim.backup.XXXXXX") || exit 1
  mv nvim "$backup_dir/nvim" || exit 1
  printf 'Previous config saved to %s/nvim\n' "$backup_dir"
fi
git clone https://github.com/CosmicNvim/CosmicNvim.git nvim && nvim

The clone is followed by nvim, which is how the plugins get installed on first launch.

By default Cosmic uses the Git checkout at vim.fn.stdpath('config'), which is usually ~/.config/nvim, and a whole-directory symlink from that location to your own checkout works with no extra configuration. If you link individual files or keep the checkout somewhere else, you set the shell environment variable COSMICNVIM_INSTALL_DIR to the checkout path, so Cosmic can find its lockfile and update the correct repository rather than a directory it does not own.

One more detail for people who install file by file: the after/ directory has to be included along with init.lua and lua/, because the built-in LSP settings are delivered through the runtimepath. After the plugins finish installing, the health check from the previous section is the natural next command.

Linters and formatters are chosen from what the project already uses

This is the most distinctive part of the configuration, and it is a policy engine rather than a setting.

Conform formats on save, and the tools are configured in lua/cosmic/plugins/conform/init.lua. The README is explicit that you install the tools for your filetypes and that Neovim has to find their executables on PATH. It also warns that Mason's LSP installation does not install every configured formatter, and that some servers, such as oxlint and Ruff, share their executable with Conform's tools and may already provide it.

For JavaScript and TypeScript, lint fixes run before formatting, and the selection table is driven by what the project has. With oxlint present and no ESLint configured, the fixes come from oxlint and the diagnostics from the oxlint server. With both oxlint and ESLint configured, the fixes are oxlint then eslint_d, and both servers report diagnostics. With only ESLint configured, eslint_d does the fixing and the ESLint server reports. With neither, the default is oxlint with the oxlint server.

The formatter selection for JS/TS, CSS, SCSS, HTML, JSON and Markdown takes the first matching rule: oxfmt if oxfmt is present, otherwise prettierd if Prettier is present, with plain prettier also enabled when prettierd is missing from PATH, otherwise no separate web formatter when ESLint is configured, and oxfmt when none of the above apply. CSS, SCSS, HTML, JSON and Markdown use the same formatter selection but do not run the JS/TS lint fix commands.

Detection works by searching the file's directory and its ancestors for supported config files such as .prettierrc or eslint.config.js, and by looking at package.json settings for eslintConfig or prettier. An oxlint, oxfmt or Prettier dependency in dependencies or devDependencies also counts, while an ESLint dependency alone does not. Conform prefers project-local binaries where the tool's formatter definition supports it, and the Prettier fallback check only looks at PATH, so a project-local-only prettier is not detected there.

A Lua configuration is a program you can read

The repository layout says what kind of artefact this is. There is init.lua at the root, a lua/ directory for the configuration, an after/ directory for runtime files, lazy-lock.json as the plugin lockfile, a tests/ directory, a docs/ directory, and tool configuration files including .stylua.toml for Lua formatting and .markdownlint.yaml for the documentation. AGENTS.md is also present, which usually means the repository is set up for automated agents working on it.

Two things follow from the Lua choice. First, the configuration is ordinary code, so it can be refactored, and a plugin setting is a function call rather than a line of Vimscript that you have to look up. The path of a single setting, lua/cosmic/plugins/conform/init.lua for the formatter configuration, is exactly what you would expect from a source tree rather than a single dotfile.

Second, a config that ships tests is telling you it is meant to be modified. The distinction between upstream and your own version is handled by the install path rather than by a fork: keep your own checkout, point Cosmic at it with COSMICNVIM_INSTALL_DIR, and change the Lua files. The lockfile is the boundary, since it is what lets Cosmic know which plugin versions are in use and which repository to update.

For a user migrating from an existing setup, the practical sequence is the one the documentation implies. Clone into a clean directory, let the plugins install on first launch, run the health check, then adjust the Lua configuration in your own checkout. The alternative, maintaining a fork, is possible but the GPL-3.0 licence means your modifications to the config, as distinct from your own plugins, carry an obligation if you distribute them.

A young release line with a recently renamed scope

CosmicNvim is a young project by release numbering. The published releases are 1.1.0 on 2026-10-10, and 1.0.1 and 1.0.0 both on 2026-02-23, which suggests the project was reorganised or renamed at the start of 2026 and reached 1.1 in the autumn.

The repository is not archived and the last push was on 2026-10-12, two days after the 1.1.0 tag, so the branch and the release are close together. That is the healthy pattern for a configuration, where a plugin breaking change in Neovim nightly can affect the whole setup overnight, and where the lockfile is the mechanism that keeps a user pinned to a working combination.

The upgrade cost for a user is therefore mostly a matter of reviewing the diff of a configuration you have customised, and of expecting the occasional change in default behaviour when the project updates its opinionated choices. The README's own historical screenshot, labelled December 2021 with a note that the current user interface and plugin defaults differ, is a good illustration of how much a config of this kind moves over time.

The GPL-3.0 licence is the other thing to settle before adopting. It is not unusual for a Neovim configuration, and it does not affect personal use, but a team that keeps its dotfiles in a proprietary work repository is making a judgement call that the licence file will not answer for them.

Editorial conclusion

CosmicNvim suits a web developer who wants a working Neovim environment with LSP, formatting, file management and session restore in one afternoon, and who is prepared to work inside a configuration that makes choices for them. It does not suit someone who wants a minimal setup, who cannot install Neovim nightly and the extra binaries, or who needs a workflow the config does not model. Verify first that your projects' linting and formatting tooling is the kind the detection understands, because the rules turn on the presence of oxlint, oxfmt, ESLint and Prettier in a project's dependencies or config files, and read the linter and formatter tables before you enable a project.

Frequently asked questions

Official sources

1. CosmicNvim/CosmicNvim on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases