Skip to content

feat(dist-custom-elements): new autoLoader option#6594

Merged
johnjenkins merged 5 commits intomainfrom
feat-add-dist-custom-elements-autoloader
Feb 7, 2026
Merged

feat(dist-custom-elements): new autoLoader option#6594
johnjenkins merged 5 commits intomainfrom
feat-add-dist-custom-elements-autoloader

Conversation

@johnjenkins
Copy link
Contributor

@johnjenkins johnjenkins commented Feb 7, 2026 •
edited
Loading

What is the current behavior?

GitHub Issue Number: N/A

What is the new behavior?

Generate an auto-loader script for dist-custom-elements that uses MutationObserver to lazily load and define custom elements as they appear in the DOM.

export const config: Config = {
  namespace: 'AutoLoader',
  outputTargets: [
    {
      type: 'dist-custom-elements',
      autoLoader: true,
      /** // or With options
      * autoLoader: {
      *   fileName: 'my-loader.js',
      *   autoStart: false
      * }
     */
    },
  ],
};

Documentation

TODO

Does this introduce a breaking change?

  • Yes
  • No

Testing

Spec and wdio

Other information

@johnjenkins johnjenkins requested a review from a team as a code owner February 7, 2026 17:36
@johnjenkins johnjenkins merged commit e130b7a into main Feb 7, 2026
69 checks passed
@theo-staizen
Copy link

theo-staizen commented Mar 1, 2026 •
edited
Loading

@johnjenkins are there no docs for this new autoLoader config?
https://stenciljs.com/docs/custom-elements

Also what's the difference between that and customElementsExportBehavior: 'auto-define-custom-elements'?

@johnjenkins
Copy link
Contributor Author

johnjenkins commented Mar 2, 2026 •
edited
Loading

@theo-staizen - apologies - I never got 'round to doing this 😅 (been busy looking at v5 dev)!

what's the difference between that and customElementsExportBehavior: 'auto-define-custom-elements'?

auto-define-custom-elements will mean that when you import a component - import 'components/my-component.js' - it will auto define itself and additionally auto import and define any dependent children.

autoloader is an alternative to dist; It outputs an loader.js in the root of your custom-elements dir - add that as a <script> tag and it adds a MutationObserver which detects DOM changes and imports / defines components as they're used.

It's still experimental right now - but initial testing shows it works (I added a simple perf test for it here)

This was referenced Mar 15, 2026
Closed
Merged
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@johnjenkins @theo-staizen