---

name: emacs-modular-config description: Use when adding/modifying Emacs modules, debugging module loading issues, or managing packages with straight.el

Emacs Modular Configuration System

Overview

Modular Loading: Jeff's Emacs uses jf/enabled-modules list and jf/load-module() function for explicit module control with error handling.

Core principle: Define modules in list → loader finds files → loads with error handling → config continues even if module fails

When to Use

Use this skill when:

• Adding new Emacs functionality or modules
• Module fails to load or causes errors
• Need to reload module for testing changes
• Package installation fails or needs debugging
• Understanding module load order matters

Quick Reference

Module System

Key Functions

jf/load-module: Loads module with error handling

• Continues loading even if module fails
• Error details go to *Messages* buffer
• Machine-specific configs auto-loaded from local/{hostname}.el

jf/reload-module: Interactive reload for testing

• Use for iterative development
• No need to restart Emacs

jf/resolve-module-path: Converts module path to file path

• Handles category directories automatically
• Resolves relative to jf/emacs-dir

Adding New Modules

1. Add to jf/enabled-modules in init.org:

Copy(setq jf/enabled-modules
  '("core/completion"
    "major-modes/org-roam"
    "your-new-module"))  ; Add here

1. Create module file following structure (see emacs-literate-programming skill)
2. Test with M-x jf/reload-module before full restart

Module Load Order

• Core modules first
• Order matters for dependencies
• Machine configs loaded last (automatic)
• Error handling allows continuation

Package Management (straight.el)

Configuration

• Package manager: straight.el (not package.el)
• Default behavior: straight-use-package-by-default t
• Storage: ~/.emacs.d/straight/

Quick Reference

Package Template

Copy(use-package package-name
  :straight (package-name :type git :host github :repo "user/repo")
  :bind (("C-c k" . package-function))
  :hook (mode . package-mode)
  :config
  (setq package-setting value))

Debugging

Module Loading Issues

1. Check variable: C-h v jf/machine-name to verify hostname
2. Enable debug: (setq jf/module-debug t) in init.org
3. Check messages: *Messages* buffer shows load errors
4. Verify path: Module file must exist at resolved path
5. Check list: Module must be in jf/enabled-modules

Package Issues

1. Check *Messages* for error details
2. Verify network/repo accessibility
3. Try M-x straight-rebuild-package
4. Delete straight cache if corrupted

Common Mistakes