Pracht Debug

Iron law: no fixes without root-cause investigation first. Read the relevant source before diagnosing, start from the most likely cause for the symptom rather than a full audit, and when you find the root cause explain why it breaks. After fixing, prove the fix — run the test, check the dev server. Never say "this should fix it."

Instruments

Reach for these before deep manual inspection:

Tool	Use
pracht verify (--changed to scope to git-changed files)	Fast confidence check
pracht doctor	Broader broken wiring or missing files
pracht docs <topic> / pracht docs --search <query>	Docs bundled with the installed CLI — check documented behavior before calling it a bug. Older CLIs lack the command; read https://pracht.resynapse.dev/llms.txt instead
pracht inspect routes|api|build --json	The resolved graph — never reconstruct it from source
GET /_pracht (JSON at /_pracht.json)	Same graph from a running dev server, no CLI needed
Server-Timing on dev SSR responses	mw / loader / render durations in ms — which phase is slow
pracht_* WebMCP page tools in the open tab	Tab-scoped view from an agent-driven browser: pracht_route, pracht_loader_data, pracht_islands, pracht_last_error, pracht_page_tools

pracht inspect needs the pracht plugin in the vite config; inspect build needs a prior pracht build. Under a Vite deploy base, prefix /_pracht with that base (links from the devtools and dev-404 pages already do). When the pracht MCP server is registered (pracht dev-mcp), prefer the inspect_routes/inspect_api/doctor/verify MCP tools — same payloads, structured results.

When you are driving a browser against pracht dev with a WebMCP-compatible test harness or host, ask the tab before reading logs: every dev document registers read-only pracht_* page tools with document.modelContext. pracht_route gives the matched route, files, render/hydration mode, and middleware; pracht_loader_data the data the page holds now ({ path: "a.0.b" } narrows it; islands/none routes answer with the route-state request to make instead); pracht_islands each island's file, strategy, props, and hydration status; pracht_last_error the structured server error behind an overlay or ErrorBoundary plus recent client errors; pracht_page_tools the app's active WebMCP tools on the route. All resolve to { ok, data } / { ok: false, error } envelopes and follow client navigation.

Checklist

Work in order; stop at the root cause.

1. Route matching

• pracht inspect routes --json (or curl http://localhost:5173/_pracht.json) for the resolved wiring; pracht doctor if a route may be missing, miswired, or pointing at a missing module.
• Is the route in src/routes.ts with the right path? The manifest uses relative paths like "./routes/home.tsx" — check for typos.
• Dynamic segments: route("/users/:id", ...) in the manifest, [id].ts in filenames.
• Wrong page renders: manifest routes match in declaration order, first match wins. Look for the dev-server warning Route "..." can never match: the earlier route "..." matches every URL it does and move the specific route up.
• If needed, grep the route path across the manifest and check matchAppRoute().

2. Typed routes and links

• A <Link route="...">, href("..."), or route-object useNavigate() that fails to typecheck usually means stale generated files: pracht typegen --check.
• Confirm the route id exists in pracht inspect routes --json. Fallback ids get renamed by path changes.
• src/pracht.d.ts carries the inferred params. :id, *, and :path* are required; extra params should fail at typecheck time.
• Runtime Unknown pracht route id "...": dev appends Did you mean "..."? plus the registered ids (production tree-shakes that and throws bare). Check the typo first, then that pracht typegen ran and the component renders inside the pracht route tree.
• For unexpected URLs, reproduce with href(routeId, options) and compare against the route's resolved path and params.

3. Loader / API errors

• On slow pages, read Server-Timing before reading code.
• Loaders must return serializable data — no functions, no circular refs. A Date arrives as a string unless pracht({ client: { richData: true } }) is set; with it, an unsupported value fails with an error naming its path.
• API handlers must return Response objects, and a default export must branch on request.method.
• Look for unhandled rejections or thrown errors.
• LoaderArgs destructuring must match what the framework provides: { request, params, context, signal, url, route }.

4. Rendering

• Blank page — check whether the route is render: "spa" (no SSR content expected) rather than "ssr".
• Hydration mismatch — dev shows a fixed red banner listing each mismatched component (via Preact's options.__m hook). Compare server HTML against client output. Usual causes: date/time differences, browser-only APIs during SSR (window, document, localStorage), conditional rendering on client state — or, on Preact 10, a suspending boundary resolving to zero or multiple DOM nodes. Preact 11 supports those boundary shapes, so Pracht skips that legacy diagnostic there. Another cause is two copies of @pracht/core in the SSR module graph. The tell for that last one: in the server-rendered HTML of every page, useLocation() returns /, useParams() returns {}, and useRouteData() returns undefined, while the hydrated client is correct — provider and hooks hold different createContext() objects. The plugin prevents it by keeping @pracht/* in ssr.noExternal; listing a @pracht/* package in ssr.external overrides that and brings the split back.
• Missing shell — an unregistered shell name throws at manifest resolution (Unknown shell "..." for route "...". Did you mean "..."? Registered shells: ...) and appears in the dev error overlay as soon as the manifest loads. Check defineApp({ shells }) and the route/group assignment.
• 404 — usually step 1, but a 404 on a URL you do expect means the loader threw notFound(), not that matching failed. In pracht dev, unmatched navigations render a dev-only 404 listing every registered route and its render mode (also printed at dev-server startup, also in pracht inspect routes). Apps declaring defineApp({ notFound }) render their own 404 page in dev and production alike, so that table is not shown — read pracht inspect routes directly.

5. Middleware

• It must be registered in defineApp({ middleware }) and applied via middleware: ["name"] on the route or group. An unregistered name (route, group, or api.middleware) throws at manifest resolution: Unknown middleware "..." for route "...". Did you mean "..."? Registered middleware: ...
• Middleware is wrap-around and server-side only, wrapping loaders and API handlers. It must always return a Response, either from await next() or by short-circuiting. Common failures:

Bug	Error
Forgetting return next()	Middleware "..." did not return a Response
Calling next() twice	Middleware "..." called next() multiple times
Mutating a non-object context	Silent — mutations don't propagate; always pass an object

6. API routes

• They live in src/api/, auto-discovered, no manifest entry. pracht inspect api --json for the inventory.
• Path maps to URL: src/api/health.ts → /api/health, src/api/users/[id].ts → /api/users/:id.
• Each file exports named method handlers (GET, POST, …) or one default handler that branches on request.method. A missing method handler is a 405 when there is no default.

7. Vite plugin and HMR

• Is pracht() in vite.config.ts? Virtual modules are virtual:pracht/client (hydration), virtual:pracht/server (SSR), virtual:pracht/islands-client (islands hydration).
• HMR only watches src/routes/, src/shells/, src/middleware/, src/api/, src/server/, src/islands/.
• What each change does: editing src/routes.ts, or a module it imports routes from, applies the new routes in place, reprints the dev banner, and reloads the page (an adapter that runs its own dev server, like Cloudflare, restarts it instead). Route, shell, and island components use Preact Fast Refresh; route/shell edits and client-reachable loader dependencies also re-fetch active route data, with rapid saves coalesced so the newest result settles last and a failed latest refresh falling back to a reload. Adding or removing a route loader or route/shell head export reloads so generated client hints stay current, and editing a route/shell exporting document headers() reloads because CSP and other response headers cannot be patched. Compiled formats get refresh instrumentation after their companion Vite plugin runs, but Markdown, MDX, and configured additional formats reload conservatively because a transform may synthesize headers() from metadata; default .tsrx preserves state when its source is headerless. Everything else invalidates the server module.

8. Build and deployment

• pracht build runs the client and server builds, then prerenders SSG/ISG routes. On serverful adapters a failed path is warned about and skipped, but the build fails if every attempted prerender returns non-200 — use the reported underlying error to fix the shared loader/render dependency; partial output stays valid. Static exports fail on any bad path.
• pracht preview builds and serves production output locally (Node runs dist/server/server.js; Cloudflare delegates to wrangler dev).
• pracht inspect build --json reports the resolved adapter target plus the client/CSS/JS manifests from the last build.
• Client assets land in dist/client/, the server bundle in dist/server/. The ISG manifest is dist/server/isg-manifest.json; on Cloudflare the build also copies it to dist/client/_pracht/isg.json for the worker to read via the assets binding.
• Confirm the adapter in pracht({ adapter: … }) matches the deployment target.

Framework internals

• handlePrachtRequest() dispatches: API routes → middleware → loader → render → HTML assembly.
• Route-state JSON is returned when the x-pracht-route-state-request header is present (client-side navigation).
• Hydration state is injected as window.__PRACHT_STATE__.
• initClientRouter() intercepts link clicks and fetches that route state.

$ARGUMENTS