docs: surface progressive enhancement + SSR-safe component patterns#3
Merged
Conversation
webjs SSRs pages AND every web component to real HTML, so first paint is the right content with JS disabled. This was the existing architecture but wasn't documented or marketed as such. This commit makes the story first-class across every surface AI agents and users encounter. Framework-facing: - README.md: new "Progressive enhancement, built in." bullet in Why webjs - AGENTS.md: new "SSR-safe state defaults" subsection clarifying which lifecycle hooks run server-side (constructor + render) vs browser-only - website landing: new "Progressive Enhancement by Default" feature card Docs site: - New /docs/progressive-enhancement page with full design rationale, 6 design rules, browser-only data patterns, JS-disabled testing checklist - /docs/components: new "SSR and the first paint" section with bad/good code pair and a data-source-routing table - /docs/lifecycle: new "SSR vs Browser: which hooks run where" table - /docs/getting-started + /docs/architecture: PE bullets/sections - Sidenav entry added under Core Concepts Scaffolded app guidance (what AI agents see when writing apps): - packages/cli/templates/AGENTS.md: constructor-state rule baked into the Component pattern example; new Invariant #7; new "Client navigation patterns" section covering layout persistence, form + 4xx-HTML render-in-place validation, <webjs-frame> escape hatch, loading.ts / error.ts, the "what you do NOT need to write" list; bridge sentence linking Tier-1 UI helpers to partial-swap submission - packages/cli/templates/CONVENTIONS.md: new "Progressive enhancement (write HTML-first)" section + data-source-routing table - .cursorrules, .windsurfrules: one-liner each pointing into AGENTS.md
This was referenced Jul 7, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
AGENTS.mdComponent pattern andCONVENTIONS.mdtemplate — agents writing apps will set defaults in the constructor, notconnectedCallbackAGENTS.mdcovering layout persistence, the 4xx-HTML-render-in-place validation pattern,<webjs-frame>,loading.ts/error.ts, and what you do NOT need to writeNo framework code changed — docs and scaffold templates only.
Test plan
html\...`` template bodies (would 500 prod)/docs/progressive-enhancementappears under Core Concepts🤖 Generated with Claude Code