Skip to content
Tutorials Center
My learning

Topics

Lesson 34 of 38 ยท Projects and Practice

Project: Build a Minimal, Fast init.el from Scratch

Build a tidy Emacs configuration in stages: sane defaults, interface, packages with use-package, completion, Git, and a checker that lints your init file.

In this project you assemble a complete, small Emacs configuration that you understand line by line. You will use ideas from the whole chapter: init file layout, setq, hooks, key bindings, use-package and completion. At the end, a JavaScript stand-in linter will check an init file for the most common slips (unbalanced parentheses, a setq with a missing value, packages used without being installed).

Everything in the Elisp blocks is real and works in current Emacs (29 or later). The checker is a stand-in that models one part of what M-x check-parens and the byte compiler do.

Step 1: files and layout

Create two files in ~/.emacs.d/ (or ~/.config/emacs/):

Text
early-init.el   ; frame and startup tweaks (runs first)
init.el         ; everything else
custom.el       ; written by Customize (auto-created)

early-init.el:

ELISP
;;; early-init.el --- before the first frame  -*- lexical-binding: t; -*-
(setq gc-cons-threshold (* 64 1024 1024))      ; fewer garbage collections while starting
(setq package-enable-at-startup nil)           ; we call package-initialize ourselves
(push '(menu-bar-lines . 0) default-frame-alist)
(push '(tool-bar-lines . 0) default-frame-alist)
(push '(vertical-scroll-bars) default-frame-alist)

Step 2: sane defaults

ELISP
;;; init.el --- my configuration  -*- lexical-binding: t; -*-

(setq custom-file (expand-file-name "custom.el" user-emacs-directory))
(load custom-file 'noerror 'nomessage)

(setq inhibit-startup-screen t
      ring-bell-function 'ignore
      use-short-answers t                       ; y/n instead of yes/no (Emacs 28+)
      make-backup-files nil
      create-lockfiles nil
      sentence-end-double-space nil
      require-final-newline t
      scroll-conservatively 101
      load-prefer-newer t)

(setq-default indent-tabs-mode nil
              tab-width 4
              fill-column 80)

(delete-selection-mode 1)          ; typing replaces the selection
(electric-pair-mode 1)             ; auto-close brackets
(show-paren-mode 1)
(column-number-mode 1)
(global-auto-revert-mode 1)
(savehist-mode 1)
(recentf-mode 1)
(save-place-mode 1)
(add-hook 'prog-mode-hook #'display-line-numbers-mode)
(add-hook 'before-save-hook #'delete-trailing-whitespace)

Each line comes from a lesson you have seen: modes are switched on with 1, hooks attach behaviour to program buffers, and custom-file keeps Customize out of your way.

Step 3: packages

ELISP
(require 'package)
(add-to-list 'package-archives '("melpa" . "https://melpa.org/packages/") t)
(setq use-package-always-ensure t)             ; install missing packages automatically

(use-package vertico   :init (vertico-mode 1))
(use-package orderless :custom (completion-styles '(orderless basic)))
(use-package marginalia :init (marginalia-mode 1))
(use-package consult
  :bind (("C-x b" . consult-buffer) ("M-s l" . consult-line) ("M-s r" . consult-ripgrep)))
(use-package corfu :custom (corfu-auto t) :init (global-corfu-mode 1))
(use-package magit :bind ("C-x g" . magit-status))
(use-package which-key :init (which-key-mode 1))
(use-package modus-themes
  :config (load-theme 'modus-vivendi t))

(modus-themes is also built in, so the package line may be unnecessary on recent Emacs.) The first start downloads packages and takes a minute; later starts are fast because of deferral and caching.

Step 4: your own commands and keys

ELISP
(defun my/duplicate-line ()
  "Copy the current line below itself."
  (interactive)
  (let ((text (buffer-substring (line-beginning-position) (line-end-position))))
    (end-of-line) (newline) (insert text)))

(global-set-key (kbd "C-c l") #'my/duplicate-line)
(global-set-key (kbd "C-c r") #'recentf-open)
(add-hook 'text-mode-hook #'visual-line-mode)

Step 5: lint it

Before you trust a configuration, check parentheses (M-x check-parens), byte-compile it (M-x byte-compile-file) and read the warnings, and start a clean second Emacs with emacs -Q --load init.el to verify it works from scratch. The stand-in below shows the sort of mechanical checks involved: balanced delimiters (ignoring strings and comments), a setq with an odd number of arguments, and use-package names with no archive coverage.

JS Stand-in: lint an init file

Press Run (or Ctrl + Enter) to see the console output here.

No output.

Step 6: grow it carefully

Add things one at a time and keep each addition in its own commit:

  • a theme and font (set-face-attribute 'default nil :font "Fira Code" :height 120);
  • Eglot and Tree-sitter modes for your languages (programming modes);
  • server mode so every shell can reuse it (the server);
  • remove anything you have not used for a month.

A configuration of 100 to 200 lines that you can explain is worth more than a copied one of 2,000.

Measure startup with M-x emacs-init-time and check which features are loaded with M-x list-features. If startup exceeds about a second, see troubleshooting and performance.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why set custom-file to a separate file?

    Customize appends code to the init file by default; custom-file redirects it.
  2. 2. What does setting use-package-always-ensure to t do?

    It makes use-package install missing packages without writing :ensure t each time.
  3. 3. Which command verifies your parentheses are balanced?

    check-parens moves to the first unbalanced delimiter.
  4. 4. How can you test a configuration from scratch without affecting your real one?

    -Q starts a clean Emacs; loading the file there shows whether it works on its own.

Summary

  • Keep early-init.el tiny, init.el readable, and Customize in custom.el.
  • Start with defaults and built-in modes, then add packages with use-package.
  • The completion stack (Vertico, Orderless, Marginalia, Consult, Corfu) plus Magit and which-key covers most needs.
  • Lint with check-parens, the byte compiler and a clean emacs -Q run.
  • Grow the file slowly, commit often, delete what you do not use.

Next: Project: A Daily Planner from Org-style TODOs