prelude-install

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Install & configure Prelude

安装与配置Prelude

Prelude is a devshell UI suite — a flake-parts module, or

prelude.lib.evalModule

for any other flake: a

nix develop

welcome banner (MOTD), an interactive command picker (

), a Markdown docs viewer, and a themed Starship prompt. Everything runs from the published flake — no checkout of the Prelude repo is needed. Print docs without cloning:

nix run github:darkmatter/prelude#skill -- install   # full consumer walkthrough
nix run github:darkmatter/prelude#skill -- options    # generated prelude.* reference

Prelude是一套devshell UI套件——可作为flake-parts模块使用，也可通过

prelude.lib.evalModule

适配其他任意flake：包含

nix develop

欢迎横幅（MOTD）、交互式命令选择器（

）、Markdown文档查看器，以及带主题的Starship提示符。所有功能都基于发布的flake运行——无需检出Prelude仓库。无需克隆即可查看文档：

nix run github:darkmatter/prelude#skill -- install   # full consumer walkthrough
nix run github:darkmatter/prelude#skill -- options    # generated prelude.* reference

0. Inspect what already exists

0. 检查现有内容

Before changing anything, look at the repo:

```
flake.nix
```
— flake-parts (
```
flake-parts.lib.mkFlake
```
) takes the module; anything else (blueprint, a plain
```
outputs
```
function) uses
```
prelude.lib.evalModule
```
, with no restructuring. Note existing
```
inputs
```
,
```
imports
```
, and
```
devShells
```
to preserve them.
```
prelude.nix
```
/
```
title.txt
```
— inspect any existing sidecar before deciding setup is needed. Edit existing configuration in place; wizard reruns overwrite both files.
```
.envrc
```
— preserve its existing loader; add
```
use flake
```
only when adopting nix-direnv, not alongside another environment-loading strategy.
Existing README and
```
docs/
```
— kept untouched by setup.

在做任何修改之前，先查看仓库现状：

```
flake.nix
```
— 若使用flake-parts（
```
flake-parts.lib.mkFlake
```
）则直接引入模块；其他情况（如blueprint、普通
```
outputs
```
函数）使用
```
prelude.lib.evalModule
```
，无需重构现有结构。注意保留已有的
```
inputs
```
、
```
imports
```
和
```
devShells
```
配置。
```
prelude.nix
```
/
```
title.txt
```
— 在确定需要安装前，先检查是否已有sidecar文件。可直接编辑现有配置；重新运行向导会覆盖这两个文件。
```
.envrc
```
— 保留其现有的加载器；仅在采用nix-direnv时添加
```
use flake
```
，不要与其他环境加载策略并用。
现有README和
```
docs/
```
目录 — 安装过程不会改动这些内容。

1. Run the wizard (new installs)

1. 运行向导（全新安装）

nix run github:darkmatter/prelude -- wizard

Steps: title text + FIGlet font, project name, commands, component toggles (

motd

menu

prompt

docs

.envrc

), MOTD copy and layout, theme, confirm. Run from the project root; it needs an interactive terminal. It writes:

```
prelude.nix
```
— full options template: your choices active, every other option present as a commented default (the file doubles as inline docs).
```
title.txt
```
— the rendered wordmark, written beside the config and referenced by bare name, so it resolves from any
```
-o
```
directory.
```
.envrc
```
(content exactly
```
use flake
```
) — only if toggled on and none exists.
With docs enabled: starter
```
README.md
```
+
```
docs/getting-started.md
```
at the project root — existing files are kept.

-o path

moves the sidecar +

title.txt

, but the emitted docs entries (

./README.md

./docs/getting-started.md

) are sidecar-relative while the starter files land at the root — with a non-root

-o

, fix those paths before evaluating. The wizard refuses

-o flake.nix

and never writes or replaces a flake. No flake at all?

nix flake init -t github:darkmatter/prelude#default

scaffolds a starter instead (configure

prelude.*

inline, skip to Verify).

nix run github:darkmatter/prelude -- wizard

步骤：标题文本 + FIGlet字体、项目名称、命令、组件开关（

motd

menu

prompt

docs

.envrc

）、MOTD文案与布局、主题、确认。需在项目根目录运行，且需要交互式终端。向导会生成以下文件：

```
prelude.nix
```
— 完整选项模板：你选择的配置会被启用，其余所有选项以注释形式展示默认值（该文件同时可作为内联文档）。
```
title.txt
```
— 渲染后的文字标识，与配置文件放在同一目录，通过裸名引用，因此可在任意
```
-o
```
指定的目录中解析。
```
.envrc
```
（内容仅为
```
use flake
```
） — 仅在开启该开关且不存在该文件时生成。
若启用文档功能：会在项目根目录生成初始
```
README.md
```
+
```
docs/getting-started.md
```
— 已有文件会被保留。

-o path

参数可将sidecar和

title.txt

移动到指定路径，但生成的文档条目（

./README.md

、

./docs/getting-started.md

）是相对于sidecar的，而初始文件会生成在根目录——如果使用非根目录的

-o

参数，需在评估前修正这些路径。向导拒绝

-o flake.nix

参数，且永远不会写入或替换flake文件。完全没有flake？可运行

nix flake init -t github:darkmatter/prelude#default

来搭建初始项目（直接内联配置

prelude.*

，跳转到验证部分）。

2. Wire it into the flake (merge, don't replace)

2. 接入flake（合并而非替换）

The example shows the Prelude-specific lines to merge into the existing

flake.nix

— keep every current input, import, and devshell package:

nix

inputs.prelude.url = "github:darkmatter/prelude";

示例展示了需要合并到现有

flake.nix

中的Prelude相关代码行——请保留所有当前的input、import和devshell包：

nix

inputs.prelude.url = "github:darkmatter/prelude";

Fresh repo, no pins yet: share one nixpkgs/flake-parts via inputs:

inputs.nixpkgs.follows = "prelude/nixpkgs";

inputs.flake-parts.follows = "prelude/flake-parts";

flake.lock pins the resolved revision even with the default-branch URL.

Preserve an existing lock; use that revision for wizard/reference commands.

A URL ending in /<rev> may additionally select an explicit commit or tag.

inside mkFlake's module argument:

imports = [ inputs.prelude.flakeModules.default ./prelude.nix # generated sidecar; import it, never replace flake.nix ];

inside perSystem, alongside existing packages:

devShells.default = pkgs.mkShell { packages = [config.packages.prelude-shell]; };


Add only `config.packages.prelude-shell` to the devshell — it bundles every
enabled component and activates via its setup-hook. Do not add
`packages.prelude` (that backs the `prelude` app).

**No flake-parts** (blueprint, a plain `outputs` function): keep the flake as
it is and evaluate the same sidecar where the devshell is defined. It builds
the same packages as the module:

```nix

devShells.default = pkgs.mkShell { packages = [config.packages.prelude-shell]; };


仅需向devshell中添加`config.packages.prelude-shell`——它打包了所有已启用的组件，并通过其setup-hook激活。不要添加`packages.prelude`（那是`prelude`应用的后端）。

**无flake-parts**的情况（blueprint、普通`outputs`函数）：保持现有flake结构不变，在定义devshell的位置评估同一个sidecar文件。它会生成与模块相同的包：

```nix

blueprint: devshell.nix (nix/devshells/default.nix with prefix = "nix/")

{pkgs, inputs, ...}: let prelude = inputs.prelude.lib.evalModule pkgs ./prelude.nix; in pkgs.mkShell {packages = [prelude.packages.prelude-shell];}


Modules receive `pkgs`, so package-backed commands go straight into
`prelude.commands`; there is no `perSystem`. Pass other module arguments
(`self`, `inputs`) through `_module.args` on a wrapper module. Reference:
`examples/without-flake-parts/`.

{pkgs, inputs, ...}: let prelude = inputs.prelude.lib.evalModule pkgs ./prelude.nix; in pkgs.mkShell {packages = [prelude.packages.prelude-shell];}


模块会接收`pkgs`参数，因此基于包的命令可直接放入`prelude.commands`；不存在`perSystem`。可通过包装模块的`_module.args`传递其他模块参数（`self`、`inputs`）。参考示例：`examples/without-flake-parts/`。

3. Activation paths

3. 激活方式

```
nix develop
```
— with the prompt component enabled (wizard default) the setup hook sources the generated init: MOTD renders,
```
x
```
/
```
docs
```
land on PATH,
```
STARSHIP_CONFIG
```
exports. Nothing extra to configure.
direnv (nix-direnv) — the generated
```
.envrc
```
(
```
use flake
```
) loads the cached environment and renders the MOTD; new developers need only their existing direnv hook. Preserve an existing
```
.envrc
```
and its environment loader.
lorri — runs
```
shellHook
```
inside the Nix builder, so route it through the same
```
.envrc
```
: replace
```
use flake
```
with
```
eval "$(lorri export direnv-adapter)"
```
.
Custom
```
shellHook
```
—
```
eval "$(prelude-preflight)"
```
is the loader-aware activation line. Never
```
export -f
```
in a shellHook (zsh rejects the
```
%
```
in
```
BASH_FUNC_…%%
```
names); shell-specific setup belongs in
```
prelude hook
```
.

```
nix develop
```
— 启用提示符组件（向导默认开启）时，setup hook会加载生成的初始化脚本：渲染MOTD、将
```
x
```
/
```
docs
```
加入PATH、导出
```
STARSHIP_CONFIG
```
。无需额外配置。
direnv（nix-direnv） — 生成的
```
.envrc
```
（
```
use flake
```
）会加载缓存的环境并渲染MOTD；新开发者只需配置好现有的direnv钩子即可。请保留已有的
```
.envrc
```
及其环境加载器。
lorri — 会在Nix构建器中运行
```
shellHook
```
，因此需通过同一个
```
.envrc
```
路由：将
```
use flake
```
替换为
```
eval "$(lorri export direnv-adapter)"
```
。
自定义
```
shellHook
```
—
```
eval "$(prelude-preflight)"
```
是感知加载器的激活命令。切勿在shellHook中使用
```
export -f
```
（zsh会拒绝
```
BASH_FUNC_…%%
```
名称中的
```
%
```
）；特定于shell的配置应放在
```
prelude hook
```
中。

4. Customize

4. 自定义配置

Edit the generated

prelude.nix

(inline config in

flake.nix

works too); every option sits there as a commented default. Highlights:

prelude.theme

—

prelude

(default),

phosphor

minted

amber

solarized

nord

gruvbox

paper

(light),

mono

apathy

; token overrides via

prelude.palette

prelude.commands.<key>

— catalogue entries behind

; the first colon infers the menu group (

db:migrate

→

db

). Package-backed commands:

prelude.lib.fromPkg packages.dev { description = …; motd = 1; }

prelude.docs.pages = [{text = ./docs/foo.md;}]

— one page per file.

编辑生成的

prelude.nix

（也可在

flake.nix

中内联配置）；所有选项都以注释默认值的形式列在其中。亮点功能：

```
prelude.theme
```
— 可选值：
```
prelude
```
（默认）、
```
phosphor
```
、
```
minted
```
、
```
amber
```
、
```
solarized
```
、
```
nord
```
、
```
gruvbox
```
、
```
paper
```
（浅色）、
```
mono
```
、
```
apathy
```
；可通过
```
prelude.palette
```
覆盖主题令牌。
```
prelude.commands.<key>
```
—
```
x
```
命令背后的目录条目；第一个冒号用于推断菜单分组（
```
db:migrate
```
→
```
db
```
）。基于包的命令：
```
prelude.lib.fromPkg packages.dev { description = …; motd = 1; }
```
。

prelude.docs.pages = [{text = ./docs/foo.md;}]

— 每个文件对应一个页面。

5. Git-track new files, then verify

5. 跟踪新文件到Git，然后验证

Git-backed flakes exclude untracked files. Inspect

git status --short

and stage only the intended files created or edited for this setup; do not stage unrelated changes or suppress

git add

errors. Include a newly created

README.md

when referenced, the actual sidecar and sibling

title.txt

locations (including custom

-o

paths), and any newly referenced docs. Do not stage a pre-existing

.envrc

merely because the wizard uses it. No commit is required for local evaluation.

Alternatively, verify with

nix develop path:.

and

nix flake check path:.

to include the working directory without changing the index. This can include normally Git-excluded files, so use it only on a trusted local working tree.

Then real smoke checks:

nix develop     # MOTD renders, themed prompt appears
x --list        # catalogue table prints non-interactively
x               # picker opens (q quits)
docs            # viewer opens when docs pages exist (q quits)
motd            # banner reprints on demand
nix flake check # full build gate (heavier)

Non-interactive

nix develop -c …

stays silent by design (no banner in build logs) — use the interactive shell to see the MOTD.

基于Git的flake会排除未跟踪的文件。检查

git status --short

的输出，仅暂存本次安装创建或修改的目标文件；不要暂存无关更改，也不要忽略

git add

的错误。若有新生成的

README.md

被引用，请将其纳入，同时包括实际的sidecar文件和同级的

title.txt

（包括自定义

-o

路径），以及所有新引用的文档。不要仅仅因为向导使用了

.envrc

就暂存已存在的

.envrc

文件。本地评估不需要提交。

或者，可使用

nix develop path:.

和

nix flake check path:.

来验证，这样会包含工作目录的内容而无需修改暂存区。这可能会包含通常被Git忽略的文件，因此仅在可信的本地工作树上使用。

然后进行实际冒烟测试：

nix develop     # MOTD renders, themed prompt appears
x --list        # catalogue table prints non-interactively
x               # picker opens (q quits)
docs            # viewer opens when docs pages exist (q quits)
motd            # banner reprints on demand
nix flake check # full build gate (heavier)

非交互式的

nix develop -c …

默认保持静默（构建日志中不会出现横幅）——请使用交互式shell查看MOTD。

Handoff

交接

```
/prelude-just <arg>
```
— adapt an existing justfile.
```
/prelude-docs
```
— author docs-viewer pages.
```
/prelude <anything>
```
— other Prelude work.

```
/prelude-just <arg>
```
— 适配现有的justfile。
```
/prelude-docs
```
— 编写文档查看器页面。
```
/prelude <anything>
```
— 其他Prelude相关工作。