feat(ServerComponent): add method to render simplified html #1072

LeoMcA · 2025-11-11T17:19:51Z

Description

Adds a renderSimple method to the server component class, which can be overwritten in a component to define a simplified HTML version of the component
Does this for the Doc component to render simply the page contents, no sidebars etc.
Doesn't render the outer layout either

Motivation

Main motivation is to provide a better API than the hacky one used in feat: add get-doc tool mcp#10
- With the renderSimple export in entry.ssr.js I don't have to set up async local storage, mock fluent, etc.
- Will also easily allow us to define simple forms of other components, e.g. Baseline or BCD, rather than maintaining a custom implementation divorced from the "real" component
This could also prove useful for other purposes we might want to explore in the future: an alternative offline option, embedding in devtools, etc.

Testing

For a preview of the simple form of a component, run:

FRED_SIMPLE_HTML=true npm start

And then navigate directly to a doc page (other page types will render nothing), e.g. http://localhost:3000/en-US/docs/Web/JavaScript/Reference/Global_Objects/Number/isSafeInteger

Screenshot

github-actions · 2025-11-11T17:23:56Z

b65d50c was deployed to: https://fred-pr1072.review.mdn.allizom.net/

caugner

Could we avoid renderSimple() if an environment variable just caused this effect?

components/doc/server.js

components/reference-layout/server.js

build/server-worker.js

caugner · 2025-11-13T10:59:50Z

components/outer-layout/server.js

  render(context, markup) {
    const asyncStore = asyncLocalStorage.getStore();
-    if (!asyncStore) {
+    if (!asyncStore || "renderSimple" in asyncStore) {


Why would renderSimple end up in asyncStore?

It wouldn't in the outer layout, since we don't call it from the renderSimple root function: this is simply to make typescript happy.

I realize that I don't fully understand what asyncLocalStorage holds.

I looked at https://github.com/mdn/fred/blob/22628366e1b9ecc0d8f36811492c5a6f08e62db4/components/server/async-local-storage.js and it doesn't have any information, it just creates an instance of AsyncLocalStorage without any semantic notion of what it contains.

It is not clear to me why "renderSimple" in asyncStore implies that asyncLocalStorage is missing. It would probably be better to throw a separate error in this case, because if asyncStore is truthy, it's apparently not missing.

Yeah it's a little bit esoteric: the top level render methods (in entry.ssr.js) populate it. I'll add a jsdoc comment or similar to explain what's going on, and point back to there.

Agreed on the error, that was just me being a little lazy.

Added a comment, and realised the name of AsyncLocalStorageContents may have seemed a little "official" - like it was coming from node itself - rather than something we had defined so renamed it, in 198df40 (#1072)

LeoMcA

Could we avoid renderSimple() if an environment variable just caused this effect?

Hmm, let me think about this: I think though it would make the component code more complex, and I think there's a nice simplicity to just having two render methods on components which need them.

components/doc/server.js

LeoMcA · 2025-11-13T11:14:26Z

components/outer-layout/server.js

  render(context, markup) {
    const asyncStore = asyncLocalStorage.getStore();
-    if (!asyncStore) {
+    if (!asyncStore || "renderSimple" in asyncStore) {


It wouldn't in the outer layout, since we don't call it from the renderSimple root function: this is simply to make typescript happy.

components/reference-layout/server.js

caugner

LGTM overall, just three more nits:

Should the method be called renderSimplified() or renderMinimal() to make it clearer what this method does.
Can we mention this in the docs (README?).
Could every renderSimple() implementation incl. default implementation explain in JSDoc what it omits?

caugner · 2025-11-21T07:20:37Z

components/server/index.js

+  /**
+   * @param {...any} args
+   * @returns {any}
+   */


nit: add description of this method

caugner · 2025-11-21T07:21:17Z

components/doc/server.js

+  /**
+   * @param {import("@fred").Context<import("@rari").DocPage>} context
+   */


nit: explain what this method omits (even if it's comparably trivial from looking at render/renderSimple side-by-side

caugner · 2025-11-21T07:21:49Z

components/reference-layout/server.js

+  /**
+   * @param {import("@fred").Context<import("@rari").DocPage>} context
+   */


nit: explain what this simplified/minimal rendering omits

… custom

caugner · 2025-11-24T08:21:35Z

components/server/async-local-storage.js

+ * Store for internal context passed around components.
+ *
+ * Generally only used within the `ServerComponent` class itself,
+ * or very special server components (such as the `OuterLayout`).


nit: Can you give an example?

LeoMcA added 2 commits November 11, 2025 16:51

feat: components can render to simplified html

02495b2

add FRED_SIMPLE_HTML option to dev server for easier testing

541548d

LeoMcA requested a review from a team as a code owner November 11, 2025 17:19

LeoMcA requested a review from caugner November 11, 2025 17:19

LeoMcA temporarily deployed to review November 11, 2025 17:21 — with GitHub Actions Inactive

caugner reviewed Nov 13, 2025

View reviewed changes

LeoMcA commented Nov 13, 2025

View reviewed changes

caugner approved these changes Nov 21, 2025

View reviewed changes

caugner changed the title ~~feat: components can render to simplified html~~ feat(ServerComponent): add method to render simplified html Nov 21, 2025

LeoMcA added 2 commits November 21, 2025 17:54

Merge remote-tracking branch 'origin/main' into render-simple

2c081e3

add jsdoc explaining asyncLocalStorage and make contents type clearly…

198df40

… custom

LeoMcA deployed to review November 21, 2025 18:00 — with GitHub Actions View deployment

caugner reviewed Nov 24, 2025

View reviewed changes

feat(ServerComponent): add method to render simplified html #1072

Are you sure you want to change the base?

feat(ServerComponent): add method to render simplified html #1072

Conversation

LeoMcA commented Nov 11, 2025

Description

Motivation

Testing

Screenshot

Uh oh!

github-actions bot commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

caugner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

LeoMcA left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

caugner left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

github-actions bot commented Nov 11, 2025 •

edited

Loading