fix(bundling): allow proper webpack treeshaking

[rwaskiewicz]

Pull request checklist

Please check if your PR fulfills the following requirements:

• Tests for the changes have been added (for bug fixes / features)
• Docs have been reviewed and added / updated if needed (for bug fixes / features)
• Build (npm run build) was run locally and any changes were pushed
• Unit tests (npm test) were run locally and passed
• E2E Tests (npm run test.karma.prod) were run locally and passed
• Prettier (npm run prettier) was run locally and passed

Pull request type

Please check the type of change your PR introduces:

• Bugfix
• Feature
• Refactoring (no functional changes, no api changes)
• Build related changes
• Documentation content changes
• Other (please describe):

What is the current behavior?

See the GitHub Issue below. In short, applications using Stencil + Webpack are susceptible to tree shaking issues with the dist-custom-elements output target

GitHub Issue Number: 3191

What is the new behavior?

this commit solves an issue where stencil projects using webpack were
unable to treeshake properly. specifically, this is a workaround to a
webpack issue (webpack/webpack#14963) where
webpack fails to treeshake when a variable is reassigned.

with this commit, we introduce a new transformer to be run during the
typescript transpilation process, proxyCustomElement that takes a
stencil component's class initializer and hoists it as the first
argument of proxyCustomElement. this eliminates the need to reassign
the variable in the final output, which was causing code generated using
the dist-custom-elements output target to fail to treeshake when used
in a webpack project.

with the introduction of this separate transformer, the creation of the
proxyCustomElement call is removed from the
addDefineCustomElementFunctions transformer. this was done for two
reasons:

1. separation of concerns - proxying the component is not strictly
   necessary when creating define calls
2. proxying must occur after the initializer has been generated.
   currently, this occurs in nativeComponentTransform. therefore, this
   step must occur after nativeComponentTransform.

as a part of creating this new transformer, a new function,
createAnonymousClassMetadataProxy was created. we intentionally choose
not to use the existing proxy creation funcitons in the same file where
the new file is defiend in order to pass the class initializer directly
to our new helper function.

update-component-class has a variable statement creation call that was
modified from const to let in
6987e43. With this commit, we can
safely revert this change as we no longer redefine the variable holding
the stencil component

Does this introduce a breaking change?

• Yes
• No

Testing

Unit Tests

Unit tests were added, and traced with the debugger locally to verify they worked as expected.

Karma Tests

Existing karma tests surrounding defining custom elements still work

• https://github.com/ionic-team/stencil/tree/main/test/karma/test-app/custom-elements-output-webpack
• https://github.com/ionic-team/stencil/tree/main/test/karma/test-app/custom-elements-output-tag-class-different

Manual Tests

autoDefineCustomElements

Manually verified autoDefineCustomElements still works as intended

Reproduction Case

Using Liam's reproduction application (see the linked GH Issue, 3191), we can reproduce the original issue like so:

git clone git@github.com:liamdebeasi/webpack-reassignment-demo.git
cd webpack-reassignment-demo
git checkout stencil
cd component-library && npm i && npm run build && npm pack
cd ../
npm i 
npm i ./component-library/component-library-0.0.1.tgz --force
npx webpack
grep -o -i -E 'Avatar Component|Badge Component' dist/main.js

The above will install the dependencies on the component library and build it, install the component library in the parent project, then run webpack. The grep command looks for components in the output of webpack. Here we see

Badge Component
Avatar Component

which is not what we want. We should only see Badge Component as its the only component used.

To test the fix, pull down this branch, npm run clean && npm ci && npm run build && npm pack to generate the tarball. Here, I'm using a fresh copy of Liam's repro:

git clone git@github.com:liamdebeasi/webpack-reassignment-demo.git
cd webpack-reassignment-demo
git checkout stencil
cd component-library
npm i
npm i PATH_TO_TARBALL --force
npm run build && npm pack
cd ../
npm i
npm i ./component-library/component-library-0.0.1.tgz --force
npx webpack
grep -o -i -E 'Avatar Component|Badge Component' dist/main.js

Again, the above will install the dependencies on the component library and build it (this time using our tarball), install the component library in the parent project, then run webpack. The only other real difference/thing worth noting is the separate npm install commands that forcefully install our special packages to make sure we have the latest & greatest. This time when we run the grep command we see "Badge Component", as intended.

Ionic Framework

Finally, as one last testing step, I installed my local tarball into Ionic Framework's core package, then npm run build && npm run test.e2e && npm run test.spec

Other Information

If it's helpful to visualize, for a simple component:

import { Component, h } from "@stencil/core";

@Component({
    tag: 'my-cmp',
})
export class MyCmp {
    render() {
        return <div>Hello</div>;
    }
}

Before this PR, the output of running the dist-custom-elements output target with stock options would be:

import { HTMLElement, h, proxyCustomElement } from '@stencil/core/internal/client';

let MyCmp$1 = class extends HTMLElement {
  constructor() {
    super();
    this.__registerHost();
  }
  render() {
    return h("div", null, "Hello");
  }
};
MyCmp$1 = /*@__PURE__*/ proxyCustomElement(MyCmp$1, [0, "my-cmp"]);
function defineCustomElement$1() {
  if (typeof customElements === "undefined") {
    return;
  }
  const components = ["my-cmp"];
  components.forEach(tagName => { switch (tagName) {
    case "my-cmp":
      if (!customElements.get(tagName)) {
        customElements.define(tagName, MyCmp$1);
      }
      break;
  } });
}

const MyCmp = MyCmp$1;
const defineCustomElement = defineCustomElement$1;

export { MyCmp, defineCustomElement };

With this PR, we now generate:

import { proxyCustomElement, HTMLElement, h } from '@stencil/core/internal/client';

const MyCmp$1 = /*@__PURE__*/ proxyCustomElement(class extends HTMLElement {
  constructor() {
    super();
    this.__registerHost();
  }
  render() {
    return h("div", null, "Hello");
  }
}, [0, "my-cmp"]);
function defineCustomElement$1() {
  if (typeof customElements === "undefined") {
    return;
  }
  const components = ["my-cmp"];
  components.forEach(tagName => { switch (tagName) {
    case "my-cmp":
      if (!customElements.get(tagName)) {
        customElements.define(tagName, MyCmp$1);
      }
      break;
  } });
}

const MyCmp = MyCmp$1;
const defineCustomElement = defineCustomElement$1;

export { MyCmp, defineCustomElement };