Using Stencil Built Web Components with Frameworks

In this section, we will outline the easiest way to integrate Stencil built web components into applications written using various popular frameworks.

Angular

Using a Stencil built web component collection within an Angular CLI project is a two-step process. We need to:

  1. Include the CUSTOM_ELEMENTS_SCHEMA in the modules that use the components
  2. Define the custom elements within your app by calling defineCustomElements(window) from main.ts (or some other appropriate place)

Including the Custom Elements Schema

Including the CUSTOM_ELEMENTS_SCHEMA in the module allows the use of the web components in the HTML markup without the compiler producing errors. Here is an example of adding it to AppModule:

import { BrowserModule } from '@angular/platform-browser';
import { CUSTOM_ELEMENTS_SCHEMA, NgModule } from '@angular/core';
import { FormsModule } from '@angular/forms';

import { AppComponent } from './app.component';
import { SharedModule } from './shared/shared.module';

@NgModule({
  declarations: [AppComponent],
  imports: [BrowserModule, FormsModule, SharedModule],
  bootstrap: [AppComponent],
  schemas: [CUSTOM_ELEMENTS_SCHEMA],
})
export class AppModule {}

The CUSTOM_ELEMENTS_SCHEMA needs to be included in any module that uses custom elements.

Defining the Custom Elements

A component collection built with Stencil includes a main function that is used to load the components in the collection. That function is called defineCustomElements() and it needs to be called once during the bootstrapping of your application. One convenient place to do this is in main.ts as such:

import { enableProdMode } from '@angular/core';
import { platformBrowserDynamic } from '@angular/platform-browser-dynamic';

import { AppModule } from './app/app.module';
import { environment } from './environments/environment';

import { defineCustomElements } from 'test-components';

if (environment.production) {
  enableProdMode();
}

platformBrowserDynamic().bootstrapModule(AppModule)
  .catch(err => console.log(err));
defineCustomElements(window);

React

With an application built using the create-react-app script the, easiest way to include the component library is to call defineCustomElements(window) from the index.js file.

import React from 'react';
import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import registerServiceWorker from './registerServiceWorker';

import { defineCustomElements } from 'test-components';

ReactDOM.render(<App />, document.getElementById('root'));
registerServiceWorker();
defineCustomElements(window);

Vue

In order to use the custom element library within the Vue app, the application must be modified to define the custom elements and to inform the Vue compiler which elements to ignore during compilation. This can all be done within the main.js file. For example:

import Vue from 'vue';
import App from './App.vue';
import { defineCustomElements } from 'test-components';

Vue.config.productionTip = false;
Vue.config.ignoredElements = [/test-\w*/];

defineCustomElements(window);

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

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.

Ember

Working with Stencil components in Ember is really easy thanks to the ember-cli-stencil addon. It handles:

  • Importing the required files into your vendor.js
  • Copying the component definitions into your assets directory
  • Optionally generating a wrapper component for improved compatibility with older Ember versions

Start off by installing the Ember addon

ember install ember-cli-stencil

Now, when you build your application, Stencil collections in your dependencies will automatically be discovered and pulled into your application. You can just start using the custom elements in your hbs files with no further work needed. For more information, check out the ember-cli-stencil documentation.

Uh oh! We can't find the page your looking for.

Head back to the home page