Naga Setup

naga-setup

Wire a repo so every WGSL edit is compiled by naga immediately, and the whole shader tree can be checked in one command. WGSL errors otherwise only surface in the browser console after a reload — this collapses that loop to zero.

The thing to keep straight

A working setup is four artifacts, and they arrive by different routes:

So a fresh clone of an already-wired repo still has half a setup: a hook that fires and does nothing, because naga isn't on the machine. That's why step 1 is the toolchain and not the config. Check each artifact, install whichever are missing, and when all four are present say so and stop — re-adding the hook just duplicates it.

Steps

1. Check the local toolchain

naga --version
jq --version

Missing naga makes everything else inert, so fix it first — and offer to run the install rather than just quoting it, since on a fresh clone this is usually the only gap:

brew install naga-cli    # macOS / Linux — NOT `brew install naga`, that formula
                         # is a Snake game and collides on the same binary name
cargo install naga-cli   # any platform with Rust

If naga --version succeeds but prints something that isn't a wgpu version string, that's the Snake game — people hit this often enough to be worth checking rather than assuming a zero exit means the compiler.

jq reads the tool payload for the hook. Usually present on macOS; brew install jq otherwise.

2. Install the hook

Already a naga entry under hooks.PostToolUse in the repo's .claude/settings.json? Leave it and move on.

Otherwise add it there — the repo's file, not the user's global one, so it travels with the repo and doesn't fire in unrelated projects:

{
    "hooks": {
        "PostToolUse": [
            {
                "matcher": "Edit|Write|MultiEdit",
                "hooks": [
                    {
                        "type": "command",
                        "command": "f=$(jq -r '.tool_input.file_path // empty'); case \"$f\" in *.wgsl) out=$(naga \"$f\" 2>&1) || { echo \"WGSL validation failed: $f\" >&2; echo \"$out\" >&2; exit 2; };; esac",
                        "statusMessage": "Validating WGSL with naga"
                    }
                ]
            }
        ]
    }
}

Merge, don't clobber. If .claude/settings.json exists, read it and append to the existing hooks.PostToolUse array — overwriting someone's settings to add a shader check is a bad trade.

Notes in case the command needs adapting:

• The payload arrives as JSON on stdin; jq -r '.tool_input.file_path' pulls the path out. It's absolute, so the hook works regardless of cwd.
• The case guard means non-WGSL edits cost one shell spawn and exit silently — cheap enough to leave unconditional.
• Exit code 2 is what makes it blocking: stderr goes back to the agent. Any other non-zero code just warns.

3. Install the batch script

Already a scripts/validate-shaders.mjs? Leave it — a repo's copy may have been adapted, and overwriting it with a near-identical file is a bad trade.

Otherwise copy assets/validate-shaders.mjs into the repo's scripts/ (create it if needed). It walks the whole tree from the root, skipping generated and vendored directories — deliberately not just src/, since shaders also live in examples/, demos/, sandbox/, and a batch check that quietly misses most of them is worse than no batch check. Widen its SKIP set if the repo has a big generated directory the default misses. It also takes explicit paths: node scripts/validate-shaders.mjs path/to/one.wgsl.

Exit codes: 0 all valid, 1 a shader failed, 2 naga not installed.

If the repo has a package.json, add:

"scripts": { "validate:shaders": "node scripts/validate-shaders.mjs" }

Not a node project? Leave the script without the npm entry — it only needs a node binary. No node at all? Install the hook alone and say the batch command isn't available.

In a monorepo, the script's scope is the parent of wherever it sits: packages/renderer/scripts/ validates that package, the repo root validates all of them. Ask which the user wants — per-package when one package has shaders, root when several do — and put the npm entry in whichever package.json sits beside it. The hook needs no such choice; one at the repo root covers every package.