fresh-dev

One-screen overview of the Fresh project — version, routes, islands, boundary violations and validator summary, with next steps. Read-only. Arg: --full to force a reindex, merge deno lint and deno check, and export the graph for livespec.

Diagnose a Fresh symptom or URL — 404s, dead islands, hydration, styles, stale manifest — with fresh_trace, fresh_islands and fresh_validate, then report the cause and the minimal fix without editing. Arg: the symptom or URL.

The anatomy of a Deno Fresh project per version and flavor (1.x manifest, 2.x Vite, 2.x builder): what each top-level file does, the detection signals, where new code belongs, the server/client boundary model, import-map and compiler settings, and how to diagnose (not perform) a 1.x to 2.x migration. Use when editing deno.json, main.ts, dev.ts, vite.config.ts, fresh.config.ts or fresh.gen.ts, when deciding where a new module lives, when a project mixes $fresh/ and @fresh/core, or when a task mentions upgrading Fresh, Vite, the import map, jsx precompile or nodeModulesDir. Query fresh_project and fresh_boundaries first.

How to add or change a server-rendered component in a Deno Fresh project (1.x and 2.x): reuse before creating, where a component shared by islands and routes may live, the shared boundary, composition instead of a monolithic route, and why a component in components/ has no state or event handlers. Use when editing components/**, when a task asks for a new UI piece, section, card, header or layout fragment, or when a route file has grown into one large JSX block. Query fresh_components and fresh_usages before creating anything.

How data moves through a Deno Fresh request (1.x and 2.x): handler to page (ctx.render(data) versus page(data) and define.page<typeof handler>), page to island props and what serializes, ctx.state set by middleware, forms with POST and redirects, not-found and error responses, and partials. Use when a page needs data, a form must be handled, an island receives the wrong props, ctx.state is undefined, or a task mentions handlers, PageProps, loaders, fetch in a route, or form submission. Query fresh_route and fresh_islands before editing.

A symptom-to-diagnosis tree for Deno Fresh projects (1.x and 2.x): a URL that returns 404 or hits the wrong file, an island that is not interactive, hydration errors, styles not applied, a stale fresh.gen.ts, startup errors about handlers or exports, missing ctx.state or page data, and type or module-not-found errors. Use when a user reports "route 404", "island not interactive", "button does nothing", "hydration", "styles not applied", "Deno is not defined", "AddrInUse", "Could not find relevant exports" or "Route conflict detected". Read-only: it never edits.

The working loop for any change in a Deno Fresh project (1.x or 2.x): find the route, the components and islands it renders, its dependencies and the server/client boundary, reuse an existing pattern, make the minimal change, validate. Load it before the first edit under routes/, islands/, components/ or deno.json, whenever a task mentions Fresh, Preact islands, deno.json, $fresh/, @fresh/core or a fresh_* tool, and when writing a brief for a vise subagent that will touch a Fresh repo. It also settles what the LSP, the fresh_* tools and deno check each answer.

When something in a Deno Fresh project must be an island and how to build one that hydrates: serializable props per version, the client closure an island drags into the bundle, nested islands, signals versus hooks, IS_BROWSER guards, and why an onClick in components/ or routes/ never fires. Use when adding or changing interactivity, editing islands/** or a (_islands)/ folder, or when a button, form, counter or hook does nothing in the browser. Query fresh_islands and fresh_boundaries before editing.

How middleware composes in a Deno Fresh project (1.x and 2.x): root-to-leaf order of _middleware.ts files, 2.x app.use() globals in main.ts and the position of staticFiles(), ctx.next(), typed ctx.state, the 2.x built-ins (cors, csrf, csp, ipFilter, trailingSlashes), error routes, and the export shapes each version accepts. Use when editing routes/**/_middleware.ts or main.ts, adding auth, logging, CORS or CSRF, or when a middleware does not run, runs twice, or runs for static files. Query fresh_trace and fresh_routes(kind="middleware") before editing.

How to reason about routes in a Deno Fresh project (1.x and 2.x): file name to URL pattern, static-over-dynamic precedence, route groups, routeOverride, _layout and _middleware scope, API routes versus pages, and the handler export shape each version accepts. Use when adding, moving, renaming or debugging anything under routes/, when a URL returns 404 or hits the wrong file, or when a task mentions a route, endpoint, page, [slug], catch-all or route group. Query fresh_routes, fresh_route and fresh_trace before editing.

Fresh-aware impact of a change — routes, islands, layouts and middleware affected, plus the checks to run. Args: files or a git ref.

Detect the Fresh project, build the fresh-dev index, and propose the vise, livespec and gitignore snippets that wire fresh-dev into its neighbours. Proposes only; writes nothing without an explicit yes. Arg: optional workspace path.

Route table of the Fresh project (pattern, kind, methods, layouts, middleware, islands) filtered by prefix or kind, or the trace of one URL to the route and chain that serve it. Read-only.

Run the fresh-dev structural validators (routes, islands, boundaries, dependencies, conventions), print findings grouped by severity, and end with ok or not ok plus the equivalent CI command. Args: categories, and --deno to merge deno lint and deno check.