Skip to content

Commit fc01297

Browse files
codemonkeychrisclaude
codemonkeychris
and
claude
committed
docs: add Quick start to README + Manual setup section to getting-started
README "Quick start" was a one-line link to docs/guide; replace it with the actual `git clone` + `./bootstrap.ps1` + `dotnet new reactorapp` sequence so readers can copy-paste from the repo home page, then link to the manual walkthrough for readers who want the no-magic path. getting-started.md.dt gains a "Manual setup" section after "Verify the install" that walks through exactly what bootstrap.ps1 does, step by step: 1. dotnet --list-sdks (prerequisite check) 2. git clone + cd 3. dotnet pack src/Reactor.Cli (as global-tool nupkg) 4. dotnet tool install -g (+ in-process PATH prepend) 5. mur pack-local (framework + ProjectTemplates → local-nupkgs) 6. dotnet new uninstall + install (template, cache-bust) 7. symlink/copy plugins/reactor → ~/.claude/plugins/reactor 8. mur doctor verify Plus a "Refreshing after git pull" note (re-run steps 5 + 6; only do 3 + 4 when the CLI itself changed) and a "Why a global tool vs bin/<arch>/?" explainer pointing at the legacy mirror layout for users who'd rather PATH-mount the build output. Rendered docs/guide/getting-started.md mirrors the template addition. Re-running `mur docs compile` against the rest of the doc currently loses the inline todo/calculator code samples (snippet sources broken locally — pre-existing pipeline state, unrelated to this PR), so the rendered file was edited to add just the new Manual setup section rather than committing a degraded full-recompile. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 0d9f13d commit fc01297

3 files changed

Lines changed: 289 additions & 1 deletion

File tree

‎README.md‎

Lines changed: 13 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,9 +69,21 @@ Many of the experiments in this repo — the charting stack, accessibility valid
6969

7070
## Quick start
7171

72-
See **[docs/guide/getting-started.md](docs/guide/getting-started.md)** for the full walkthrough — prerequisites, building the framework and `mur` CLI from source, scaffolding your first app, and running through hello-world, a todo list, and a calculator with screenshots at each step.
72+
Reactor doesn't ship a signed NuGet yet, so you build the framework, the `mur` CLI, and the project template from source. `bootstrap.ps1` collapses that into a single command — ~3 minutes per machine.
7373

74+
```powershell
75+
git clone https://github.com/microsoft/microsoft-ui-reactor.git
76+
cd microsoft-ui-reactor
77+
./bootstrap.ps1
7478
79+
dotnet new reactorapp -n MyApp
80+
cd MyApp
81+
dotnet run
82+
```
83+
84+
`bootstrap.ps1` packs `mur` as a `dotnet tool` global install (cross-shell PATH, no per-arch `$env:Path` edits), packs the framework + project templates into `local-nupkgs/`, registers the `dotnet new reactorapp` template, and installs the Reactor agent plugin under `~/.claude/plugins/reactor`. Re-run it (or `mur upgrade` for a lighter refresh) after `git pull`. Verify a working install with `mur doctor`.
85+
86+
Prefer to wire it up by hand? **[docs/guide/getting-started.md](docs/guide/getting-started.md#manual-setup)** has a no-magic walkthrough of the exact `dotnet pack` / `dotnet tool install` / `dotnet new install` calls `bootstrap.ps1` makes, plus the full hello-world → todo → calculator tour.
7587

7688
---
7789

‎docs/_pipeline/templates/getting-started.md.dt‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -100,6 +100,144 @@ remediation for anything broken.
100100
> [spec 022](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/specs/022-packaging-and-distribution.md) §4.4).
101101
> Until that release ships, the bootstrap above is the supported path.
102102

103+
### Manual setup
104+
105+
If you'd rather not run `bootstrap.ps1`, here is exactly what it does, step
106+
by step. Every command is a stock `dotnet` or `git` invocation — no Reactor
107+
tooling required until the very last step, where you build `mur` from source
108+
and install it as a global tool. Each block below corresponds to a numbered
109+
phase in `bootstrap.ps1`, so the script is a useful cross-reference if
110+
anything goes wrong.
111+
112+
**1. Confirm prerequisites.** Reactor requires .NET 10 or later. The Windows
113+
App SDK is pulled in transitively when the framework builds.
114+
115+
```powershell
116+
dotnet --list-sdks
117+
# Expect at least one entry starting with "10."
118+
```
119+
120+
**2. Clone and enter the repo.** Everything below assumes the working
121+
directory is the repo root.
122+
123+
```powershell
124+
git clone https://github.com/microsoft/microsoft-ui-reactor.git
125+
cd microsoft-ui-reactor
126+
```
127+
128+
**3. Pack `mur` as a global-tool nupkg.** `Reactor.Cli.csproj` sets
129+
`PackAsTool=true`, so `dotnet pack` produces a tool package. The
130+
`-p:Platform` flag matters because the build step runs the SignaturesGen
131+
apphost to refresh `skills/reactor.api.txt`; that apphost must match the
132+
host architecture.
133+
134+
```powershell
135+
$hostArch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'ARM64' } else { 'x64' }
136+
dotnet pack src/Reactor.Cli/Reactor.Cli.csproj `
137+
-c Release `
138+
"-p:Platform=$hostArch" `
139+
-o local-nupkgs `
140+
--nologo
141+
# Produces local-nupkgs/Microsoft.UI.Reactor.Cli.<version>.nupkg
142+
```
143+
144+
**4. Install `mur` as a dotnet global tool.** This is what puts `mur` on
145+
PATH cross-shell with no `$env:Path` edits. If a previous install exists,
146+
use `update` instead of `install`.
147+
148+
```powershell
149+
dotnet tool install -g `
150+
--add-source ./local-nupkgs `
151+
Microsoft.UI.Reactor.Cli `
152+
--no-cache --ignore-failed-sources
153+
154+
# If `mur` was already installed:
155+
# dotnet tool update -g --add-source ./local-nupkgs Microsoft.UI.Reactor.Cli --no-cache --ignore-failed-sources
156+
```
157+
158+
`dotnet tool install -g` adds `~/.dotnet/tools` to the **user** PATH, which
159+
the current shell does not automatically inherit. For this session only,
160+
prepend it manually so the next step finds `mur`:
161+
162+
```powershell
163+
$env:Path = "$env:USERPROFILE\.dotnet\tools;$env:Path"
164+
```
165+
166+
New PowerShell windows pick up the user-PATH change on their own.
167+
168+
**5. Pack the framework and project templates.** This is what produces the
169+
two `0.0.0-local` nupkgs that the `dotnet new reactorapp` template
170+
references.
171+
172+
```powershell
173+
mur pack-local
174+
# Produces:
175+
# local-nupkgs/Microsoft.UI.Reactor.0.0.0-local.nupkg
176+
# local-nupkgs/Microsoft.UI.Reactor.ProjectTemplates.0.0.0-local.nupkg
177+
```
178+
179+
If you'd rather not depend on the freshly-installed `mur`, you can invoke
180+
the source project directly:
181+
182+
```powershell
183+
dotnet run --project src/Reactor.Cli/Reactor.Cli.csproj `
184+
-c Release "-p:Platform=$hostArch" -- pack-local
185+
```
186+
187+
**6. Install the `dotnet new reactorapp` template.** The template engine
188+
caches by package id, so a same-version repack can lose to the cached copy.
189+
Always uninstall first.
190+
191+
```powershell
192+
dotnet new uninstall Microsoft.UI.Reactor.ProjectTemplates 2>$null
193+
dotnet new install local-nupkgs/Microsoft.UI.Reactor.ProjectTemplates.0.0.0-local.nupkg
194+
```
195+
196+
**7. (Optional) Install the Reactor agent plugin.** If you use Claude Code
197+
or another agent and want it to author Reactor code with the right
198+
factories, drop the in-repo plugin folder into your agent's plugin path. A
199+
symlink is preferred so edits in the checkout are immediately visible; a
200+
copy works when you can't create symlinks (Developer Mode off + non-admin
201+
shell).
202+
203+
```powershell
204+
$pluginSrc = (Resolve-Path "plugins/reactor").Path
205+
$pluginDst = "$env:USERPROFILE\.claude\plugins\reactor"
206+
New-Item -ItemType Directory -Path (Split-Path $pluginDst) -Force | Out-Null
207+
if (Test-Path $pluginDst) { Remove-Item $pluginDst -Recurse -Force }
208+
try {
209+
New-Item -ItemType SymbolicLink -Path $pluginDst -Target $pluginSrc -ErrorAction Stop | Out-Null
210+
} catch {
211+
Copy-Item $pluginSrc $pluginDst -Recurse -Force
212+
}
213+
```
214+
215+
For Copilot CLI or other agents, follow that tool's plugin-install path and
216+
point it at `<repo>/plugins/reactor`.
217+
218+
**8. Verify.** `mur doctor` performs the same checks the bootstrap script's
219+
final stage relies on — SDK version, `mur` resolvability, both `0.0.0-local`
220+
nupkgs present, template registered, and plugin installed.
221+
222+
```powershell
223+
mur doctor
224+
```
225+
226+
#### Refreshing after `git pull`
227+
228+
Without the bootstrap script, repeat **steps 5 and 6** after every pull —
229+
the framework nupkg and the template both need to be regenerated against
230+
the new source. Repeat **steps 3 and 4** only when `src/Reactor.Cli/`
231+
itself changes (a running `mur` process cannot replace its own binary, so
232+
the install must happen from a shell that isn't already running `mur`).
233+
234+
> **Why a global tool instead of just running from `bin/<arch>/`?** Both
235+
> work. The repo's CLI csproj still mirrors `mur.exe` to `bin/<arch>/` after
236+
> every build for the legacy PATH layout. The global-tool install is just
237+
> the friendliest default — it puts `mur` on PATH cross-shell, cross-CWD,
238+
> with no arch-aware PATH munging, and `dotnet tool update -g` becomes the
239+
> upgrade verb.
240+
103241
<!-- ai:caveat -->
104242
The bootstrap is the supported developer path *only* until the signed public
105243
NuGet ships under spec 022. If you skip `bootstrap.ps1` and try `dotnet new

‎docs/guide/getting-started.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -88,6 +88,144 @@ remediation for anything broken.
8888
> [spec 022](https://github.com/microsoft/microsoft-ui-reactor/blob/main/docs/specs/022-packaging-and-distribution.md) §4.4).
8989
> Until that release ships, the bootstrap above is the supported path.
9090
91+
### Manual setup
92+
93+
If you'd rather not run `bootstrap.ps1`, here is exactly what it does, step
94+
by step. Every command is a stock `dotnet` or `git` invocation — no Reactor
95+
tooling required until the very last step, where you build `mur` from source
96+
and install it as a global tool. Each block below corresponds to a numbered
97+
phase in `bootstrap.ps1`, so the script is a useful cross-reference if
98+
anything goes wrong.
99+
100+
**1. Confirm prerequisites.** Reactor requires .NET 10 or later. The Windows
101+
App SDK is pulled in transitively when the framework builds.
102+
103+
```powershell
104+
dotnet --list-sdks
105+
# Expect at least one entry starting with "10."
106+
```
107+
108+
**2. Clone and enter the repo.** Everything below assumes the working
109+
directory is the repo root.
110+
111+
```powershell
112+
git clone https://github.com/microsoft/microsoft-ui-reactor.git
113+
cd microsoft-ui-reactor
114+
```
115+
116+
**3. Pack `mur` as a global-tool nupkg.** `Reactor.Cli.csproj` sets
117+
`PackAsTool=true`, so `dotnet pack` produces a tool package. The
118+
`-p:Platform` flag matters because the build step runs the SignaturesGen
119+
apphost to refresh `skills/reactor.api.txt`; that apphost must match the
120+
host architecture.
121+
122+
```powershell
123+
$hostArch = if ($env:PROCESSOR_ARCHITECTURE -eq 'ARM64') { 'ARM64' } else { 'x64' }
124+
dotnet pack src/Reactor.Cli/Reactor.Cli.csproj `
125+
-c Release `
126+
"-p:Platform=$hostArch" `
127+
-o local-nupkgs `
128+
--nologo
129+
# Produces local-nupkgs/Microsoft.UI.Reactor.Cli.<version>.nupkg
130+
```
131+
132+
**4. Install `mur` as a dotnet global tool.** This is what puts `mur` on
133+
PATH cross-shell with no `$env:Path` edits. If a previous install exists,
134+
use `update` instead of `install`.
135+
136+
```powershell
137+
dotnet tool install -g `
138+
--add-source ./local-nupkgs `
139+
Microsoft.UI.Reactor.Cli `
140+
--no-cache --ignore-failed-sources
141+
142+
# If `mur` was already installed:
143+
# dotnet tool update -g --add-source ./local-nupkgs Microsoft.UI.Reactor.Cli --no-cache --ignore-failed-sources
144+
```
145+
146+
`dotnet tool install -g` adds `~/.dotnet/tools` to the **user** PATH, which
147+
the current shell does not automatically inherit. For this session only,
148+
prepend it manually so the next step finds `mur`:
149+
150+
```powershell
151+
$env:Path = "$env:USERPROFILE\.dotnet\tools;$env:Path"
152+
```
153+
154+
New PowerShell windows pick up the user-PATH change on their own.
155+
156+
**5. Pack the framework and project templates.** This is what produces the
157+
two `0.0.0-local` nupkgs that the `dotnet new reactorapp` template
158+
references.
159+
160+
```powershell
161+
mur pack-local
162+
# Produces:
163+
# local-nupkgs/Microsoft.UI.Reactor.0.0.0-local.nupkg
164+
# local-nupkgs/Microsoft.UI.Reactor.ProjectTemplates.0.0.0-local.nupkg
165+
```
166+
167+
If you'd rather not depend on the freshly-installed `mur`, you can invoke
168+
the source project directly:
169+
170+
```powershell
171+
dotnet run --project src/Reactor.Cli/Reactor.Cli.csproj `
172+
-c Release "-p:Platform=$hostArch" -- pack-local
173+
```
174+
175+
**6. Install the `dotnet new reactorapp` template.** The template engine
176+
caches by package id, so a same-version repack can lose to the cached copy.
177+
Always uninstall first.
178+
179+
```powershell
180+
dotnet new uninstall Microsoft.UI.Reactor.ProjectTemplates 2>$null
181+
dotnet new install local-nupkgs/Microsoft.UI.Reactor.ProjectTemplates.0.0.0-local.nupkg
182+
```
183+
184+
**7. (Optional) Install the Reactor agent plugin.** If you use Claude Code
185+
or another agent and want it to author Reactor code with the right
186+
factories, drop the in-repo plugin folder into your agent's plugin path. A
187+
symlink is preferred so edits in the checkout are immediately visible; a
188+
copy works when you can't create symlinks (Developer Mode off + non-admin
189+
shell).
190+
191+
```powershell
192+
$pluginSrc = (Resolve-Path "plugins/reactor").Path
193+
$pluginDst = "$env:USERPROFILE\.claude\plugins\reactor"
194+
New-Item -ItemType Directory -Path (Split-Path $pluginDst) -Force | Out-Null
195+
if (Test-Path $pluginDst) { Remove-Item $pluginDst -Recurse -Force }
196+
try {
197+
New-Item -ItemType SymbolicLink -Path $pluginDst -Target $pluginSrc -ErrorAction Stop | Out-Null
198+
} catch {
199+
Copy-Item $pluginSrc $pluginDst -Recurse -Force
200+
}
201+
```
202+
203+
For Copilot CLI or other agents, follow that tool's plugin-install path and
204+
point it at `<repo>/plugins/reactor`.
205+
206+
**8. Verify.** `mur doctor` performs the same checks the bootstrap script's
207+
final stage relies on — SDK version, `mur` resolvability, both `0.0.0-local`
208+
nupkgs present, template registered, and plugin installed.
209+
210+
```powershell
211+
mur doctor
212+
```
213+
214+
#### Refreshing after `git pull`
215+
216+
Without the bootstrap script, repeat **steps 5 and 6** after every pull —
217+
the framework nupkg and the template both need to be regenerated against
218+
the new source. Repeat **steps 3 and 4** only when `src/Reactor.Cli/`
219+
itself changes (a running `mur` process cannot replace its own binary, so
220+
the install must happen from a shell that isn't already running `mur`).
221+
222+
> **Why a global tool instead of just running from `bin/<arch>/`?** Both
223+
> work. The repo's CLI csproj still mirrors `mur.exe` to `bin/<arch>/` after
224+
> every build for the legacy PATH layout. The global-tool install is just
225+
> the friendliest default — it puts `mur` on PATH cross-shell, cross-CWD,
226+
> with no arch-aware PATH munging, and `dotnet tool update -g` becomes the
227+
> upgrade verb.
228+
91229
> **Caveat:** The bootstrap is the supported developer path *only* until the signed public
92230
> NuGet ships under spec 022. If you skip `bootstrap.ps1` and try `dotnet new
93231
> reactorapp` anyway, the scaffolder fails with `NU1101: Unable to find package

0 commit comments

Comments
 (0)