Declarative, Reproducible Emacs with straight.el and use-package

Jacob Boxerman's exploration of declarative, reproducible Emacs configurations represents a thoughtful approach to managing the complexity that often plagues Emacs setups. His journey this summer led him to develop a configuration philosophy that prioritizes reproducibility and declarative principles, ensuring that Emacs environments can be reliably recreated across machines while maintaining clear, understandable configuration code.

The core of Boxerman's approach rests on two fundamental concepts: reproducibility and declarativeness. Reproducibility ensures that an exact Emacs environment—including packages, versions, color schemes, and keybindings—can be recreated on any machine. This addresses the common frustration of subtle bugs or behavioral changes that emerge between package releases. Declarativeness, which Boxerman emphasizes goes hand-in-hand with reproducibility, means configuring Emacs behavior in a well-defined manner that minimizes ambiguity and missing definitions.

At the heart of this setup are two essential packages: straight.el and use-package. straight.el serves as a package manager with two key advantages. First, it downloads packages from their source repositories and stores them locally, enabling easy modification of the underlying Elisp code. Second, it supports version pinning through lockfiles that track specific commit hashes, ensuring consistent package versions across installations unless explicitly updated.

The setup process for straight.el involves visiting its GitHub repository, copying the bootstrap code, and following additional configuration steps. Boxerman recommends organizing packages into profiles—he uses separate profiles for base packages and programming-related packages, each with its own lockfile. This organization allows for minimal configurations on machines used primarily for non-development tasks while maintaining full development environments elsewhere.

use-package provides the declarative configuration framework that complements straight.el's package management. It offers a macro that handles package loading and configuration in a clean, modular fashion. The package's documentation is comprehensive, but Boxerman highlights several key keywords that form the foundation of effective use-package usage: :init, :config, :custom, and :hook.

The :init keyword runs code before a package loads, but Boxerman advises using it sparingly since pre-loading configuration often proves unnecessary. The :custom and :config keywords serve similar purposes—:custom sets custom variables while :config runs arbitrary Elisp after package loading. Boxerman recommends preferring :custom over :config when possible, as custom settings can have side effects that should be respected. The :hook keyword provides a clean interface for adding hooks, with after-init being particularly useful for activating modes after initialization completes.

Boxerman demonstrates these principles through practical examples, such as configuring recentf-mode to activate after initialization while setting custom variables for maximum saved items. This approach exemplifies the clean, readable style that declarative configuration enables.

The organizational philosophy extends throughout the entire configuration. Boxerman structures his setup so that nearly everything resides within use-package blocks, with minimal dependencies between blocks and no reliance on loading order. The only critical requirement is placing the straight.el bootstrap code at the top of the configuration file. Keybinding configuration, managed through general.el, stays alongside relevant packages rather than in a centralized section, maintaining the modular structure.

This approach draws inspiration from Nix and functional programming principles, though Boxerman notes that many Emacs users have been pursuing similar goals for years without explicitly recognizing them. The declarative configuration model ensures that the entire Emacs setup can be understood and reproduced from a single file, eliminating the ambiguity and hidden dependencies that often plague complex configurations.

The companion video provides a practical tour of Boxerman's configuration, demonstrating how these principles translate into actual code organization and package management. The visual demonstration helps illustrate the modular structure and shows how use-package blocks encapsulate all configuration related to specific packages, including settings, keybindings, and initialization code.

Boxerman's methodology addresses several common pain points in Emacs configuration management. The reproducibility aspect eliminates the "it works on my machine" problem that frustrates many users when setting up Emacs on new systems. The declarative approach makes configurations more maintainable and understandable, particularly valuable when revisiting configurations after extended periods or collaborating with other users.

The separation of concerns through profiles and modular use-package blocks creates a flexible system that can adapt to different use cases without sacrificing consistency. Whether setting up a minimal configuration for basic text editing or a comprehensive development environment, the same principles and tools apply, with differences managed through profile selection and package inclusion.

This configuration philosophy represents a mature approach to Emacs management that balances power and flexibility with reproducibility and clarity. By leveraging straight.el's version control capabilities and use-package's declarative syntax, users can build configurations that are both sophisticated and maintainable, avoiding the configuration drift and dependency issues that often plague long-term Emacs usage.

The principles Boxerman outlines extend beyond Emacs to broader software configuration management. The emphasis on reproducibility, declarative definitions, and modular organization reflects best practices in modern software development, making this approach valuable not just for Emacs users but for anyone interested in effective configuration management strategies.

For users looking to implement similar approaches, the path forward involves studying the documentation for both straight.el and use-package, experimenting with profile organization, and gradually refactoring existing configurations to embrace declarative principles. The initial investment in restructuring pays dividends through improved reliability, easier maintenance, and greater confidence in configuration reproducibility across different environments.

Boxerman's work provides both a practical guide and a philosophical framework for thinking about Emacs configuration. By naming and articulating principles that many users have discovered intuitively, he offers a roadmap for others to follow and adapt, potentially raising the overall quality and reliability of Emacs configurations across the community.