renderComponent() #1099

NullVoxPopuli · 2025-05-01T22:01:17Z

Propose `renderComponent()`

Rendered

Summary

This pull request is proposing a new RFC.

To succeed, it will need to pass into the Exploring Stage, followed by the Accepted Stage.

A Proposed or Exploring RFC may also move to the Closed Stage if it is withdrawn by the author or if it is rejected by the Ember team. This requires an "FCP to Close" period.

An FCP is required before merging this PR to advance to Accepted.

Upon merging this PR, automation will open a draft PR for this RFC to move to the Ready for Released Stage.

Exploring Stage Description

This stage is entered when the Ember team believes the concept described in the RFC should be pursued, but the RFC may still need some more work, discussion, answers to open questions, and/or a champion before it can move to the next stage.

An RFC is moved into Exploring with consensus of the relevant teams. The relevant team expects to spend time helping to refine the proposal. The RFC remains a PR and will have an Exploring label applied.

An Exploring RFC that is successfully completed can move to Accepted with an FCP is required as in the existing process. It may also be moved to Closed with an FCP.

Accepted Stage Description

To move into the "accepted stage" the RFC must have complete prose and have successfully passed through an "FCP to Accept" period in which the community has weighed in and consensus has been achieved on the direction. The relevant teams believe that the proposal is well-specified and ready for implementation. The RFC has a champion within one of the relevant teams.

If there are unanswered questions, we have outlined them and expect that they will be answered before Ready for Release.

When the RFC is accepted, the PR will be merged, and automation will open a new PR to move the RFC to the Ready for Release stage. That PR should be used to track implementation progress and gain consensus to move to the next stage.

Checklist to move to Exploring

The team believes the concepts described in the RFC should be pursued.
The label S-Proposed is removed from the PR and the label S-Exploring is added.
The Ember team is willing to work on the proposal to get it to Accepted

Checklist to move to Accepted

This PR has had the Final Comment Period label has been added to start the FCP
The RFC is announced in #news-and-announcements in the Ember Discord.
The RFC has complete prose, is well-specified and ready for implementation.
- All sections of the RFC are filled out.
- Any unanswered questions are outlined and expected to be answered before Ready for Release.
- "How we teach this?" is sufficiently filled out.
The RFC has a champion within one of the relevant teams.
The RFC has consensus after the FCP period.

text/1099-renderComponent.md

lifeart · 2025-05-02T07:23:49Z

text/1099-renderComponent.md

+
+When isInteractive is false, modifiers don't run, when true, modifiers do run.
+
+#### `into`


we could add after to allow app rendering after some node, without creating extra element wrapper

I've never heard of folks doing this -- is there a compelling reason / use case?

(maybe a bunch of render components in a list?)

i kinda want to push back on this, as I don't know if the current render can do this.
It can always be added later if we need it

@NullVoxPopuli, I agree.
Main use-case is render ember app in the middle of smf

@NullVoxPopuli in between nodes, for example, we have:

<html> <body> <header> ama header </header> { HERE_I_WANT_TO_RENDER_WHOLE_APP without creating extra node } <footer> ama footer </footer> </body> </html>

gossi · 2025-05-02T15:07:53Z

I'm a big fan of this, as this is the baseline to write a storybook adapter for gts files. But I have some questions around this, as I think the narrative is not clear (yet):

Why is it renderComponent() ... when it renders a template? (which I very much prefer). We can use that to render html that uses a helper or modifier. Vue and svelte have similar concepts for helper and modifier, but their testing lacks support for them, because they constrained themselves to components only (see my Inline Svelte components for tests sveltejs/svelte#14791 (comment), alse see API for vitest-browser-svelte and vitest-browser-vue) and I like us not to run into that constrained. I see it similar to the render() function we use in tests and would even expect the same behavior.
There is args but no backing class? That means a template-only-component? Is that by-design?
I wonder why there is an into parameter and later a parentElement() on the result type? If into becomes the parentElement then please name it like that (or is it the render replacing the into). Is the parentElement() on the result then needed? We can assume that is a given?
There is plenty API that adressess templates, but this is also very much fragmented. Can we all the API that is about templates in @ember/template? In the end it doesn't really matter if these are compilers or renderers or parsers or whatever. In the end everything that you need to operate on templates is coming from one package.

NullVoxPopuli · 2025-05-02T15:35:49Z

Why is it renderComponent() ... when it renders a template?
There is plenty API that adressess templates, but this is also very much fragmented. Can we all the API that is about templates in @ember/template

template() only returns a component 🎉
when not used with a class, it returns a template-only component.

I see it similar to the render() function we use in tests and would even expect the same behavior.

aye! the render() utility from @ember/test-helpers is quite involved, and after this RFC we could change its implementation to use renderComponent to

simplify implementation of @ember/test-helpers / ember-qunit
encourage exploration of other render-utilities, such as what would be needed to make browser-mode vitest work

There is args but no backing class? That means a template-only-component? Is that by-design?

what do you mean no backing class?

This is covered in RFC#931

import { template } from "@ember/template-compiler";

class Example extends Component {
  static {
    template(
      "Hello {{message}}",
      {
        component: this,
        scope: () => ({ message }),
      },
    );
  }
}

s the parentElement() on the result then needed? We can assume that is a given?

I only included it because the sample implementation from @wycats included it -- I'm more than happy to remove it, as it does feel redundant, since you need a handle to that same element (it is the into) to render anything anyway.

lifeart · 2025-05-02T15:56:47Z

text/1099-renderComponent.md

+/**
+ * Renders a component into an element, given a valid component definition.
+ */
+export function renderComponent(


wondering if it make sense to give function name just "render", because we can't render anything except component (or template-only component) in ember (app has it's own render logic)

lifeart · 2025-05-02T15:57:34Z

text/1099-renderComponent.md

+
+#### `into`
+
+The element to render the compnoent into.


should we have body as default target node?

can we rename it to parentElement to make it match what the DOM has already defined?

we removed parentElement 🙈

should we have body as default target node?

idk, any downsides?

you removed the getter from the result. I see into is ambivalent. It can mean, that this is a parent or replaced with the contents you provide. parentElement is a concept, that is already known.

lifeart · 2025-05-02T15:59:31Z

text/1099-renderComponent.md

+const render = modifier((element) => {
+    let result = renderComponent(Demo, {
+        owner,
+        env: { document: document, isInteractive: true },


for non-interactive envs we may have different function like renderSSR, so, wondering if we really need isInteractive flag, any use-cases for it?

great question -- I'd need to dig in to glimmer-vm to see what all isInteractive is used for.

I don't know how much benefit there is to having renderComponent do multiple things via this flag vs your suggestion of renderSSR (which I like)

lifeart · 2025-05-02T16:17:29Z

text/1099-renderComponent.md

+     * Destroys the render tree and removes all rendered content from the element rendered into.
+     */
+    destroy(): void
+


I think render result should contain component instance itself, to be able to update it's properties if needed (and to be able to debug it)

text/1099-renderComponent.md

simonihmig · 2025-05-04T21:08:13Z

text/1099-renderComponent.md

+        /**
+         * Optional owner. Defaults to `{}`, can be any object, but will need to implement the [Owner](https://api.emberjs.com/ember/release/classes/Owner) API for components within this render tree to access services.
+         */
+        owner?: object;


but will need to implement the Owner API

So should this be owner?: Owner; then? And how can it default to {}, which obvisouly does not implement Owner?

the owner doesn't need any specific methods implemented if no dependency injection is used.

in this use case for rendering, the owner is more about wiring up lifetimes, than it is adding resolving mechanisms.

NullVoxPopuli · 2025-07-11T18:34:57Z

text/1099-renderComponent.md

+
+## How we teach this
+
+`renderComponent` is meant as an integration-enabling API and would not be added to the guides, or need any documentation beyond what would live in source on the function itself.


TODO: add some examples

REPL

astro

vitepress

etc, etc

NullVoxPopuli · 2025-07-14T21:11:18Z

text/1099-renderComponent.md

+            /**
+             * Defaults to globalThis.document.
+             */
+            document?: SimpleDocument | Document; 


TODO: investigate what all is used on the document -- can the interface be more minimal?

NullVoxPopuli · 2025-07-14T21:17:05Z

text/1099-renderComponent.md

+There is an existing implementation in [PR#20781](https://github.com/emberjs/ember.js/pull/20781/)
+
+Here is where this RFC differs:
+- no hasDOM (we always have a DOM, as we have not done any design on [Swappable Renderers](https://github.com/emberjs/ember.js/issues/20648))


TODO: add this back, but default to true

https://github.com/emberjs/ember.js/blob/bd344210335a391f0455e4b1fea0d512267038d7/packages/%40ember/-internals/browser-environment/lib/has-dom.ts

explain that removing this involves legacy SSR, and we'd probably want to explore how modern SSR works

NullVoxPopuli · 2025-07-14T21:28:02Z

text/1099-renderComponent.md

+
+The args to pass to the component
+
+### Behaviors


create a renderer if one doesn't already exist.
otherwise use the host app's existing renderer (and revalidation stuff, etc)

import { renderComponent } from '@ember/renderer';

8f93b6c

github-actions bot added the S-Proposed In the Proposed Stage label May 1, 2025

NullVoxPopuli changed the title ~~import { renderComponent } from '@ember/renderer';~~ renderComponent() May 1, 2025

NullVoxPopuli added 6 commits May 1, 2025 18:02

Update file

7a07019

JSbin demo: 4 lines

bd3abb6

Update 1099-renderComponent.md

aeb0c9b

Update 1099-renderComponent.md

bbe15f0

Update 1099-renderComponent.md

9b29c99

Update 1099-renderComponent.md

e639595

lifeart reviewed May 2, 2025

View reviewed changes

text/1099-renderComponent.md Outdated Show resolved Hide resolved

lifeart reviewed May 2, 2025

View reviewed changes

Updates

f2dc345

NullVoxPopuli added 2 commits May 2, 2025 11:36

Remove parentElement from the returned object of renderComponent

9948528

Mention storybook

a7f7352

lifeart reviewed May 2, 2025

View reviewed changes

text/1099-renderComponent.md Outdated Show resolved Hide resolved

NullVoxPopuli added 7 commits May 2, 2025 12:26

Remove alwaysRevalidate

ff14fdf

Updaets

04be807

updaets

a3b61b3

Remove rerender

ff35d79

Add note

474d347

Updates, add some todos

e259063

React needs destruction

7353450

ef4 added S-Exploring In the Exploring RFC Stage and removed S-Proposed In the Proposed Stage labels May 2, 2025

NullVoxPopuli added 2 commits May 2, 2025 14:58

Change into type to Element

0321e75

Change into type to Element

fc3d1e5

simonihmig reviewed May 4, 2025

View reviewed changes

NullVoxPopuli mentioned this pull request May 18, 2025

new repl infra (enabling importing from CDN (no v1 addons)) NullVoxPopuli/limber#1925

Merged

6 tasks

NullVoxPopuli commented Jul 11, 2025

View reviewed changes

NullVoxPopuli mentioned this pull request Jul 13, 2025

Initial implementation of renderComponent emberjs/ember.js#20781

Open

NullVoxPopuli added 2 commits July 13, 2025 17:28

Update 1099-renderComponent.md

7616fc9

Update 1099-renderComponent.md

cea6629

NullVoxPopuli commented Jul 14, 2025

View reviewed changes

NullVoxPopuli added 3 commits July 15, 2025 11:01

Clarify differences from implementation PR

afc9af1

Updates, no more todos

a4d569a

Updates

705f435


		When isInteractive is false, modifiers don't run, when true, modifiers do run.

		#### `into`


		## How we teach this

		`renderComponent` is meant as an integration-enabling API and would not be added to the guides, or need any documentation beyond what would live in source on the function itself.

Uh oh!

renderComponent() #1099

Are you sure you want to change the base?

renderComponent() #1099

Conversation

NullVoxPopuli commented May 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Propose renderComponent()

Summary

Checklist to move to Exploring

Checklist to move to Accepted

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!

Choose a reason for hiding this comment

Uh oh!

gossi commented May 2, 2025

Uh oh!

NullVoxPopuli commented May 2, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

lifeart May 2, 2025 • 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!

gossi May 2, 2025 • 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!

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!

lifeart May 2, 2025 • 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

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!

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!

Uh oh!

NullVoxPopuli commented May 1, 2025 •

edited

Loading

Propose `renderComponent()`

lifeart May 2, 2025 •

edited

Loading

gossi May 2, 2025 •

edited

Loading

lifeart May 2, 2025 •

edited

Loading