菜单
Build, publish, and debug workflows for local development. Use when iterating on UI, debugging message sending, or testing on mobile devices.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/freenet/river --skill local-dev命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
基于 SOC 职业分类
正在显示 SKILL.md
| name | local-dev |
| description | Build, publish, and debug workflows for local development. Use when iterating on UI, debugging message sending, or testing on mobile devices. |
Build, publish, and debug workflows. For general Freenet local node management,
contract publishing, and debugging patterns, see the local-dev skill in the
freenet-agent-skills plugin.
which freenet fdev dx
rustup target add wasm32-unknown-unknown
# 1. Build the web-container-tool (native, not cross-compiled)
cargo build --release -p web-container-tool
# 2. Build the web container contract WASM
cargo build --release --target wasm32-unknown-unknown -p web-container-contract
# 3. Generate test keys
mkdir -p test-contract
target/release/web-container-tool generate --output test-contract/test-keys.toml
# 4. Start an isolated test node (in a separate terminal or background)
# Choose an appropriate log directory for your OS:
# macOS: ~/Library/Logs/freenet-test-node
# Linux: ~/.local/share/freenet-test-node/logs
LOG_DIR=~/Library/Logs/freenet-test-node # adjust for your OS
mkdir -p "$LOG_DIR"
freenet network \
--network-port 31338 \
--ws-api-port 7510 \
--ws-api-address 0.0.0.0 \
--is-gateway \
--skip-load-from-network \
--data-dir ~/freenet-test-node/data \
--public-network-address 127.0.0.1 \
--log-dir \
--log-level debug
# Full rebuild + republish (~15s):
./scripts/local-republish.sh
# Skip UI build if only repackaging (~2s):
./scripts/local-republish.sh --skip-build
# Target a different port:
./scripts/local-republish.sh --port 7509
The script outputs desktop and phone URLs after publishing. Use Playwright MCP tools to verify the result without opening a manual browser — see "Automated verification with Playwright MCP" below.
cargo build --release --target wasm32-unknown-unknown -p room-contract # Room contract WASM
cargo build --release --target wasm32-unknown-unknown -p chat-delegate # Chat delegate WASM
cargo build --release --target wasm32-unknown-unknown -p web-container-contract # Web container
(cd ui && dx build --release) # UI (Dioxus)
cargo make dev # dx serve with hot reload (localhost:8080)
cargo make dev-example # dx serve with example data (no network needed)
# 1. Make your UI change in ui/src/
# 2. Rebuild + republish:
./scripts/local-republish.sh
# 3. Hard-refresh browser (Cmd+Shift+R / Ctrl+Shift+R)
# 1. Rebuild contract
cargo build --release --target wasm32-unknown-unknown -p room-contract
# 2. Copy to UI public dir (UI embeds contract WASM)
cp target/wasm32-unknown-unknown/release/room_contract.wasm ui/public/contracts/
# 3. Full rebuild + publish
./scripts/local-republish.sh
# 1. Rebuild delegate (UI includes delegate via include_bytes!)
cargo build --release --target wasm32-unknown-unknown -p chat-delegate
# 2. Rebuild UI (picks up new delegate) + publish
./scripts/local-republish.sh
The cargo make publish tasks cross-compile the web-container-tool for
x86_64-unknown-linux-gnu. On other platforms, use local-republish.sh
or run the steps manually:
# 1. Build UI
(cd ui && dx build --release)
# 2. Compress
(cd target/dx/river-ui/release/web/public && tar -cJf ../../../../../webapp/webapp.tar.xz *)
# 3. Sign with test keys
target/release/web-container-tool sign \
--input target/webapp/webapp.tar.xz \
--output target/webapp/webapp-test.metadata \
--parameters target/webapp/webapp-test.parameters \
--key-file test-contract/test-keys.toml \
--version $(( $(date +%s) / 60 ))
# 4. Publish
fdev --port 7510 execute put \
--code target/wasm32-unknown-unknown/release/web_container_contract.wasm \
--parameters target/webapp/webapp-test.parameters \
contract \
--webapp-archive target/webapp/webapp.tar.xz \
--webapp-metadata target/webapp/webapp-test.metadata
The Playwright MCP plugin is enabled (.claude/settings.local.json). Use it
to verify UI changes without manually opening a browser.
After publishing to a local node:
browser_navigate → URL from local-republish.sh outputbrowser_snapshot → verify layout and content render correctlybrowser_fill_form + browser_click → test message sendingbrowser_console_messages → check for WASM panics or errorsbrowser_resize → test mobile breakpoints (767px, 480px)Against example data (no node needed):
cargo make build-ui-example-no-sync
cd target/dx/river-ui/release/web/public && python3 -m http.server 8082 &
Then browser_navigate → http://127.0.0.1:8082/
Typical iteration loop:
./scripts/local-republish.shbrowser_navigate to published URLbrowser_snapshot to verifybrowser_console_messages to check for errorsBuilt-in debug overlay activated via ?debug=1 query parameter. Shows
timestamped log messages on-screen with a minimize/expand toggle — essential
for mobile where console is inaccessible.
http://{IP}:7510/v1/contract/web/{CONTRACT_ID}/?debug=1
Use crate::util::debug_log("msg") to log to the overlay. Does nothing
without ?debug=1.
A WASM panic hook creates a visible red error overlay showing the panic message. Appears automatically on any crash, no query param needed.
create_room_modal.rs generates SigningKey, stores it in the ROOMS signal as RoomData::self_sk, and calls store_signing_key() to save a copy in the chat delegatesign_message_locally(&msg_bytes, &self_sk). There is no delegate round-trip on the message path (freenet/river#512) — it could not change the signature bytes and it cost seconds of visible lagsign_*_with_fallback → send_delegate_request(Sign*{...}) → delegate looks up signing_key:{origin}:{room_key} → returns signatureself_sk; otherwise (and on any delegate failure) the payload is signed locally with self_skNEEDS_SYNC set → ProcessRooms → UPDATE sentKey debugging points:
NEEDS_SYNC effect also
fires save_rooms_to_delegate() alongside the UPDATE, so a delegate op does
contend for the same node afterwards"Sign request for room, signature created: true/false" — if false, the delegate doesn't have the key"Delegate signing failed, using fallback"riverctl --node-url ws://127.0.0.1:7510/v1/contract/command?encodingProtocol=native room list
[send] signed OK (browser, with ?debug=1) → the message was signed locally[send] delta applied OK → it is in local state and on screenUpdate { key: ... } → UPDATE arrived at nodeResultRouter received result → UPDATE processed, result sent back to clientIf step 2 happens but step 3 doesn't, the browser died between applying the message locally and sending the UPDATE. There is no delegate step here — see "Signing flow" above.
Firefox mobile runs Dioxus signal subscriber notifications synchronously
during Drop, unlike Chrome/Safari which defer to microtask boundaries. This
causes RefCell already borrowed panics in WASM at three levels:
Dioxus signal re-entrancy — ROOMS.with_mut() Drop triggers subscriber
notifications that cascade into ROOMS.read(). Fix: use try_read() for
all reactive signal reads. try_read() still registers Dioxus subscriptions
(confirmed in Dioxus 0.7.x source) but returns Err instead of panicking.
wasm-bindgen-futures task re-entrancy — spawn_local inside a polled
future causes re-entrant Task::run() at singlethread.rs:132. Fix: use
safe_spawn_local() helper (in util.rs) that wraps spawn_local in
setTimeout(0) to break out of the WASM call stack.
Signal mutation inside spawn_local — ROOMS.with_mut() inside a
spawn_local task triggers notifications that re-queue the same task. Fix:
move signal mutations out of spawn_local via setTimeout(0).
Key pattern for safe signal writes in WASM:
// WRONG — can cause re-entrant borrow in Firefox
spawn_local(async {
// ... async work ...
ROOMS.with_mut(|rooms| { /* mutate */ });
});
// RIGHT — defer mutation to clean execution context
#[cfg(target_arch = "wasm32")]
{
let cb = Closure::once_into_js(move || {
ROOMS.with_mut(|rooms| { /* mutate */ });
});
web_sys::window().unwrap()
.set_timeout_with_callback(&cb.into()).ok();
}
Important: Signal clears in use_effect must be synchronous, not deferred.
Deferring a clear that the effect subscribes to causes an infinite loop.
See mark_needs_sync() in app.rs and safe_spawn_local() in util.rs
for canonical examples.
| Symptom | Cause | Fix |
|---|---|---|
| Messages fail to send (new room) | Signing key not stored in delegate | Fixed: create_room_modal.rs now calls store_signing_key after room creation |
| "signature created: false" in node logs | Delegate can't find signing key for room | Ensure StoreSigningKey is sent after room creation; fallback signs locally |
| Mobile send appears stuck | Browser suspends WASM when screen locks | Keep phone screen active; delegate signing avoids long async chains |
RefCell already borrowed on Firefox mobile | Dioxus signal re-entrant borrow during Drop | Use try_read() instead of read() for reactive signal access |
Crash at singlethread.rs:132 | spawn_local inside polled future on Firefox | Use safe_spawn_local() to defer via setTimeout(0) |
| Blank page after code change (no panic) | Infinite loop from deferred signal clear | Keep signal clears synchronous in use_effect; only defer spawns |