Skill: Shadow-CLJS Debug

Goal

To systematically identify and fix compilation errors, dependency issues, and configuration problems in shadow-cljs projects.

Use This Skill When

• shadow-cljs compile fails.
• The build hangs or loops indefinitely.
• You see “Undeclared Var”, “No such namespace”, or “Analysis Error”.
• You suspect a dependency is missing.

Do Not Use This Skill When

• The error is clearly a syntax error (use clojure-syntax-rescue).

Steps

1. Analyze Error:
   • Read the error message fully. Is it a compilation error or a dependency error?
   • Undeclared Var: You forgot to (:require [namespace :as alias]) or are using a function that doesn’t exist.
   • No such namespace: The file path does not match the namespace declaration, or the package is not installed.
2. Check Config:
   • Read shadow-cljs.edn. Is the build ID correct? Are source paths included?
   • Read deps.edn (if used). Is the dependency listed?
   • Read package.json. Is the npm package installed?
3. Clean State:
   • If behavior is weird or inconsistent, delete the cache: rm -rf .shadow-cljs .cpcache.
   • Restart the watch process.
4. Verify Interop:
   • npm: Ensure you use (:require ["package-name" :as pkg]) for npm packages.
   • Globals: Use js/window or js/console for globals, do not require them.
5. Fix & Retry:
   • Apply the fix.
   • Run npx shadow-cljs compile <build-id> (or release for production).

Output

• A successful compilation (exit code 0).

Strong Hints

• Constraint: Never edit the output files (for example public/js/main.js). Only edit .cljs source.
• Tip: Shadow-CLJS relies heavily on package.json for JS deps. If an npm import fails, check node_modules first (workspace-dependency-check).
• Tip: (:require [foo.bar :as bar]) requires a file at src/foo/bar.cljs. Check file paths match namespaces exactly.

Suggested Next Skills

Check the Skill Graph for the full workflow.

• clojure-syntax-rescue
• workspace-dependency-check