elwins-test-web-components

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 src="https://unpkg.com/elwins-test-web-components@latest/dist/elwins-test-web-components.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>
  

Node Modules

• Run:

  npm install elwins-test-web-components --save
  

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

  <script src="node_modules/elwins-test-web-components/dist/elwins-test-web-components.js"></script>
  

• Then you can use the elements anywhere in your template, JSX, html etc
• For example:

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

Vue

Bindings to make this process easier will come in the future.

• Run:

  npm install elwins-test-web-components --save
  

• Import the components into your main.js file by:

  • importing the node module
  • telling Vue to ignore the custom element tags (see https://vuejs.org/v2/api/#ignoredElements)
  • binding the Stenciljs component code to the window object

  • import Vue from "vue";
    import App from "./App.vue";
    
    import {
      applyPolyfills,
      defineCustomElements,
    } from "elwins-test-web-components/loader";
    
    Vue.config.productionTip = false;
    
    // Tell Vue to ignore all components defined in the elwins-test-web-components
    // package. The regex assumes all components names are prefixed
    // 'eve'
    Vue.config.ignoredElements = [/eve-\w*/];
    
    // Bind the custom elements to the window object
    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/newsletter">Newsletter</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 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.

React

Use the bindings in https://github.com/elwinvaneede/elwins-test-web-components-react and follow the instructions there.

Angular

Bindings not yet created, but possible. Contact me if you need them.

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