docs: comprehensive documentation audit, fixes, and website improvements by bartlomieju · Pull Request #3712 · freshframework/fresh

bartlomieju · 2026-03-28T07:22:07Z

Summary

Full documentation audit and fixes for Fresh 2.x docs. Addresses every issue identified in the audit report.

Critical fixes

Remove 4 TODO placeholders (app.md, plugins/index.md)
Fix 4 broken code examples (layouts syntax error, routing missing ctx, csrf wrong import, getting-started unused prop)
Fix 3 copy-pasted frontmatter descriptions (context, env-vars, app)
Fix CSRF page describing CORS instead of CSRF

New pages (8)

Architecture — request lifecycle diagram, server-first rendering, islands architecture
Data Fetching — handlers, page(), type-safe data passing, async components, PageProps reference
Signals — useSignal, computed, props, shared state, serialization
Serialization — supported types, what can't be serialized, circular refs, pitfalls
API Routes — handler-only routes, method-specific, catch-all, programmatic
Common Patterns — protected routes, redirects, cookies, WebSockets, streaming, content negotiation, subdomain routing, proxying, lazy-loading islands
API Reference — all exports from fresh, fresh/runtime, fresh/dev
OpenTelemetry — what's instrumented, enabling tracing, Deno Deploy

Expanded pages (6)

Routing — matching priority, HTTP methods, HEAD fallback, file-based handlers
Vite plugin — HMR, plugin composition, internals, debugging
Deno Deploy — build config, env vars, custom domains, troubleshooting
deno compile — cross-compilation, limitations
Error handling — expanded HttpError with message param, import paths
Plugins index — plugin authoring guidance, built-in plugin list

Structural improvements

Update all 3 index pages (concepts, advanced, examples) with links to every sub-page
Cross-link the two Layouts pages (file-based vs programmatic)
Resolve contradictory build commands (remove legacy dev.ts references)
Add "next steps" to Getting Started
Explain (_islands) and (_components) directories in file routing
Document basePath, assetSrcSet(), IS_BROWSER, route css option
Add PR guidelines to Contributing page
Add Deno version requirements to Introduction

Docs fixes from issue triage

Docker deployment — add missing deno install --allow-scripts step, remove stale deno cache, fix CMD (Outdated docs for Docker and/or with DaisyUI. #3500)
Deployment index — add install step before build (Outdated docs for Docker and/or with DaisyUI. #3500)
Static files — add tip about root-relative URLs (Images not shown as expected after build Fresh project #3482), add image optimization section with vite-imagetools, CDN services, best practices (Add an image optimization example to docs #671)
main.ts vs main.tsx — fix examples showing JSX in main.ts, add tip about serverEntry config (Docs: Is it main.ts or main.tsx #3476)
Head component — clarify dedup precedence: last-rendered wins (Documentation on duplicate tags in <Head> is unclear #2749)
Islands — add custom elements / web components section (Add Example of How to Use Custom Elements in Fresh #2741)
Sharing state — rewrite cart example to avoid shared module-level signals (Docs: Change cart example to not used shared signals #2437, Docs: Update sharing state example #1877)
Common patterns — add subdomain routing (Subdomain routing #603), proxying requests (Docs for proxying requests under a route #361), lazy-loading islands (Feature: Lazyload islands components in the client side #565)

Website fixes

Canary redirects — catch-all /docs/canary/... → /docs/... redirect (docs: add redirects for canary -> latest #3375)
Recipe partials — redirect direct access to recipe routes to homepage (Homepage partials example gets weird with the refresh button. #2559)
Homepage — add progressive complexity code examples to Simple section (An untapped marketing advantage for Fresh: progressive complexity? #2755)

Image reference fixes

Rename getting-started-3-cotuntdown.png → getting-started-3-countdown.png
Fix 1.x partials image path

Grammar/typos

11 corrections across 12 files

CI

Add docs/check_images_test.ts — verifies all markdown image references resolve to existing files in www/static/

Test plan

Verify new pages render correctly on the docs site
Check TOC changes in docs/toc.ts produce correct navigation
Verify internal links between pages resolve
Run deno test -A docs/check_images_test.ts
Review code examples against current Fresh 2.x API

Closes #3514
Closes #3476
Closes #3591
Closes #2876
Closes #2075
Closes #1612
Closes #1535
Closes #527
Closes #3059
Closes #3695
Closes #3548
Closes #3500
Closes #3482
Closes #3375
Closes #2749
Closes #2741
Closes #2559
Closes #2437
Closes #671
Closes #361

🤖 Generated with Claude Code

Fill in documentation for `.route()`, `.onError()` route, and `.notFound()` route examples in concepts/app.md. Replace TODO in plugins/index.md with a list of built-in plugins. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Fix syntax error in concepts/layouts.md (missing parens around arrow fn params) - Add missing `ctx` parameter in concepts/routing.md blog handler - Fix wrong import `app` -> `App` in plugins/csrf.md - Remove unused `target` prop from Countdown example in getting-started Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- concepts/app.md: was "Add a global app wrapper..." (from app-wrapper page) - concepts/context.md: was "Plugins can add..." (from plugins page) - advanced/environment-variables.md: was "Error pages can be used..." (from error-handling page) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The CSRF plugin page had copy-pasted text describing CORS behavior ("which origins...is permitted to load resources from"). Replaced with an accurate description of CSRF protection mechanics. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- "it's subfolders" -> "its subfolders" (middleware.md) - "other's like" -> "others like" (define.md) - "than this is likely" -> "then this is likely" (troubleshooting.md) - "as well has collect" -> "as well as collect" (deno-deploy.md) - "the the correct" -> "the correct" (cloudflare-workers.md) - "host name number" -> "host name" (deno-compile.md) - "While this generally desired" -> "While this is generally desired" (rendering-raw-html.md) - "If can't update" -> "If you can't update" (builder.md) - Missing closing quotes in code comments (context.md, app.md) - Image filename typo "cotuntdown" -> "countdown" (getting-started) - "_layout_.tsx" -> "_layout.tsx" (layouts.md) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The advanced section index was a single sentence with no links to its sub-pages. Added a complete list of all advanced topics with brief descriptions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The routing page was ~100 words with only basic examples (one broken). Now covers route matching priority (static-first, then registration order), HTTP method handlers, HEAD fallback behavior, and file-based route handler patterns. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…nals The Vite page was ~100 words showing only the config options. Now explains what the plugin does (JSX, aliasing, HMR, code splitting), how to add other Vite plugins alongside Fresh, how HMR works, and debugging tips. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Signals are a core reactivity feature with zero dedicated documentation. New page covers: creating signals with useSignal, computed signals, passing signals as island props, shared state via module-level signals, and serialization behavior. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Handler-only routes (JSON APIs) are a very common pattern with no documentation. New page covers: basic JSON responses, method-specific handlers with 405 fallback, catch-all handlers, and programmatic routes. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

There are two layout docs (file-based in concepts/, programmatic in advanced/) with no cross-references. Added a note at the top of each page pointing to the other with a clear distinction. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The deployment index listed both 'deno task build' and the legacy 'deno run -A dev.ts build'. The latter was removed by the Fresh 2 migration (dev.ts is replaced by vite.config.ts). Now shows only the current command with a note linking to the migration guide. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Deno Deploy page was 4 numbered steps (~70 words). Now covers build step configuration, environment variables, custom domains, and troubleshooting. deno compile page was ~80 words. Now covers cross-compilation, the --include flag, and known limitations. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fresh 1.x had a dedicated data fetching page that was dropped in 2.x. New page covers: handler-to-component data flow with page(), type-safe data passing with define.handlers/define.page, async page components, middleware state, response customization, and a PageProps reference table. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Documents what types can be passed as island props, what cannot be serialized (functions, class instances, symbols), circular reference handling, signal serialization mechanics, and common pitfalls like large props and accidental non-serializable values. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Collects frequently-needed patterns in one place: protected routes, URL redirects, content negotiation, cookies, query parameters, response headers, streaming, WebSockets, and timing middleware. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fresh 1.x had a dedicated architecture page that was dropped in 2.x. New page includes an ASCII request flow diagram covering static files, middleware chain, routing, handlers, layouts, page rendering, and island hydration. Also explains server-first rendering, islands architecture, middleware onion pattern, layout inheritance, and build/deploy flow. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- islands.md: fix "route/index.tsx" typo -> "routes/index.tsx" - middleware.md: add missing csp() to included middlewares list, fix trailingSlash -> trailingSlashes - layouts.md: fix line 88 using define.layout() for a page example -> define.page() - migration-guide.md: add missing ctx parameter in ctx.render() example - markdown.md: remove unused CONTENT variable, fix step numbering (3 not 4) - builder.md: fix inconsistent tailwind() args (remove extra app param) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Was missing Architecture, Data Fetching, Signals, Static Files, and File Routing links. Now lists every concept sub-page with descriptions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The getting started page ended abruptly after the Countdown example with no guidance on where to go next. Added links to routing, data fetching, islands, middleware, and architecture. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

These directories were shown in the project structure tree but never explained. Added a section describing what each does and why the parentheses matter. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- static-files.md: add assetSrcSet() usage example - error-handling.md: expand HttpError docs with message param, import path, and browser availability - app.md: add Configuration section documenting basePath option - islands.md: clarify IS_BROWSER import and behavior Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Manual reference covering all exports from fresh, fresh/runtime, and fresh/dev entry points. Each export includes its kind (class, function, component, constant, type) and links to the relevant docs page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- examples/index.md: add API Routes and Common Patterns to listing, match order to TOC - migration-guide.md: fix awkward phrasing "automatically update like" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The introduction had no mention of what Deno version is needed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The audit noted there was no explanation of how to create custom plugins. Added a "Creating reusable plugins" section showing how to export a middleware function as a reusable plugin. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Fresh has built-in OTel instrumentation listed as a feature in the introduction but with no dedicated documentation. New page covers what's instrumented, how to enable tracing with Deno's built-in OTel support, and the Deno Deploy integration. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The audit noted the contributing page could use PR submission guidelines. Added a section covering deno task ok, focused PRs, test expectations, and code style. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

The RouteConfig css option for loading per-route CSS files was undocumented. Added an example alongside the existing routeOverride section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Shows how to register and use custom elements and third-party web component libraries inside Fresh islands. Closes #2741 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

When recipe partial routes are accessed directly (not as a partial request), redirect to /#partials instead of serving raw HTML fragments. Closes #2559 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Module-level signals are shared across all server requests, causing state leaks between users. Rewrote the cart example to create signals per-render and pass them as props, with a warning about the pitfall. Closes #2437 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Covers build-time optimization with vite-imagetools, CDN image services, and best practices for responsive images. Closes #671 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Subdomain routing via middleware + URLPattern (ref #603) - Proxying requests to upstream servers (closes #361) - Lazy-loading island content with Preact lazy() + Suspense (ref #565) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

ctx.render() requires a vnode argument; use page() to delegate rendering to the default page export instead. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

…hecker - Add layouts page to concepts section in TOC (file existed but wasn't registered) - Exclude GitHub edit URLs from link checker to avoid 429 rate limiting Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

1. Fix handlers → handler (singular) in app.route() example 2. Fix app.onError() missing path argument 3. Fix css shown inside RouteConfig → top-level export 4. Fix variable shadowing (page shadows page() import) 5. Fix ctx.redirect() in page component → move to handler 6-8. Add missing HttpError and define imports in examples 9. Add config and info to PageProps reference table 10. Add RouteData, Lazy, MaybeLazy, ResolvedBuildConfig to API reference 11. Clarify layout nesting order in architecture docs 12. Add note explaining useSignal in server-rendered route for signals Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

- Fix app.onError() missing path arg in error-handling.md - Add missing HttpError import in error-handling.md - Add missing define imports in WebSocket, subdomain, timing examples - Standardize on `handler` (singular) for all export names - Convert all untyped middleware to define.middleware() Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

crowlKats · 2026-03-28T11:46:55Z

+| `assetSrcSet` | Function  | Apply `asset()` to all URLs in a `srcset` string.                                              |
+| `Partial`     | Component | Mark a region for partial updates. See [Partials](/docs/advanced/partials).                    |
+| `Head`        | Component | Add elements to the document `<head>`. See [Modifying head](/docs/advanced/head).              |
+| `HttpError`   | Class     | HTTP error class (re-exported from `fresh`).                                                   |


just tested on JSR repo, this doesnt seem to be available in fresh/runtime?
Ideally it is (needed for making jsr-io/jsr#1352 landable)

I think it's just not released yet: #3080

It should be part of2.2.2 release... I'll check what's going on

It's here http://jsr.io/@fresh/core@2.2.2/doc/~/HttpError

The ASCII art request lifecycle diagram had broken box alignment. Replace it with an inline HTML/CSS flowchart that renders cleanly. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

bartlomieju · 2026-03-28T14:56:41Z

Note: #3706 should land first.

…hitecture - Replace em dashes with hyphens across all changed docs - Add ~49 cross-links between doc pages for better discoverability - Restore JSX example on introduction page, remove Requirements section - Rework "Where to host" section, add AI agent mention to "When to use" - Expand scoped middleware description in architecture diagram Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Replace `deno run -Ar jsr:@fresh/init` with `deno create @fresh/init` across docs, READMEs, homepage, and init help text. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

bartlomieju and others added 30 commits March 27, 2026 19:59

docs: add navigation links to advanced index page

066622c

The advanced section index was a single sentence with no links to its sub-pages. Added a complete list of all advanced topics with brief descriptions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: update concepts index with all sub-pages

033022a

Was missing Architecture, Data Fetching, Signals, Static Files, and File Routing links. Now lists every concept sub-page with descriptions. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: update examples index and fix migration guide grammar

ebf194e

- examples/index.md: add API Routes and Common Patterns to listing, match order to TOC - migration-guide.md: fix awkward phrasing "automatically update like" Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fmt

025b3c6

docs: add Deno version requirements to introduction

5b8af4c

The introduction had no mention of what Deno version is needed. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: add PR guidelines to contributing page

3adb4cc

The audit noted the contributing page could use PR submission guidelines. Added a section covering deno task ok, focused PRs, test expectations, and code style. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

docs: document route css option in file routing

715a0fe

The RouteConfig css option for loading per-route CSS files was undocumented. Added an example alongside the existing routeOverride section. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

bartlomieju and others added 3 commits March 28, 2026 10:50

docs: add custom elements (web components) section to islands docs

6e1f660

Shows how to register and use custom elements and third-party web component libraries inside Fresh islands. Closes #2741 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: redirect direct access to recipe partial routes to homepage

badf670

When recipe partial routes are accessed directly (not as a partial request), redirect to /#partials instead of serving raw HTML fragments. Closes #2559 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

This was referenced Mar 28, 2026

Docs: Update sharing state example #1877

Closed

Add examples of Fresh "with-x-library" with the goal to drive adoption #712

Closed

bartlomieju and others added 4 commits March 28, 2026 11:12

docs: add image optimization section to static files docs

1b9e184

Covers build-time optimization with vite-imagetools, CDN image services, and best practices for responsive images. Closes #671 Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

chore: format docs

0e07166

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fix: use page() instead of ctx.render() in recipe partial routes

cfad1d8

ctx.render() requires a vnode argument; use page() to delegate rendering to the default page export instead. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

bartlomieju changed the title ~~docs: comprehensive documentation audit and fixes~~ docs: comprehensive documentation audit, fixes, and website improvements Mar 28, 2026

bartlomieju and others added 2 commits March 28, 2026 11:34

This comment was marked as off-topic.

Sign in to view

csvn reviewed Mar 28, 2026

View reviewed changes

Comment thread docs/latest/advanced/api-reference.md

bartlomieju and others added 2 commits March 28, 2026 12:00

docs: link to JSR auto-generated API docs

cb01272

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

crowlKats reviewed Mar 28, 2026

View reviewed changes

Comment thread docs/latest/concepts/architecture.md Outdated

docs: replace ASCII art with HTML/CSS flowchart in architecture page

1614706

The ASCII art request lifecycle diagram had broken box alignment. Replace it with an inline HTML/CSS flowchart that renders cleanly. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

crowlKats approved these changes Mar 28, 2026

View reviewed changes

csvn mentioned this pull request Mar 28, 2026

feat: support deno create for project initialization #3706

Merged

3 tasks

bartlomieju and others added 3 commits March 28, 2026 16:24

docs: update init command to use deno create

4af0d2c

Replace `deno run -Ar jsr:@fresh/init` with `deno create @fresh/init` across docs, READMEs, homepage, and init help text. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

fmt

b560aa8

bartlomieju enabled auto-merge (squash) March 29, 2026 18:08

bartlomieju added 2 commits March 29, 2026 20:11

reset CI

e136a75

fix link

d91adac

bartlomieju merged commit 103427f into main Mar 29, 2026
9 checks passed

bartlomieju deleted the docs/quick-wins-audit-fixes branch March 29, 2026 18:22

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

docs: comprehensive documentation audit, fixes, and website improvements#3712

docs: comprehensive documentation audit, fixes, and website improvements#3712
bartlomieju merged 60 commits into
mainfrom
docs/quick-wins-audit-fixes

bartlomieju commented Mar 28, 2026 •

edited

Loading

Uh oh!

This comment was marked as off-topic.

Uh oh!

Uh oh!

crowlKats Mar 28, 2026 •

edited

Loading

Uh oh!

csvn Mar 28, 2026

Uh oh!

bartlomieju Mar 28, 2026

Uh oh!

bartlomieju Mar 28, 2026

Uh oh!

Uh oh!

bartlomieju commented Mar 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

bartlomieju commented Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Critical fixes

New pages (8)

Expanded pages (6)

Structural improvements

Docs fixes from issue triage

Website fixes

Image reference fixes

Grammar/typos

CI

Test plan

Uh oh!

This comment was marked as off-topic.

Uh oh!

Uh oh!

crowlKats Mar 28, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

csvn Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

bartlomieju Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

bartlomieju Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

bartlomieju commented Mar 28, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

bartlomieju commented Mar 28, 2026 •

edited

Loading

crowlKats Mar 28, 2026 •

edited

Loading