Skip to content

Disentinel/grafema / .claude/skills/rust-embed-rebuild-invalidation

rust-embed-rebuild-invalidation

Verified

Force `rust-embed` to re-embed assets from `$GRAFEMA_UI_DIST` (or any env-driven path) when cargo's incremental compilation skips the macro re-expansion. Use when: (1) you rebuilt the GUI bundle but the rust-server binary still serves the OLD bundle, (2) `cargo build --release` finishes in seconds (incremental hit) and `strings target/release/binary | grep <new-hash>` finds nothing, (3) any rust-embed pipeline where assets live outside the cargo source tree and are picked up via env var or symlink. Cargo only re-runs the proc macro when the rust file declaring `#[derive(RustEmbed)]` changes — env var changes alone don't trigger it.

FileKindSize
SKILL.mdskill md3.9 KB
---
name: rust-embed-rebuild-invalidation
description: |
  Force `rust-embed` to re-embed assets from `$GRAFEMA_UI_DIST` (or any env-driven path) when cargo's incremental compilation skips the macro re-expansion. Use when:
  (1) you rebuilt the GUI bundle but the rust-server binary still serves the OLD bundle,
  (2) `cargo build --release` finishes in seconds (incremental hit) and `strings target/release/binary | grep <new-hash>` finds nothing,
  (3) any rust-embed pipeline where assets live outside the cargo source tree and are picked up via env var or symlink.
  Cargo only re-runs the proc macro when the rust file declaring `#[derive(RustEmbed)]` changes — env var changes alone don't trigger it.
author: Claude Code
version: 1.0.0
date: 2026-04-25
---

# Rust-Embed Rebuild Invalidation

## Problem

`rfdb-server` embeds the GUI bundle via `rust-embed`:

```rust
#[derive(RustEmbed)]
#[folder = "$GRAFEMA_UI_DIST"]
pub struct UiAssets;
```

You rebuild the GUI:

```bash
pnpm --filter @grafema/gui build       # produces dist/assets/HexAtlas-NEW.js
GRAFEMA_UI_DIST=$(pwd)/packages/gui/dist cargo build --release -p rfdb
```

Cargo says "Finished in 6 seconds" — way too fast for a full re-embed. You start the server, hit the URL, and `curl http://localhost:51833/ui/default | grep HexAtlas` returns the **OLD hash**. Re-running the build doesn't help.

## Why this happens

`rust-embed` is a `proc_macro` evaluated at compile time. Cargo decides whether to re-run a proc-macro by hashing the source file that contains the `#[derive(RustEmbed)]`. **Changes to environment variables (like `GRAFEMA_UI_DIST`) or to the contents of the asset folder do not invalidate the proc-macro.** Cargo treats it as cache-hit, the previously expanded include-bytes! tree stays embedded, and your new asset never makes it into the binary.

## Fix — touch the host file

```bash
touch packages/rfdb-server/src/static_ui.rs
GRAFEMA_UI_DIST=$(pwd)/packages/gui/dist cargo build --release -p rfdb
```

`touch` updates the file's mtime, which forces cargo to re-run the proc-macro, which re-reads the env var, which re-embeds the new assets. Build will take longer (full rust-embed re-expansion).

Verify:

```bash
strings target/release/rfdb-server | grep -E "HexAtlas-[A-Za-z0-9]+\.js" | head -3
# Should print the NEW hash (matches dist/assets/HexAtlas-NEW.js)
```

## Why not `cargo clean`?

Works, but overkill — clears the entire target/, ~5 minute full rebuild. Touching one file is ~30 seconds and surgical.

## Detection — how to know you've been bitten

If after `cargo build --release`:

1. `ls -la target/release/<binary>` — is the mtime older than your last `pnpm build`?
2. `strings target/release/<binary> | grep <known-new-hash>` — empty? You hit this bug.

**Always verify embed freshness before debugging "the server returns old data".** It's the second-most-common false-trail (after stale process on the port — see `zombie-process-port-hunt`).

## Project script

For the Grafema build pipeline, the canonical recipe (from `scripts/build-gui-for-rfdb.sh`) should be:

```bash
pnpm --filter @grafema/gui build
touch packages/rfdb-server/src/static_ui.rs    # ← invalidate macro
GRAFEMA_UI_DIST=$(pwd)/packages/gui/dist \
  cargo build --release -p rfdb
```

Without the `touch`, the script's "rebuild rfdb-server with new bundle baked in" promise is silently broken on incremental builds.

## Generalization

This pattern applies to any cargo proc-macro that reads files or env vars at expansion time:

- `include_bytes!` / `include_str!` — same problem if the included path is outside cargo's tracked tree
- `serde_json::from_str(include_str!(...))` — same
- Custom build.rs that reads from `$ENV` and writes a generated source — usually OK if `cargo:rerun-if-env-changed=ENV` is declared, but easy to forget

If you see "fast cargo rebuild + stale embedded data" for any of these — the workaround (`touch` the host file) generalizes.
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall