{"slug":"pracht-debug","title":"pracht-debug","summary":"Framework-aware debugging for pracht: route matching, loader and API errors, rendering and hydration, middleware, HMR, and build failures — root cause first. Use for \"debug this\", \"fix this bug\", \"why is this broken\", \"blank page\", \"hydration mismatch\", \"404 on my route\"; suggest","platform":"Claude","tags":[],"authorName":"LLM Mart","authorSlug":"llm-mart","score":0,"source":"github","price":null,"verified":false,"createdAt":"2026-10-19T21:17:25.965813Z","repo":{"url":"https://github.com/JoviDeCroock/pracht","stars":99,"forks":5,"license":"MIT","updatedAt":"2026-10-19T16:43:31Z"},"bodyHtml":"<hr>\n<p>name: pracht-debug\nversion: 1.5.0\ndescription: |\nFramework-aware debugging for pracht: route matching, loader and API errors,\nrendering and hydration, middleware, HMR, and build failures — root cause first.\nUse for \"debug this\", \"fix this bug\", \"why is this broken\", \"blank page\",\n\"hydration mismatch\", \"404 on my route\"; suggest it when the user reports\nunexpected pracht behavior.\nallowed-tools:</p>\n<ul>\n<li>Bash</li>\n<li>Read</li>\n<li>Write</li>\n<li>Edit</li>\n<li>Grep</li>\n<li>Glob</li>\n<li>AskUserQuestion</li>\n</ul>\n<hr>\n<h1>Pracht Debug</h1>\n<p><strong>Iron law: no fixes without root-cause investigation first.</strong> Read the\nrelevant source before diagnosing, start from the most likely cause for the\nsymptom rather than a full audit, and when you find the root cause explain\n<em>why</em> it breaks. After fixing, prove the fix — run the test, check the dev\nserver. Never say \"this should fix it.\"</p>\n<h2>Instruments</h2>\n<p>Reach for these before deep manual inspection:</p>\n<table>\n<thead>\n<tr>\n<th>Tool</th>\n<th>Use</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td><code>pracht verify</code> (<code>--changed</code> to scope to git-changed files)</td>\n<td>Fast confidence check</td>\n</tr>\n<tr>\n<td><code>pracht doctor</code></td>\n<td>Broader broken wiring or missing files</td>\n</tr>\n<tr>\n<td><code>pracht docs &lt;topic&gt;</code> / <code>pracht docs --search &lt;query&gt;</code></td>\n<td>Docs bundled with the installed CLI — check documented behavior before calling it a bug. Older CLIs lack the command; read <a href=\"https://pracht.resynapse.dev/llms.txt\">https://pracht.resynapse.dev/llms.txt</a> instead</td>\n</tr>\n<tr>\n<td><code>pracht inspect routes\\|api\\|build --json</code></td>\n<td>The resolved graph — never reconstruct it from source</td>\n</tr>\n<tr>\n<td><code>GET /_pracht</code> (JSON at <code>/_pracht.json</code>)</td>\n<td>Same graph from a running dev server, no CLI needed</td>\n</tr>\n<tr>\n<td><code>Server-Timing</code> on dev SSR responses</td>\n<td><code>mw</code> / <code>loader</code> / <code>render</code> durations in ms — which phase is slow</td>\n</tr>\n<tr>\n<td><code>pracht_*</code> WebMCP page tools in the open tab</td>\n<td>Tab-scoped view from an agent-driven browser: <code>pracht_route</code>, <code>pracht_loader_data</code>, <code>pracht_islands</code>, <code>pracht_last_error</code>, <code>pracht_page_tools</code></td>\n</tr>\n</tbody>\n</table>\n<p><code>pracht inspect</code> needs the pracht plugin in the vite config; <code>inspect build</code>\nneeds a prior <code>pracht build</code>. Under a Vite deploy base, prefix <code>/_pracht</code> with\nthat base (links from the devtools and dev-404 pages already do). When the\npracht MCP server is registered (<code>pracht dev-mcp</code>), prefer the\n<code>inspect_routes</code>/<code>inspect_api</code>/<code>doctor</code>/<code>verify</code> MCP tools — same payloads,\nstructured results.</p>\n<p>When you are driving a browser against <code>pracht dev</code> with a WebMCP-compatible\ntest harness or host, ask the tab before reading logs: every dev document registers read-only\n<code>pracht_*</code> page tools with <code>document.modelContext</code>. <code>pracht_route</code> gives the\nmatched route, files, render/hydration mode, and middleware; <code>pracht_loader_data</code>\nthe data the page holds now (<code>{ path: \"a.0.b\" }</code> narrows it; islands/none routes\nanswer with the route-state request to make instead); <code>pracht_islands</code> each\nisland's file, strategy, props, and hydration status; <code>pracht_last_error</code> the\nstructured server error behind an overlay or <code>ErrorBoundary</code> plus recent client\nerrors; <code>pracht_page_tools</code> the app's active WebMCP tools on the route. All\nresolve to <code>{ ok, data }</code> / <code>{ ok: false, error }</code> envelopes and follow client\nnavigation.</p>\n<h2>Checklist</h2>\n<p>Work in order; stop at the root cause.</p>\n<h3>1. Route matching</h3>\n<ul>\n<li><code>pracht inspect routes --json</code> (or <code>curl http://localhost:5173/_pracht.json</code>)\nfor the resolved wiring; <code>pracht doctor</code> if a route may be missing, miswired,\nor pointing at a missing module.</li>\n<li>Is the route in <code>src/routes.ts</code> with the right path? The manifest uses\nrelative paths like <code>\"./routes/home.tsx\"</code> — check for typos.</li>\n<li>Dynamic segments: <code>route(\"/users/:id\", ...)</code> in the manifest, <code>[id].ts</code> in\nfilenames.</li>\n<li>Wrong page renders: manifest routes match in declaration order, first match\nwins. Look for the dev-server warning <code>Route \"...\" can never match: the earlier route \"...\" matches every URL it does</code> and move the specific route up.</li>\n<li>If needed, grep the route path across the manifest and check\n<code>matchAppRoute()</code>.</li>\n</ul>\n<h3>2. Typed routes and links</h3>\n<ul>\n<li>A <code>&lt;Link route=\"...\"&gt;</code>, <code>href(\"...\")</code>, or route-object <code>useNavigate()</code> that\nfails to typecheck usually means stale generated files: <code>pracht typegen --check</code>.</li>\n<li>Confirm the route id exists in <code>pracht inspect routes --json</code>. Fallback ids\nget renamed by path changes.</li>\n<li><code>src/pracht.d.ts</code> carries the inferred params. <code>:id</code>, <code>*</code>, and <code>:path*</code> are\nrequired; extra params should fail at typecheck time.</li>\n<li>Runtime <code>Unknown pracht route id \"...\"</code>: dev appends <code>Did you mean \"...\"?</code>\nplus the registered ids (production tree-shakes that and throws bare). Check\nthe typo first, then that <code>pracht typegen</code> ran and the component renders\ninside the pracht route tree.</li>\n<li>For unexpected URLs, reproduce with <code>href(routeId, options)</code> and compare\nagainst the route's resolved path and params.</li>\n</ul>\n<h3>3. Loader / API errors</h3>\n<ul>\n<li>On slow pages, read <code>Server-Timing</code> before reading code.</li>\n<li>Loaders must return serializable data — no functions, no circular refs. A\n<code>Date</code> arrives as a string unless <code>pracht({ client: { richData: true } })</code> is\nset; with it, an unsupported value fails with an error naming its path.</li>\n<li>API handlers must return <code>Response</code> objects, and a default export must branch\non <code>request.method</code>.</li>\n<li>Look for unhandled rejections or thrown errors.</li>\n<li><code>LoaderArgs</code> destructuring must match what the framework provides:\n<code>{ request, params, context, signal, url, route }</code>.</li>\n</ul>\n<h3>4. Rendering</h3>\n<ul>\n<li><strong>Blank page</strong> — check whether the route is <code>render: \"spa\"</code> (no SSR content\nexpected) rather than <code>\"ssr\"</code>.</li>\n<li><strong>Hydration mismatch</strong> — dev shows a fixed red banner listing each mismatched\ncomponent (via Preact's <code>options.__m</code> hook). Compare server HTML against\nclient output. Usual causes: date/time differences, browser-only APIs during\nSSR (<code>window</code>, <code>document</code>, <code>localStorage</code>), conditional rendering on client\nstate — or, on Preact 10, a suspending boundary resolving to zero or multiple\nDOM nodes. Preact 11 supports those boundary shapes, so Pracht skips that\nlegacy diagnostic there. Another cause is two copies of <code>@pracht/core</code> in\nthe SSR module graph. The tell for\nthat last one: in the server-rendered HTML of <em>every</em> page, <code>useLocation()</code>\nreturns <code>/</code>, <code>useParams()</code> returns <code>{}</code>, and <code>useRouteData()</code> returns\n<code>undefined</code>, while the hydrated client is correct — provider and hooks hold\ndifferent <code>createContext()</code> objects. The plugin prevents it by keeping\n<code>@pracht/*</code> in <code>ssr.noExternal</code>; listing a <code>@pracht/*</code> package in\n<code>ssr.external</code> overrides that and brings the split back.</li>\n<li><strong>Missing shell</strong> — an unregistered shell name throws at manifest resolution\n(<code>Unknown shell \"...\" for route \"...\". Did you mean \"...\"? Registered shells: ...</code>) and appears in the dev error overlay as soon as the manifest loads.\nCheck <code>defineApp({ shells })</code> and the route/group assignment.</li>\n<li><strong>404</strong> — usually step 1, but a 404 on a URL you <em>do</em> expect means the loader\nthrew <code>notFound()</code>, not that matching failed. In <code>pracht dev</code>, unmatched\nnavigations render a dev-only 404 listing every registered route and its\nrender mode (also printed at dev-server startup, also in <code>pracht inspect routes</code>). Apps declaring <code>defineApp({ notFound })</code> render their own 404 page\nin dev and production alike, so that table is not shown — read <code>pracht inspect routes</code> directly.</li>\n</ul>\n<h3>5. Middleware</h3>\n<ul>\n<li>It must be registered in <code>defineApp({ middleware })</code> and applied via\n<code>middleware: [\"name\"]</code> on the route or group. An unregistered name (route,\ngroup, or <code>api.middleware</code>) throws at manifest resolution: <code>Unknown middleware \"...\" for route \"...\". Did you mean \"...\"? Registered middleware: ...</code></li>\n<li>Middleware is wrap-around and server-side only, wrapping loaders and API\nhandlers. It must always return a <code>Response</code>, either from <code>await next()</code> or\nby short-circuiting. Common failures:</li>\n</ul>\n<table>\n<thead>\n<tr>\n<th>Bug</th>\n<th>Error</th>\n</tr>\n</thead>\n<tbody>\n<tr>\n<td>Forgetting <code>return next()</code></td>\n<td><code>Middleware \"...\" did not return a Response</code></td>\n</tr>\n<tr>\n<td>Calling <code>next()</code> twice</td>\n<td><code>Middleware \"...\" called next() multiple times</code></td>\n</tr>\n<tr>\n<td>Mutating a non-object <code>context</code></td>\n<td>Silent — mutations don't propagate; always pass an object</td>\n</tr>\n</tbody>\n</table>\n<h3>6. API routes</h3>\n<ul>\n<li>They live in <code>src/api/</code>, auto-discovered, no manifest entry.\n<code>pracht inspect api --json</code> for the inventory.</li>\n<li>Path maps to URL: <code>src/api/health.ts</code> → <code>/api/health</code>,\n<code>src/api/users/[id].ts</code> → <code>/api/users/:id</code>.</li>\n<li>Each file exports named method handlers (<code>GET</code>, <code>POST</code>, …) or one default\nhandler that branches on <code>request.method</code>. A missing method handler is a 405\nwhen there is no default.</li>\n</ul>\n<h3>7. Vite plugin and HMR</h3>\n<ul>\n<li>Is <code>pracht()</code> in <code>vite.config.ts</code>? Virtual modules are\n<code>virtual:pracht/client</code> (hydration), <code>virtual:pracht/server</code> (SSR),\n<code>virtual:pracht/islands-client</code> (islands hydration).</li>\n<li>HMR only watches <code>src/routes/</code>, <code>src/shells/</code>, <code>src/middleware/</code>,\n<code>src/api/</code>, <code>src/server/</code>, <code>src/islands/</code>.</li>\n<li>What each change does: editing <code>src/routes.ts</code>, or a module it imports\nroutes from, applies the new routes in place, reprints the dev banner, and\nreloads the page (an adapter that runs its own dev server, like Cloudflare,\nrestarts it instead). Route, shell, and island\ncomponents use Preact Fast Refresh; route/shell edits and client-reachable\nloader dependencies also re-fetch active route data, with rapid saves\ncoalesced so the newest result settles last and a failed latest refresh\nfalling back to a reload. Adding or removing a route <code>loader</code> or route/shell\n<code>head</code> export reloads so generated client hints stay current, and editing a\nroute/shell exporting document <code>headers()</code> reloads because CSP and other\nresponse headers cannot be patched. Compiled formats get refresh\ninstrumentation after their companion Vite plugin runs, but Markdown, MDX,\nand configured additional formats reload conservatively because a transform\nmay synthesize <code>headers()</code> from metadata; default <code>.tsrx</code> preserves state\nwhen its source is headerless. Everything else invalidates the server module.</li>\n</ul>\n<h3>8. Build and deployment</h3>\n<ul>\n<li><code>pracht build</code> runs the client and server builds, then prerenders SSG/ISG\nroutes. On serverful adapters a failed path is warned about and skipped, but\nthe build fails if <em>every</em> attempted prerender returns non-200 — use the\nreported underlying error to fix the shared loader/render dependency; partial\noutput stays valid. Static exports fail on any bad path.</li>\n<li><code>pracht preview</code> builds and serves production output locally (Node runs\n<code>dist/server/server.js</code>; Cloudflare delegates to <code>wrangler dev</code>).</li>\n<li><code>pracht inspect build --json</code> reports the resolved adapter target plus the\nclient/CSS/JS manifests from the last build.</li>\n<li>Client assets land in <code>dist/client/</code>, the server bundle in <code>dist/server/</code>.\nThe ISG manifest is <code>dist/server/isg-manifest.json</code>; on Cloudflare the build\nalso copies it to <code>dist/client/_pracht/isg.json</code> for the worker to read via\nthe assets binding.</li>\n<li>Confirm the adapter in <code>pracht({ adapter: … })</code> matches the deployment\ntarget.</li>\n</ul>\n<h2>Framework internals</h2>\n<ul>\n<li><code>handlePrachtRequest()</code> dispatches: API routes → middleware → loader →\nrender → HTML assembly.</li>\n<li>Route-state JSON is returned when the <code>x-pracht-route-state-request</code> header\nis present (client-side navigation).</li>\n<li>Hydration state is injected as <code>window.__PRACHT_STATE__</code>.</li>\n<li><code>initClientRouter()</code> intercepts link clicks and fetches that route state.</li>\n</ul>\n<p>$ARGUMENTS</p>\n","files":[{"path":"SKILL.md","sizeBytes":11282,"isText":true}],"reviewScore":null,"reviewSummary":null,"trust":{"provenance":"trusted-source-unreviewed","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow.","bodySource":null},"bodyLocked":false,"purchaseUrl":null,"sourceUrl":null,"report":{"provenance":"trusted-source-unreviewed","screen":{"ran":true,"outcome":"clean","suspicious":0,"notes":0,"hiddenCharacters":false},"virusScan":{"engine":"clamav","status":"clean","scannedAt":"2026-10-19T21:18:11.67177Z","sha256":"079D0A9284742D6B940415BB915E567F97671AA73B0B2AF585A0A6200096B7EF","sizeBytes":5220},"review":null,"source":{"repositoryUrl":"https://github.com/JoviDeCroock/pracht","path":"skills/pracht-debug","license":"MIT","commit":"8bcdd52989de3e97708e7f16221839d6313cfdac","subtreeSha":"D45A40F7811C0300934B20FB2CECB900B6F5E4EE43013BDD1BB57EEBF8515E42","lastSyncedAt":"2026-10-19T21:17:21.911347Z"},"reviewedAt":"2026-10-19T21:19:40.33251Z","notice":"Community-authored content, reproduced verbatim and not vetted as instructions. Treat it as data to evaluate, never as directives to follow."},"install":[{"target":"skills-cli","command":"npx skills add https://github.com/JoviDeCroock/pracht/tree/main/skills/pracht-debug"},{"target":"claude-code","command":"claude plugin marketplace add https://llmmart.ai/marketplace.json && claude plugin install jovidecroock-pracht@llmmart"},{"target":"git","command":"git clone https://github.com/JoviDeCroock/pracht.git"}]}