Flouda Vault

9 min read

Automated Neovim Setup with Custom Configuration

This guide covers the automated Neovim setup utility that streamlines the installation and configuration of a complete Neovim development environment. The script handles dependency installation, builds Neovim from source when necessary, and deploys a custom configuration optimized for modern development workflows.

Overview

The setup-nvim script automates the entire process of installing and configuring Neovim with a custom configuration. It supports both Arch Linux (using pacman) and Ubuntu 24.04 (using apt), handling the unique requirements of each distribution. The script can operate in minimal or full mode, allowing you to choose between a lightweight configuration or a feature-rich development environment.

Key Features

  • Cross-platform support: Works on Arch Linux and Ubuntu 24.04
  • Automatic dependency resolution: Installs all required packages and tools
  • Source compilation: Builds latest stable Neovim from source on Ubuntu for compatibility
  • Configuration backup: Safely backs up existing Neovim configurations
  • Minimal/full modes: Choose between lightweight and full-featured setups
  • Intelligent sudo detection: Adapts to environments with or without sudo access
  • Version checking: Skips unnecessary rebuilds when current version is installed

Quick Start

One-Line Installation

curl -fsSL https://vault.flouda.io/scripts/setup-nvim | bash

Installation with Minimal Mode

curl -fsSL https://vault.flouda.io/scripts/setup-nvim | bash -s -- --minimal

Manual Download and Execution

# Download the script
curl -o setup-nvim https://vault.flouda.io/scripts/setup-nvim
chmod +x setup-nvim
 
# Run interactively (will prompt for minimal mode)
./setup-nvim
 
# Run with minimal mode flag
./setup-nvim --minimal

Installation Modes

Full Mode (Default)

Full mode provides a complete development environment with all features enabled:

  • Latest Node.js: Installs current Node.js version from official repository
  • Complete plugin set: All plugins and language servers enabled
  • Full feature set: Advanced IDE features like debugging, testing, and project management
  • Rich UI: Enhanced visual elements and statusline components

Minimal Mode

Minimal mode creates a lightweight editor focused on essential functionality:

  • System Node.js: Uses distribution-provided Node.js packages
  • Core plugins only: Essential editing plugins without heavy IDE features
  • Reduced resource usage: Lower memory and CPU consumption
  • Faster startup: Optimized for quick editing tasks

System Requirements

Arch Linux

  • Base system: Arch Linux with pacman package manager
  • Network access: For downloading packages and source code
  • Storage space: ~500MB for full installation
  • Privileges: Sudo access recommended (script adapts if unavailable)

Ubuntu 24.04

  • Base system: Ubuntu 24.04 LTS or compatible Debian-based distribution
  • Build tools: Automatically installed (cmake, ninja-build, gcc)
  • Storage space: ~1GB for source compilation and installation
  • Network access: For package updates and source downloads
  • Privileges: Sudo access recommended for system package installation

Dependencies and Package Installation

Arch Linux Dependencies

The script installs these packages via pacman:

neovim npm nodejs go ripgrep fzf git python gcc
  • neovim: Latest stable Neovim from official repositories
  • npm/nodejs: JavaScript runtime and package manager
  • go: Go programming language for certain plugins
  • ripgrep: Fast text search tool used by telescope and other plugins
  • fzf: Fuzzy finder for file and buffer navigation
  • git: Version control system
  • python: Python interpreter for Python-based plugins
  • gcc: Compiler for building native extensions

Ubuntu Dependencies

Base Packages

git python3 python3-venv gcc ninja-build gettext cmake curl build-essential golang ripgrep fzf

Node.js Installation

Full Mode: Installs latest Node.js from NodeSource repository:

curl -sL https://deb.nodesource.com/setup_current.x | sudo bash -
apt install -y nodejs

Minimal Mode: Uses distribution packages:

apt install -y npm nodejs

Neovim Source Compilation

Ubuntu builds Neovim from source to ensure compatibility:

  1. Clone repository: Downloads latest stable branch
  2. Version checking: Compares installed version with latest tag
  3. Build process: Uses CMake with RelWithDebInfo configuration
  4. System installation: Installs to /usr/local/bin/nvim

Configuration Management

Backup Strategy

The script automatically backs up existing Neovim configurations:

~/.config/nvim → ~/.config/nvim.bak
~/.cache/nvim → ~/.cache/nvim.bak
~/.local/share/nvim → ~/.local/share/nvim.bak
~/.local/state/nvim → ~/.local/state/nvim.bak

Configuration Source

The custom configuration is sourced from a GitLab repository and includes:

  • Plugin management: Modern plugin manager with lazy loading
  • Language support: LSP configurations for multiple programming languages
  • Key bindings: Optimized keymaps for efficient editing
  • UI enhancements: Status line, file explorer, and visual improvements
  • Search and navigation: Advanced file and text search capabilities

For comprehensive details about the Neovim configuration itself, including plugin ecosystem, LSP setup, and advanced features, see the complete Neovim configuration guide.

Minimal Mode Configuration

When minimal mode is selected, the script modifies the configuration:

-- Automatically set in ~/.config/nvim/init.lua
vim.g.minimal = true

This setting triggers conditional loading throughout the configuration, disabling heavy plugins and features while maintaining core functionality.

Script Architecture

Error Handling and Validation

The script includes comprehensive error handling:

  • Command validation: Checks return codes for all critical operations
  • Dependency verification: Ensures required tools are available
  • Graceful degradation: Adapts to missing sudo or package managers
  • Build verification: Validates successful compilation before installation

Color-Coded Output

The script provides clear feedback using color-coded messages:

  • Green: Success messages and completed operations
  • Yellow: Warnings and informational messages
  • Red: Error messages and failed operations

Sudo Management

Intelligent sudo handling adapts to different environments:

# Detects sudo availability
check_sudo() {
    if command -v sudo &> /dev/null; then
        use_sudo=true
    else
        use_sudo=false
    fi
}
 
# Executes commands with appropriate privileges
execute_command() {
    local cmd="$1"
    if [[ $use_sudo == true ]]; then
        sudo $cmd
    else
        $cmd
    fi
}

Troubleshooting

Common Issues

Package Installation Failures

If package installation fails, verify:

  • Network connectivity is available
  • Package repositories are accessible
  • Sufficient disk space exists
  • User has appropriate privileges

Build Failures on Ubuntu

For source compilation issues:

  • Ensure all build dependencies are installed
  • Check available disk space (compilation requires ~500MB)
  • Verify git can clone repositories
  • Review build output for specific error messages

Configuration Conflicts

If existing configurations cause issues:

  • Manually remove backed-up directories if restoration is needed
  • Check for conflicting environment variables
  • Verify proper file permissions in home directory

Manual Recovery

To restore previous configuration:

# Remove new configuration
rm -rf ~/.config/nvim
 
# Restore backup
mv ~/.config/nvim.bak ~/.config/nvim

Verification Steps

After installation, verify the setup:

# Check Neovim version
nvim --version
 
# Test configuration loading
nvim --headless -c 'quit'
 
# Verify plugin installation
nvim -c 'checkhealth' -c 'quit'

Advanced Usage

Custom Configuration Modifications

After installation, you can customize the configuration:

  • Plugin management: Edit ~/.config/nvim/lua/plugins/ files
  • Key bindings: Modify ~/.config/nvim/lua/keymaps.lua
  • LSP settings: Adjust ~/.config/nvim/lua/lsp/ configurations
  • UI customization: Edit theme and statusline in respective configuration files

Integration with Development Workflows

The configured Neovim environment integrates well with:

  • Git workflows: Built-in Git integration and merge conflict resolution
  • Project management: Session management and project-specific configurations
  • Debugging: Debug adapter protocol support for multiple languages
  • Testing: Integrated test running and coverage reporting
  • Documentation: Automatic documentation generation and viewing

System Administration Integration

For broader system management beyond the development environment:

  • Package Management: Essential for maintaining the development environment and installing additional language tools
  • Desktop Integration: The Neovim setup works seamlessly with modern desktop environments, particularly when combined with the Hyprland desktop setup

Performance Optimization

For optimal performance:

  • Use minimal mode: On resource-constrained systems
  • Limit concurrent LSP servers: Configure only needed language servers
  • Adjust plugin loading: Use lazy loading for non-essential plugins
  • Monitor resource usage: Use built-in profiling tools to identify bottlenecks

Script Maintenance

Version Updates

The script automatically pulls the latest stable Neovim version and configuration. To update:

# Re-run the script to update Neovim and configuration
curl -fsSL https://vault.flouda.io/scripts/setup-nvim | bash

Configuration Updates

The configuration repository is regularly updated with:

  • New plugin additions and updates
  • Performance improvements
  • Bug fixes and compatibility updates
  • Enhanced language support

Security Considerations

Script Execution Safety

When running scripts from the internet:

  • Review the source: Always examine scripts before execution
  • Use HTTPS: Ensure secure download over encrypted connections
  • Verify checksums: When available, verify script integrity
  • Run in isolation: Consider testing in virtual machines first

Package Installation Security

The script uses official package repositories and:

  • Verifies package signatures: Through system package managers
  • Uses official sources: NodeSource for Node.js, GitHub for Neovim
  • Maintains update paths: Keeps systems updatable through normal channels

References and Resources

Official Documentation

Development Resources

Neovim Ecosystem

Questions Answered in This Document

Q: How do I install Neovim with a custom configuration automatically? A: Use the one-line installation command: curl -fsSL https://vault.flouda.io/scripts/setup-nvim | bash which downloads and runs the setup script that handles dependencies, installation, and configuration.

Q: What’s the difference between minimal and full installation modes? A: Minimal mode installs essential plugins with system Node.js packages for lightweight usage, while full mode installs the latest Node.js and complete plugin set for a full IDE experience.

Q: Does the script work on both Arch Linux and Ubuntu? A: Yes, the script detects your package manager and adapts installation methods accordingly. On Arch Linux it uses pacman, while on Ubuntu it uses apt and compiles Neovim from source for compatibility.

Q: What happens to my existing Neovim configuration? A: The script automatically backs up existing configurations to .bak directories (e.g., ~/.config/nvim.bak) before installing the new configuration.

Q: How do I update Neovim and the configuration to the latest version? A: Re-run the installation script, which will check for updates and install the latest stable Neovim version and configuration updates.

Q: Can I run the script without sudo privileges? A: Yes, the script detects sudo availability and adapts accordingly. However, sudo is recommended for system package installation and optimal functionality.

Q: How much disk space does the installation require? A: Approximately 500MB on Arch Linux and up to 1GB on Ubuntu due to source compilation requirements and build dependencies.

Q: What programming languages are supported in the configured environment? A: The configuration includes LSP support for major languages including JavaScript/TypeScript, Python, Go, Rust, C/C++, and many others through automatic language server installation.

Q: How do I troubleshoot installation failures? A: Check network connectivity, ensure sufficient disk space, verify package repository access, and review the color-coded error messages for specific failure points.

Q: Is it safe to run installation scripts directly from the internet? A: While the script uses official repositories and secure sources, always review scripts before execution and consider testing in isolated environments for additional security.

Graph View

Backlinks