Skip to main content

Getting Started

zflash is a fast, staged plugin manager for zsh. You describe everything your shell loads in one short file, the spec, and zflash compiles it into a single byte-compiled init file. At shell start nothing is resolved, searched, forked or parsed by the manager: your .zshrc sources a tiny bootstrap and that one file.

Everything in the spec (plugins, <tool> init zsh output, your own rc files) is split into two stages, before and after the first prompt, so the prompt appears as early as possible.

:::info Version These docs describe zflash 0.2.0. Run zflash version to see which version you have. See Upgrading zflash to get the latest. :::

Requirements​

  • zsh (developed and benchmarked on zsh 5.9)
  • git, used to clone and update plugins
  • curl, only for the one-line installer

zflash runs on macOS and Linux.

Quick start​

1. Install zflash and wire it into your ~/.zshrc:

zsh -c "$(curl -fsSL https://raw.githubusercontent.com/arastu/zflash/main/install.sh)" zflash-install --zshrc

This clones zflash into ~/.local/share/zflash/zflash, creates a starter spec at ~/.config/zflash/plugins.zsh, and adds two lines to the end of ~/.zshrc.

2. Open a new terminal. The first shell clones the plugins listed in the starter spec and builds the init file. Every shell after that starts from the compiled file.

3. Check what was loaded:

zflash list
fpath  zsh-users/zsh-completions/src
sync   ohmyzsh/ohmyzsh/lib/history.zsh
defer  ohmyzsh/ohmyzsh/lib/clipboard.zsh
...
defer  zsh-users/zsh-autosuggestions/zsh-autosuggestions.plugin.zsh

4. Make it yours. Open ~/.config/zflash/plugins.zsh, add or remove lines, and open a new shell. zflash notices the spec changed and rebuilds automatically.

~/.config/zflash/plugins.zsh
zflash defer ohmyzsh/ohmyzsh plugins/git plugins/docker
zflash defer zsh-users/zsh-autosuggestions

Why zflash?​

Typical managerzflash
Work at startupLoad the manager, resolve plugins, maybe check for updatesSource one compiled file
Completion initOften a full compinit every startCached compinit -C after the first prompt; earlier compdef calls are queued
Deferred loadingAdd a plugin and wire it up yourselfzflash defer, built in
Completion dirsMust be declared before compinit by handHoisted automatically from every line
starship init zsh, zoxide init zsh, fzf --zshForked on every startRun once at build time, output inlined (zflash eval)
Your aliases, functions, exportsParsed on every startListed in the spec: byte-compiled, staged like plugins
UpdatesAt startup, in the foregroundIn the background, after the prompt

Next steps​