README

Elwins Test Web Components

Some test Web Components build with Stencil.

Stencil

Stencil is a simple compiler for generating Web Components and progressive web apps (PWA). Stencil was built by the Ionic Framework team for its next generation of performant mobile and desktop Web Components.

Stencil combines the best concepts of the most popular frontend frameworks into a compile-time rather than run-time tool. It takes TypeScript, JSX, a tiny virtual DOM layer, efficient one-way data binding, an asynchronous rendering pipeline (similar to React Fiber), and lazy-loading out of the box, and generates 100% standards-based Web Components that run on both modern browsers and legacy browsers back to Internet Explorer 11.

Stencil components are just Web Components, so they work in any major framework or with no framework at all. In many cases, Stencil can be used as a drop in replacement for traditional frontend frameworks given the capabilities now available in the browser, though using it as such is certainly not required.

Stencil also enables a number of key capabilities on top of Web Components, in particular Server Side Rendering (SSR) without the need to run a headless browser, pre-rendering, and objects-as-properties (instead of just strings).

Note: Stencil and Ionic are completely independent projects. Stencil does not prescribe any specific UI framework, but Ionic is the largest user of Stencil (today!)

Using these components

Script tag

Put a script tag similar to this in the head of your index.html:

<script
  type="module"
  src="https://cdn.jsdelivr.net/npm/elwins-test-web-components@0.3.0/dist/elwins-test-web-components/elwins-test-web-components.esm.js"
></script>

Then you can use the elements anywhere in your template, JSX, html etc.

For example:

<eve-button href="https://elwinvaneede.com">Website</eve-button>

Vue 2

Run npm install elwins-test-web-components or yarn add elwins-test-web-components

Edit src/main.js to include:

// Import my test Web Components
import {
  applyPolyfills,
  defineCustomElements,
} from "elwins-test-web-components/loader";
// ...
// configure Vue.js to ignore my test Web Components
Vue.config.ignoredElements = [/eve-\w*/];
// Register my test Web Components
applyPolyfills().then(() => {
  defineCustomElements();
});

new Vue({
  render: (h) => h(App),
}).$mount("#app");

The components should then be available in any of the Vue components:

render() {
  return (
    <div>
      <eve-button href="https://elwinvaneede.com">Website</eve-button>
    </div>
  )
}

Vue provides several different ways to install and use the framework in an application. The above technique for integrating a Stencil custom element library has been tested on a Vue 2 application that was created using the vue-cli with ES2015 and WebPack as primary options. A similar technique should work if the application was generated using other options.

Binding Complex Data

When binding complex data such as objects and arrays, use the .prop modifier to make Vue bind them as a property instead of an attribute:

<eve-select :options.prop="myOptions" />

Based on the Shoelace docs

Two-way Binding

One caveat is there's no support for v-model on custom elements in Vue 2, but you can still achieve two-way binding manually:

<!-- This doesn't work -->
<eve-input v-model="name"></eve-input>

<!-- This works, but it's a bit longer -->
<eve-input :value="name" @input="name = $event.target.value"></eve-input>

If that's too verbose, you can use this Directive from Shoelace.

Based on the Shoelace docs

Development

To start building the components using Stencil, clone this repo to a new directory:

git clone https://github.com/elwinvaneede/elwins-test-web-components.git elwins-test-web-components
cd elwins-test-web-components

and run:

npm install
npm start

To build the components for production, run:

npm run build

To run the unit tests for the components, run:

npm test

Usage no npm install needed!