Thursday, 7 December, 2017 UTC

Summary

A few weeks ago in Polymer Summit 2017, Max Lynch and Adam Bradley introduced a new compiler which creates native Web Components. The compiler is called Stencil and it combines a lot of aspects from known libraries and frameworks such as React and Angular. In this article, we will familiarize ourselves with the basics of Stencil.

Stencil components are built using JSX and TypeScript. Therefore, familiarity with these two technologies will be very important before going further. To create our first Stencil component, we add a new file with a .tsx extension. For example, create a collapsible-panel folder in the src/components directory then add collapsible-panel.tsx in the folder. Insert the following code:

First of all, the file’s extension is .tsx which means that the code is written in TypeScript and JSX.

In order to create a Stencil component we use the Component decorator which configures the class with the selector in the DOM and with the scoped style. Decorators are basically functions that extend what is being decorated. Therefore, in this case, the Component decorator extends and adds more functionality to the CollapsiblePanel class. We will visit some of the existing decorators later in this article.

Then we create a class for the component and export it. In our class, we are using two other Stencil decorators — **Prop and State. Prop indicates a property that the component will get as a component attribute while State is an inner state of the component.

The component gets to work in the render function because that is where we tell our compiler how to render the component. Similarities with other frameworks can be noticed here — such as the use of curly brackets for binding the onClick and hidden events (like JSX in React) and the slot element which is used to indicate that the content will be provided by the component’s user (like transclusion in Angular).

To style our component, we create a file collapsible-panel.scss, add our style to it and insert it in our src/components/collapsible-panel directory:

If we run the app using the npm start command, we should see the following web page with a collapsible bar:

Decorators

Stencil is useful when it comes to building interactive components. There are a number of decorators such as Component, Props, State and Event that help achieve this. Let’s take a look at how these decorators are used.

Component Decorator

Our component must be decorated with an @Component() decorator from the @stencil/core package. A HTML tag name and a styleUrl which contains our style sheet are provided for the component. If multiple stylesheets are wanted then they can be referenced by styleUrls instead . For our stylesheet, we use Sass. Create a file with the .``scss extension.

Props are custom properties that we can provide values for. These are used to pass down data from parent components to any child component. The @Prop() decorator is used by a component to declare the Props it expects to receive. Props can be in different forms: they can be a number, a string, a boolean, an Object or an Array. When a member decorated with the @Prop() decorator is set, the component re-renders by default.

We now need to track the state of our component’s internal data. To do this we use the @State() decorator. The @State() decorator manages our component’s internal data. This implies that a user cannot modify the property from outside the component, but the component can modify it however it sees fit. Any changes to an @State() property will cause the components render function to be called again.

The code above will dispatch a custom DOM event called shoppingCompleted.

To handle events dispatched from @Events, we use the @``Listen() decorator in the listening component. In the example below, let’s assume that a child component, ShoppingList, emits a shoppingCompleted event using the EventEmitter.

It’s really exciting to see where the web is headed. The ability to create web components which can be shared with any framework and library is going to improve how we build for the web. For a deeper understanding of how Stencil works, especially with advanced concepts such as server side rendering and service workers, you can check out the Stencil Documentation here.

The post Getting started with StencilJS appeared first on Pusher Blog.