Road to v5 🚀

[christian-bromann]

This issue is a tracking issue to collect feedback for potential breaking changes and new features in Stencil v5. We appreciate everyone interested to participate and comment on urgent issues or often requested features they would like to see in the new major version. We will collect all acknowledged issues in here and resolve comments that mention it.

Accepted v5 Bug Fixes / Features / Breaking Changes

• Support for Scope Elements (see Support for Scope Elements #2957)

Under Consideration

• Support importing JSX classes and use them to reference Stencil components in JSX - current state: more investigation needed to validate how we can provide type support, see branch cb/jsx-object
• Migrate to new compiler as Stencil is currently using an old Rollup version - current state: general acknowledgement within the Stencil community, however we need to validate whether we should migrate to something new like Rolldown or continue with Rollup and work on update the version

[johnjenkins]

I would like Stencil to remove (or at least deprecate in preparation for removal) a bunch / most of the extras:

• experimentalSlotFixes < rename to scopedSlotFixes. Encompasses all current slot polyfill behaviour. true by default when any scoped: true component is detected.
• appendChildSlotFix < remove
• cloneNodeFix < remove
• enableImportInjection < change to true by default
• experimentalImportInjection < remove
• experimentalScopedSlotChanges < remove
• scopedSlotTextContentFix < remove
• scriptDataOpts < remove
• slotChildNodesFix < remove

Related, I'd like Stencil to mark as deprecated (or remove) a few of the slot monkey-patches.
I think Stencil should concentrate on the minimum footprint required to make scoped: true components work in all the environments / libs they need to - not shim the whole DOM api.

• patchSlotInsertAdjacentHTML < deprecate or remove
• patchSlotInsertAdjacentText < deprecate or remove
• patchSlotInsertAdjacentElement < deprecate or remove

^ perhaps we could add a hook which Stencil would call, allowing users to add more if they require them?

Lastly, I think it would good for Stencil to unify / simplify scoped: boolean | shadow: boolean

Prepare for the removal of:

@Component({
  tag: 'tag-1'
})

@Component({
  tag: 'tag-1',
  scoped: false,
})

@Component({
  tag: 'tag-1',
  shadow: false,
})

Potentially changing the api to something like:

@Component({
  tag: 'tag-1',
  scoping: 'shadow' | 'class', // more could be added later - 'shadow-closed' etc
})

[christian-bromann]

I would like Stencil to remove (or at least deprecate in preparation for removal) a bunch / most of the extras:

💯 a question: are we removing patches like experimentalScopedSlotChanges because there is no need for them anymore, because you have been fixing them or because experimentalSlotFixes contains all the fixes already?

^ perhaps we could add a hook which Stencil would call, allowing users to add more if they require them?

Do you mean like a extra package / plugin for folks who want to use scoped components?

Lastly, I think it would good for Stencil to unify / simplify scoped: boolean | shadow: boolean

IMHO all Stencil components should be shadow by default. Users can switch them to scoped components by setting scoped: true. Wdyt?

[johnjenkins]

are we removing patches like experimentalScopedSlotChanges because there is no need for them anymore, because you have been fixing them or because experimentalSlotFixes contains all the fixes already?

At the moment to get the best / most consistent behaviour from scoped: true components you need to apply both experimentalScopedSlotChanges (does a bunch of vdom improvements) and experimentalSlotFixes (activates all the polyfills in dom-extras).

I, as someone who knows stencil pretty well, have no idea why experimentalScopedSlotChanges and experimentalSlotFixes are separate 😅.
I'm guessing it's not obvious to others coming from outside that they should apply these 1) at all 2) why they need both.

Also add to this that that Stencil runs all it's internal tests with these 2 flags on all the time now, it'll make our (Stencil devs) lives much easier and more determinative.

Do you mean like a extra package / plugin for folks who want to use scoped components?

I haven't thought about it much so maybe it doesn't make sense, but I just mean some kind of config hook / function that users can leverage...
When Stencil monkey patches it's scoped: true component prototypes, we could call the user hook.

This would allow users to provide their own monkey-patch for innerHTML or whatever. We could provide an example in the docs.

IMHO all Stencil components should be shadow by default. Users can switch them to scoped components by setting scoped: true. Wdyt?

Yeah - as a default that makese sense. But still tweaking might make sense(?)
e.g. We don't want scoped: false and it might be good to have something more extensible for the future (e.g. for shadowRoot#closed)

[christian-bromann]

it'll make our (Stencil devs) lives much easier and more determinative.

Afaik these patches were introduced as feature flags for users to opt-in because they had breaking character. v5 allows us to "merge them in" and consolidate this tech debt. If you suggest to make these patches the "default" behavior, I am all in.

This would allow users to provide their own monkey-patch for innerHTML or whatever. We could provide an example in the docs.

Is this something a common StencilJS user would do? My only concern is that opening up these hooks to users means we introduce interfaces that require maintenance and documentation when it is not clear how much this would be actually useful for a common Stencil user.

We don't want scoped: false and it might be good to have something more extensible for the future (e.g. for shadowRoot#closed)

I see. That makes sense, especially the extensibility part. scoping: 'shadow' | 'class', // more could be added later - 'shadow-closed' etc makes most sense to me then, making "shadow-open" the default choice.

My original desire was it to keep the upgrade effort minimal, while not dragging old interfaces (scoped: true) along into v5. With this, every large project that uses scoped: true would need to go through all files and change the value. However we could create a codemod for this, e.g. npx upgrade-stencil v5 to help make this process seamless.

[johnjenkins]

Is this something a common StencilJS user would do? My only concern is that opening up these hooks to users means we introduce interfaces that require maintenance and documentation when it is not clear how much this would be actually useful for a common Stencil user.

Agreed - let's not make more work before we need to!

My original desire was it to keep the upgrade effort minimal, while not dragging old interfaces (scoped: true) along into v5. With this, every large project that uses scoped: true would need to go through all files and change the value. However we could create a codemod for this, e.g. npx upgrade-stencil v5 to help make this process seamless.

Gotcha, happy to 'just' make shadow: true the default / deprecate the other options for now if that simplifies things

[christian-bromann]

Gotcha, happy to 'just' make shadow: true the default / deprecate the other options for now if that simplifies things

You are right though when it comes to extensibility. It makes sense to have ensure we can seamlessly add "closed" shadow roots in the future.