DEV Community: Luis Aviles

How to Handle Time Zones using DateTime and Luxon

Luis Aviles — Fri, 16 Jul 2021 00:53:18 +0000

Raise your hand if you've ever had issues dealing with time zones, or even if you've asked, "How do I convert a Date object to another time zone in JavaScript?"

In my personal experience, this kind of requirement can become a big problem for developers if the date-handling-related concepts are not clearly understood, or the right tools are not used.

Using Dates and Time Zones in JavaScript

Let's suppose you have a date representation from an external API, and you need to convert the date to any desired time zone.

The best option for this is using a representation that meets the ISO 8601 standard. As an example of this, we can set a date like 2021/06/10 02:20:50 in UTC. Then, the standard notation for this date will be 2021-06-10T02:20:50+00:00.

On other hand, the JavaScript language provides a Date object that represents a single moment in time. You can create a Date object in different ways:

let date;
date = new Date(); // Get the current date

date = new Date("2021-06-10T02:20:50+00:00"); // An object representation of given string date

date = new Date(new Date()); // Creates an object representation from another one

Also, we can set a time zone value to any given Date object as follows:

let stringInput = "2021-06-10T02:20:50+00:00";
let timeZone = "America/Los_Angeles";
const dateObject = new Date(stringInput).toLocaleString("en-US", {
  timeZone,
});

console.log(dateObject); // Prints: 6/9/2021, 7:20:50 PM

The toLocaleString method returns a string with a language-sensitive representation of the Date object. At the same time, this method supports optional arguments where you can configure the time zone. Find more information about this method here.

As you can see, the output date matches the configured time zone (GMT-7). However, we have a string representation of the date, and it would be much better if we work with a JavaScript object instead.

Luxon

Luxon is considered an evolution of Moment.js- a very popular library for date handling in the JavaScript ecosystem.

As the Luxon project says:

Luxon is a powerful, modern, and friendly wrapper for JavaScript dates and times.

Indeed, this library solves most of the common problems related to Date handling:

Date internationalization
Time zones and Offsets
Calendars support
Dates Formatting
Dates Parsing
Dates Math (Add/Subtract days, months, etc)
Dates Validation
and More...

The DateTime Object

The most important part of the Luxon library is the DateTime object. It can be considered a wrapper of the native Date object along with a timezone, and a local configuration.

The simplest way of creating a DateTime object is as follows.

import { DateTime } from "luxon";

let dateTime = DateTime.local();
console.log("Current Date", dateTime.toISO()); // 2021-06-22T21:11:45.638-04:00

The method toISO() will return an ISO 8601-compliant string representation of the DateTime object.

Also, you can create a DateTime in a specific time zone.

// Create a DateTime in a Specific Timezone
let zone = "America/Denver";
let dateTime = DateTime.fromObject({
  zone,
});
console.log("Current Date", dateTime.toISO()); // 2021-06-22T19:11:45.640-06:00

As you can compare with the previous example, the time output is different because of the use of America/Denver as the time zone.

Of course, there is a way to create a custom date in a specific time zone:

let dateTime = DateTime.fromObject({
  'America/Denver',
}).set({
  day: 1,
  month: 5,
  year: 2021,
});
console.log("Custom date", dateTime.toISO()); //2021-05-01T19:11:45.641-06:00

The set method allows overriding specific properties such as year, month, day, etc.

Converting a DateTime to a different Time Zone

Now let's suppose we have a DateTime object, and we need to convert it to a different time zone.

let dateTime = DateTime.fromObject({
  'America/Denver',
}).set({
  day: 1,
  month: 5,
  year: 2021,
});

// Convert existing date to another Timezone
dateTime = dateTime.setZone("America/La_Paz");
console.log("Custom date, America/La_Paz", dateTime.toISO()); //2021-05-01T21:11:45.641-04:00

Configuring the Default Time Zone

What happens when the whole application needs to run every date in a specific time zone? Just suppose you have defined a configuration within your app to allow the selection of a time zone at any time.

To solve this problem, you don't need to use the time zone string here and there. The Settings class, instead, comes to the rescue:

import { Settings } from "luxon";

// Configure the time zone
Settings.defaultZoneName = "America/Denver";

console.log(Settings.defaultZoneName); // Reading the configured time zone.

The defaultZoneName can be used as a set or get method for the default time zone when you're working with the library.

In the same way, the Settings class contains other methods to configure Luxon's behavior.

Then, when you're creating a new DateTime object again, it will take the configured time zone by default.

dateTime = DateTime.local();
console.log("Configured defaultZoneName", dateTime.toISO()); //2021-06-22T19:21:54.362-06:00

Pay attention to the offset value, which corresponds now with America/Denver.

Validate a Time Zone

In case you define a user entry point to configure the time zone globally, it is important to validate the text before causing problems with the DateTime objects.

A useful way to do it is through, again, a DateTime object:

const timeZone = "America/Not_Defined_TZ";
const myDateTime = DateTime.local().setZone(timeZone);
console.log("timeZone valid", myDateTime.isValid); // Prints 'false'

Now try again with a valid time zone, for example, America/Los_Angeles.

Live Demo

Wanna play around with this code? Just open the embedded CodeSandbox editor:

Conclusion

In this article, I described a couple of useful methods for using Luxon for Time Zone handling using either JavaScript or TypeScript. Personally, I consider it a very useful library, and it also avoids rewriting and testing your own code for handling dates and time zones, which could save you a lot of time.

Feel free to reach out on Twitter if you have any questions. Follow me on GitHub to see more about my work.

This Dot Labs is a modern web consultancy focused on helping companies realize their digital transformation efforts. For expert architectural guidance, training, or consulting in React, Angular, Vue, Web Components, GraphQL, Node, Bazel, or Polymer, visit thisdotlabs.com.

This Dot Media is focused on creating an inclusive and educational web for all. We keep you up to date with advancements in the modern web through events, podcasts, and free content. To learn, visit thisdot.co.

Web Components Communication Using an Event Bus

Luis Aviles — Thu, 17 Jun 2021 00:56:09 +0000

Imagine you're building a Single Page Application using Web Components only. You have several pages, have configured the routes, and need to be able to handle general events or actions.

Here's when you start to think about potential solutions as well: Maybe it's time to add state management to the application? Is it a good time to build a "custom" solution? What about using some design patterns in this case?

The answers to these questions will depend on the complexity of the current scenario, the experience of the developers, or on the opinions of the team. It is clear that there is no absolute answer!

In this article, we'll go over how to communicate between components using a custom Event Bus implementation.

What is an Event Bus?

The Event Bus idea is generally associated with the Publish-subscribe pattern:

Publish–subscribe is a messaging pattern where senders of messages, called publishers, do not program the messages to be sent directly to specific receivers, called 'subscribers', but instead, categorize published messages into classes without knowledge of subscribers

In other words, an Event Bus can be considered as a global way to transport messages or events to make them accessible from any place within the application.

Web Components Communication

When you're working with Web Components through LitElement, it's usual firing events for sending messages between them. You can use either Standard or Custom events.

Fire a Standard Event using new Event('event')
Fire a Custom Event using new CustomEvent('event', {...options})

For a practical example, let's assume we have two components at this time: The first one could be named as a parent component and the second one as the child component

The Child Component

The child component is defined as a custom button implementation only.

import { LitElement, html, property, customElement, css } from 'lit-element';

export interface MyButtonEvent {
  label: string;
  date: string;
}

@customElement('my-button')
class MyButton extends LitElement {
  @property({ type: String }) label: string = 'Hello LitElement';

  constructor() {
    super();
  }

  render() {
    return html`
      <span @click=${this.handleClick}>
        ${this.label}
      </span>
    `;
  }

  private handleClick(e: MouseEvent) {
    this.dispatchEvent(new Event("myClick"));
  }
}

The above code snippet does the following:

It creates a model for the data to be passed through a Custom Event. The model is defined as an interface called MyButtonEvent.
Next, the component is created using a TypeScript class with the help of the LitElement decorators
- The @customElement decorator allows the component definition using a name for it: my-button. It is applied at the class level.
- The static styles attribute defines the styles for the component using a tagged template literal(css)
- The @property decorator, which allows declaring properties in a readable way.
- The render method returns the HTML content through a template literal(html). This function will be called any time label property changes.

Now pay attention to the render() method. It does use the @click binding into the template. And this allows capturing the click event itself in a declarative way.

The Parent Component

The parent component works as a container since it will be in charge of the custom button rendering. Here's how the template will be using the child component:

<my-button label="Show Alert"> </my-button>

However, in a real-world scenario, this parent component we'll need to handle the child event myClick once it gets fired.

// my-container.ts

import { LitElement, html, customElement, css } from "lit-element";
import "./my-button";

@customElement("my-container")
class MyContainer extends LitElement {
  static styles = css`
    :host {
      display: block;
    }
  `;

  constructor() {
    super();
  }

  render() {
    return html`
      <my-button @myClick=${this.handleClick} label="Hello LitElement">
      </my-button>
    `;
  }

  private handleClick(e: Event) {
    console.log("MyContainer, myClick", e);
  }
}

Find a brief explanation of the previous code snippet before starting to use the Event Bus.

The render function defines a template literal, and makes use of the my-button element using <my-button></my-button> as if it were part of the HTML vocabulary
- The @myClick attribute sets a function reference to handle the event in a declarative syntax.
- The label attribute sets the text displayed in the button. Anytime it changes, the button will be rendered again.
The handleClick function receives an Event object with more information about it. Open your browser's console, and feel free to inspect this value.

In case you require sending data along with the event, the handleClick method can be updated accordingly:

  private handleClick(e: CustomEvent<MyButtonEvent>) {
    const detail: MyButtonEvent = e.detail;
    // Process the 'detail' object here
  }

Event Bus Communication

For this example, we can assume that the parent component will act as the "root" of all events to be used through the Event Bus object.

Then, let's register an alert event in the constructor method. The purpose of it will be to render an alert message from different places in the application.

// my-container.ts

class MyContainer extends LitElement {

  private alertRegistry: Registry;

  constructor() {
    super();

    this.alertRegistry = EventBus.getInstance().register(
      'alert',
      (message: string) => {
        AlertManager.showAlert(message);
      }
    );
  }
}

Once you register an event, you can get the Registry object to be able to unregister later.

You're ready to go!

As a next step, let's dispatch an alert event every time the button gets "clicked". This can be done within the handleClick function:

  // my-container.ts
  private handleClick(e: CustomEvent<MyButtonEvent>) {
    const detail: MyButtonEvent = e.detail;
    EventBus.getInstance().dispatch('alert', `Alert at ${detail.date}`);
  }

Now the Event Bus is working as expected. You can start registering/dispatching other events from other components. They do not need to be related in any way, since the communication channel for this type of event will be the Event Bus.

Unregistering from the Event Bus

It's important to keep track of the different events you're registering to avoid potential memory leaks in the application.

For this example, we'll enable displaying the alert message only for the first time. Other clicks over the "Show Alert" button won't take any effect or dispatch actions through the Event Bus.

Let's update the parent component.

// my-container.ts

  private handleClick(e: CustomEvent<MyButtonEvent>) {
    const detail: MyButtonEvent = e.detail;

    EventBus.getInstance().dispatch('alert', `Alert at ${detail.date}`);
    this.alertRegistry.unregister();
  }

The last line of the handleClick method ensures the unregistering process from the Event Bus. Thus, other calls for the alert event will be ignored.

Live Demo

Wanna play around with this code? Just open the embedded Stackblitz editor:

Conclusion

In this article, I described two ways to communicate and pass data between components.

In case the components are related, it is clear that the best way to communicate them is through simple or custom events.
If you're planning to send events across the entire application, no matter the component or the module, then the Event Bus may work for you. In other words, it's a way to just send Events to a common channel without knowing who is going to process the message at the end.

Feel free to reach out on Twitter if you have any questions. Follow me on GitHub to see more about my work. Be ready for more articles about Lit in this blog.

Lit 2.0 Released: Building Fast and Lightweight Web Components

Luis Aviles — Tue, 18 May 2021 03:40:05 +0000

In the past months, I've been actively using Web Components to build single-page applications. It has been a great experience so far, not only because I learned a lot about the latest web standards, but also because the web applications ended up being quite fast.

The Web Component development story is not something new. In fact, it has been nearly three years since LitElement was introduced as a base class to build Web Components using JavaScript with the addition of great support from TypeScript. On the other hand, lit-html had been released almost four years ago as a way to create small and fast HTML templates in JavaScript.

As it was expected, these two worlds evolved favorably. Lit 2.0 was announced as a single library with a major update promising simple and fast Web Components.

What's New?

Lit 2.0 is coming out with a lot of great new features.

Smaller

The templating system of Lit 2.0 weights around 2.7 KB minified, and gzipped(compressed). Including the component base + reactive elements, it weights 5.8 KB.

The previous image shows the bundle size for lit@2.0.0-rc.1 from the BundlePhobia tool.

Better

This new release also includes several template improvements and a brand new class-based API for creating directives as the below example shows.

import {Directive, directive} from 'lit/directive.js';

class MyDirective extends Directive {
  render() {
    return `Hello world`;
  }
}

const hello = directive(MyDirective);
const template = html`<div>${hello()}</div>`;

Also, Lit 2.0 introduces the concept of Reactive Controllers which is a powerful primitive for code reuse and composition.

A Reactive Controller comes with the ability to "hook" into the component's lifecycle and it has its own creation API.

class MyElement extends LitElement {
  private clock = new MyReactiveController(this);
}

In the above code snippet, the component associated with the Reactive Controller instance is called the host component.

Faster

The Lit team has considered efficient rendering as one of the core values for the library since a good performance is always important when you're building for the web platform.

The library authors claim that Lit 2.0 is up to 20% faster on initial rendering and up to 15% faster on updates.

Also, it's good to know that Lit templates are efficient in keeping track of the UI, and only updates on re-rendering. These powerful features come along with interoperability in mind: they can work anywhere you use HTML with or without any framework.

Server-Side Rendering

Yes, Lit 2.0 comes with a server package for rendering Lit templates and components on the server, along with a flexible client-side "hydration".

The package name is below @lit-labs/ssr since it's a pre-release software at this time. However, it's expected to support a wide range of use cases:

App rendering frameworks built on top of web components.
Framework-specific plugins for rendering custom elements such as React or Angular.
Integration with static site generators.

You can be up-to-date about this server-side rendering support by following the news in this repository.

Connect with Lit

Lit 2.0 is not only about the cool features that are already described above, it comes along with a brand-new logo, a new website, and a welcoming community.

Why Lit?

The Web Components written with Lit are natively supported by browsers and they can be a perfect solution to share components across your application.

Also, Lit can be a useful solution to create your set of components through the Design System defined by your organization. This is even more helpful when your team uses multiple libraries and frameworks to build applications!

Community

You can be the first to know the good news about Lit and the upcoming releases. Share your ideas and projects with the community.

Join the conversations on Twitter: @buildWithLit
Send your issues or even better, help with Pull Requests on GitHub
Send your questions and help with technical issues on StackOverflow. Use lit, lit-html and lit-element as the related tags.
Finally, you can be part of lit-and-friends on Slack.

Just always remember to be nice to each other!

Playground

If you are a Developer who really enjoys and thinks through interactive examples, you cannot miss the Lit Playground website, which comes with the classic "Hello World" examples (using JavaScript and TypeScript), and others covering template concepts, directives, and more.

Conclusion

In case you were using both LitElement and lit-html (like me), it could be a great opportunity to upgrade your code to Lit 2.0. The general idea to do this involves updating the npm packages, importing paths, updating any custom directive, and using the class-based API or even adapt to minor breaking changes. Luckily, there is a guide available for upgrades.

If you're new in the world of Web Components, welcome! There is a step-by-step Lit tutorial available too.

Feel free to reach out on Twitter if you have any questions. Follow me on GitHub to see more about my work. Be ready for more articles about Lit on this blog.

LitElement properties: @property vs @internalProperty

Luis Aviles — Thu, 18 Feb 2021 00:22:16 +0000

LitElement is an excellent alternative to build lightweight web applications since it’s based on the Web Components standard, and with the help of TypeScript, we can see more possibilities to build web components faster with a good developer experience.

In this article, I will explain the practical use of @property and @internalProperty decorators using a TypeScript implementation.

The Problem

Let's suppose you're building a small application that needs to display a list of Users. When you select any of them, other details should be displayed. In this case, it's the Address information.

Next, let's define the data model and a dataset before implementing the web components using LitElement.

Data Modeling and Dataset

The Data Model

Let's rely on TypeScript interfaces and static typing to have the model ready.

// model.ts
export interface User {
  id: number;
  name: string;
}

export interface Address {
  country: string;
  state: string;
  city: string;
  street: string;
  zipCode: number;
}

As you may note, the Address interface will display a set of attributes that represents a complete address.

The Source of Data

To make the testing easier, let's create a dataset of entities that matches the previous model.

// data.ts
import { Address } from "./model";
import { User } from "./model";

export const users: User[] = [
  {
    id: 0,
    name: "Donald Mayfield"
  },
  {
    id: 1,
    name: "Jill J. Fritz"
  },
  {
    id: 2,
    name: "Terry Buttram"
  }
];

export const address: Address[] = [
  {
    street: "2180 BELLFLOWER",
    country: "USA",
    state: "AL",
    city: "Madison",
    zipCode: 35064
  },
  {
    street: "845 ODOM ROAD, SUITE 200",
    country: "USA",
    state: "CA",
    city: "Los Angeles",
    zipCode: 90720
  },
  {
    street: "9025 QUEENS BLVD",
    country: "USA",
    state: "NY",
    city: "Queens",
    zipCode: 11355
  }
];

The relationship between the users and address is simple: The User id matches with the position of the address array.

Using LitElement Properties

LitElement provides different ways to manage the properties. As the documentation says:

LitElement manages your declared properties and their corresponding attributes.

This can be done using either a static properties field or using decorators. Let's take the TypeScript-way using the power of decorators.

We'll understand the "properties management" better in the practice through the next sections.

Creating the MainViewer Container

Let's create a class to contain our first component. In this case, we'll define a container component that will be in charge of displaying both the list of users and their details.

import {
  LitElement,
  html,
  customElement,
  css,
  internalProperty
} from "lit-element";
import { users } from "./data";
import { User } from "./model";

@customElement("main-viewer")
class MainViewer extends LitElement {
  static styles = css`
    :host {
      display: block;
    }
  `;

  users: User[] = [];
  userId?: number;

  constructor() {
    super();
  }

  render() {
    return html`
      <div>
        <h1>User Address Viewer</h1>
        <span>Select a User to see the Address:</span>
        <ul>
          ${this.users.map(
            user => html`
              <li>
                <a href="#" @click="${() => this.viewAddress(user.id)}"
                  >${user.name}</a
                >
              </li>
            `
          )}
        </ul>
      </div>
    `;
  }

  async connectedCallback() {
    super.connectedCallback();
    this.users = await this.getUsers();
  }

  private getUsers() {
    // in the real-world you'll get the data from a service, file, etc.
    return new Promise<User[]>((resolve, reject) => resolve(users));
  }

  private viewAddress(id: number) {
    this.userId = id;
  }
}

Let's explain what is happening in this component so far:

The static styles attribute defines the styles for the component using a tagged template literal (css).
It defines two class properties: users to "store" the set of Users to be displayed in the main list. Also, the userId will contain a reference of the selected User identifier (this value will be changed every time you select a different user).
The render method returns the HTML content through a template literal (html). This function will be called any time a component property changes.
The connectedCallback function makes a call to getUsers in order to get the initial data when the component is added to the document's DOM.
The getUsers function should perform an asynchronous call (in a real-world scenario) to retrieve the data.
The viewAddress function receives an id of the object selected once the user performs a click action over the link. Then, the class property userId will be updated.

The previous code is perfectly fine. However, it won't display any data yet! We'll only see the title and a blank section on the page and no list of users rendered.

Using the @internalProperty Decorator

In order to fix this rendering issue, we should make sure to trigger an update cycle for the web component.

Think for a while about when the update cycle should be performed: every time you change the list of users! However, this cannot be done every time you update any variable or attribute from your class. Instead, you should mention which attributes are "keys" to perform the rendering operation or keep your component updated. We'll call LitElement properties to these key attributes.

Once you have identified them, we'll need to declare these attributes as properties:

// main-viewer.ts

@customElement("main-viewer")
class MainViewer extends LitElement {
  // ...

  @internalProperty() users: User[] = [];
  @internalProperty() userId?: number;

  constructor() {
    super();
  }

  // ...
}

Why use @internalProperty in this case?

For this MainViewer component, we don't need to reference either users or userId from outside the component.
From the previous point, we can consider users and userId attributes as private or protected.

In other words, LitElement observes and "reacts" to these property changes so the template gets rendered/updated automatically.

Using the @property Decorator

Creating the AddressViewer Component

Before creating the child component, let's think about how we are going to use it from the container. In terms of web components, let's suppose we'll need the following element and attribute:

<address-viewer .userId=${userId}></address-viewer>

That means the new address-viewer component will need to "receive" the userId value to be able to retrieve the respective Address. The .userId=${userId} notation applies a one-way data binding to a property, meaning the AddressViewer component will have the userId as a public property.

@property vs @internalProperty decorators

Let's take the previous consideration into account and create a new file address-viewer.ts:

import {
  LitElement,
  html,
  property,
  customElement,
  css,
  internalProperty
} from "lit-element";
import { address } from "./data";
import { Address } from "./model";

@customElement("address-viewer")
class AddressViewer extends LitElement {
  static styles = css`
    :host {
      display: block;
    }

    table {
      border-collapse: collapse;
      width: 100%;
    }

    td,
    th {
      border: 1px solid gray;
      text-align: left;
      padding: 5px;
    }
  `;

  @property({ type: Number }) userId: number;
  @internalProperty() userAddress?: Address;

  constructor() {
    super();
  }

  render() {
    if (this.userAddress === undefined) {
      return html``;
    }

    return html`
      <table>
        <tr>
          <th>Country</th>
          <th>State</th>
          <th>City</th>
          <th>Street</th>
          <th>Zip Code</th>
        </tr>
        <tr>
          <td>${this.userAddress.country}</td>
          <td>${this.userAddress.state}</td>
          <td>${this.userAddress.city}</td>
          <td>${this.userAddress.street}</td>
          <td>${this.userAddress.zipCode}</td>
        </tr>
      </table>
    `;
  }

  update(changedProperties: Map<string, unknown>) {
    if (changedProperties.has("userId")) {
      const oldValue = changedProperties.get("userId") as number;
      console.log("userId updated, newVal", this.userId, "oldVal", oldValue);
      this.loadAddress(this.userId);
    }
    super.update(changedProperties);
  }

  private async loadAddress(id: number) {
    this.userAddress = await this.getAddress(id);
  }

  private getAddress(id: number) {
    return new Promise<Address>((resolve, reject) => resolve(address[id]));
  }
}

Again, let's take a closer look at the previous source code:

The userId attribute is defined as a public property for the component using @property decorator.
The userAddress property doesn't need to be public property for the component. Instead, it's defined using @internalProperty decorator to trigger the update cycle once it gets changed.
- Initially, It's undefined
The render method returns the HTML content to be rendered every time a property is changed.
- Note the function will return a meaningful template only once the userAddress contains the required object.
The update function reflects property values and calls the render function.
- It receives a Map with the properties that have been changed.
- It verifies if the userId property has been changed, and then performs a call to loadAddress.
- Whenever you override this method, you'll need to call super.update() to render your template.
The loadAddress function takes the new value for userId and calls the utility function to retrieve the Address object.

The brand-new AddressViewer component is ready, and we'll need to use it as a child component in the main container. Let's update the render function as follows:

// main-viewer.ts

// Let's import the <address-viewer> definition
import "./address-viewer";

@customElement("main-viewer")
class MainViewer extends LitElement {
  //...

  render() {
    return html`
      <div>
        <h1>User Address Viewer</h1>
        <span>Select a User to see the Address:</span>
        <ul>
          ${this.users.map(
            user => html`
              <li>
                <a href="#" @click="${() => this.viewAddress(user.id)}"
                  >${user.name}</a
                >
              </li>
            `
          )}
        </ul>
        <address-viewer .userId=${this.userId}></address-viewer>
      </div>
    `;
  }

 // ... 
}

Again, pay attention to the one-way data binding .userId=${this.userId} that will trigger a rendering operation over the <address-viewer> component whenever the userId gets changed. This is magic, right?

Live Demo

Want to play around with this code? Open the Stackblitz editor:

Feel free to reach out on Twitter if you have any questions. Follow me on GitHub to see more about my work.

How to Handle Events with LitElement and TypeScript

Luis Aviles — Thu, 11 Feb 2021 16:23:12 +0000

In previous posts, I covered different topics about Web Components and Single-Page Applications using LitElement and TypeScript.

It's well known that LitElement has added good support to manage Properties and Events to write powerful web components. In this post, we'll focus on event handling using a LitElement-based component as a use case using the TypeScript language.

The Custom Component

Let's start the Web Component creation using the Stackblitz editor and define the initial code for our first component:

// my-button.ts

import { LitElement, html, property, customElement, css } from "lit-element";

@customElement("my-button")
class MyButton extends LitElement {
  static styles = css`
    :host {
      display: inline-block;
      padding: 10px;
      background: #5fe1ee;
      border-radius: 5px;
      cursor: pointer;
    }
  `;

  @property() label = "Hello LitElement";

  constructor() {
    super();
  }

  render() {
    return html`
      <span>
        ${this.label}
      </span>
    `;
  }
}

The previous code creates a custom button definition using the following features from LitElement:

The @customElement decorator allows the component definition using a name for it: my-button. It is applied at the class level.
The static styles attribute defines the styles for the component using a tagged template literal(css)
The @property decorator, which allows declaring properties in a readable way.
The render method returns the HTML content through a template literal(html). This function will be called any time label property changes.

How to Fire Events

Once the previous code gets rendered in the browser, you'll see a custom button definition as the next screenshot shows:

However, this button definition doesn't have the ability to fire events yet. Let's add that support updating the render function:

// my-button.ts

  render() {
    return html`
      <span @click=${this.handleClick}>
        ${this.label}
      </span>
    `;
  }

  private handleClick(e: MouseEvent) {
    console.log("MyButton, click", e);
  }

The render function does use the lit-html @click binding into the template. This will allow capturing the click event. In other words, we're adding an event listener in a declarative way.

Let's assume the brand new <my-button></my-button> component needs to fire the click event. This can be done using the dispatchEvent function.

// my-button.ts

  private handleClick(e: MouseEvent) {
    this.dispatchEvent(new Event("myClick"));
  }

Handling the Event

In a real-world scenario, we'll need to handle (or listen) the new myClick event once it gets fired.

Let's add a container component int the my-container.ts file and import the my-button.ts definition as follows:

// my-container.ts

import { LitElement, html, customElement, css } from "lit-element";
import "./my-button";

@customElement("my-container")
class MyContainer extends LitElement {
  static styles = css`
    :host {
      display: block;
    }
  `;

  constructor() {
    super();
  }

  render() {
    return html`
      <my-button @myClick=${this.handleClick} label="Hello LitElement">
      </my-button>
    `;
  }

  private handleClick(e: Event) {
    console.log("MyContainer, myClick", e);
  }
}

Let's explain what's happening there:

The render function defines a template literal and makes use of the my-button element using <my-button></my-button> as if it were part of the HTML vocabulary
- The @myClick attribute sets a function reference to handle the event in a declarative syntax.
- The label attribute sets the text displayed in the button. Anytime it changes, the button will be rendered again.
The handleClick function receives an Event object with more information about it. Open your browser's console and feel free to inspect this value.

How to Fire Custom Events

There are times when the web component needs to send a value or an object (along with its attributes) when it fires the event. if that's the case, you can create a CustomEvent.

Since we're using TypeScript, it would be great to create a model for the data to be passed through the Custom Event. Let's create it in the my-button.ts file as:

// my-button.ts

export interface MyButtonEvent {
  label: string;
  date: string;
}

Of course, you can create a separate file for this model. Now, let's update the handleClick function as follows:

// my-button.ts

  private handleClick(e: MouseEvent) {
    const event = new CustomEvent<MyButtonEvent>("myClick", {
      detail: {
        label: this.label,
        date: new Date().toISOString()
      }
    });
    this.dispatchEvent(event);
  }

The Custom Event object is created for specifying the data type (MyButtonEvent) that will be fired as part of the detail. Remember the name of this interface: we'll make use of it next.

Handling the Custom Event

In a previous section, we've been handling the myClick event in the my-container.ts file. Let's update it to support our Custom Event.

// my-container.ts

  private handleClick(e: CustomEvent<MyButtonEvent>) {
    const detail: MyButtonEvent = e.detail;

    console.log("MyContainer, myClick", detail);
  }

Pay attention to the event parameter and the type we're using to capture the event details: CustomEvent<MyButtonEvent>. This is helpful to capture the emitted object with the right type. Thanks, TypeScript! :-)

Live Demo

Wanna play around with this code? Just open the Stackblitz editor:

Conclusion

LitElement is an excellent alternative to build lightweight web applications since it's based on the Web Components standard, and with the help of TypeScript, we can see more possibilities to build Web Components faster with a good developer experience.

Feel free to reach out on Twitter if you have any questions. Follow me on GitHub to see more about my work.

Introduction to LitElement

Luis Aviles — Wed, 10 Feb 2021 20:18:19 +0000

The use of powerful frameworks and libraries is very widespread nowadays. We can name Angular, React.js, Vue, Svelte, among others.

It's hard to imagine building a web application without the use of any of these component-based frameworks. For these options, the components are reusable and configurable widgets. They are able to provide a custom behavior and styling and they're used as building blocks for the application.

Can we share a component between these frameworks? The short answer is no. Every framework/library has a custom API definition to build components and they are not interoperable with each other.

What is LitElement?

According to the official LitElement website:

LitElement is a simple base class for creating fast, lightweight web components that work in any web page with any framework.

That means we can use the OOP (Object-Oriented Programming) paradigm using JavaScript or even better: TypeScript.

JavaScript vs TypeScript

To create your first custom Web Component using JavaScript, you'll need to define a class that implements the appearance and functionality of it as follows:

import { LitElement, html } from 'lit-element';

class HelloComponent extends LitElement {
  static get properties() {
    return { name: { type: String } };
  }

  constructor() {
    super();
    this.name = 'Luis'; // Set a default value here
  }

  // Defines a template to be "rendered" as part of the component.
  render() { 
    return html`Hello ${this.name}. Welcome to LitElement!`;
  }
}

// Register as a custom element named <hello-component>
customElements.define('hello-component', HelloComponent);

Now let's see how you can write your first Web Component using the power of TypeScript:

import { LitElement, html, property, customElement } from 'lit-element';

//Decorator that register as a custom element named <hello-component>
@customElement('hello-component') 
export class HelloComponent extends LitElement {
  // You can assign the default value here.
  @property({type: String}) name = 'Luis'; 

  // Defines a template to be "rendered" as part of the component.
  render() { 
    return html`Hello, ${this.name}. Welcome to LitElement!</p>`;
  }
}

As you may note, the use of TypeScript decorators will provide the ability to annotate the class declarations and members.

In the next section, you can find more articles to learn and get started with LitElement and TypeScript.

More about LitElement

In the past months, I've been publishing several articles about using LitElement with TypeScript. Also, I've been using these technologies actively to build Single-page applications, and I'm happy to share these resources with you:

More articles are coming soon! Do not miss any of them and visit the This Dot Blog to be up-to-date.

Feel free to reach out on Twitter if you have any questions. Follow me on GitHub to see more about my work.

¿Por qué deberías usar React Query o SWR?

Luis Aviles — Wed, 10 Feb 2021 20:14:59 +0000

La mayoría de nosotros aquí en React-land estamos desarrollando nuestras aplicaciones con la nueva y brillante API Hooks y enviando peticiones a APIs externas como nadie. Quienes somos nuevos con los hooks, puede que hayamos empezado a crearlos como el siguiente ejemplo simplificado:

export const useSearch = () => {
    const [query, setQuery] = useState();
    const [results, setResults] = useState();

    useEffect(() => {
        if (!query)
            return;

        api.search(query)
            .then(results => setResults(results));
    }, [query]);

    return {
        query,
        setQuery,
        results
    }
}

El Problema

Sin embargo, cada vez que se invoca a un hook, esa instancia es única para el componente desde el que se llamó, por lo que podemos encontrar algunos problemas:

Actualizar la consulta anterior en una instancia no la actualizará para las demás.
Si tenemos tres componentes que utilizan un hook que realiza una petición a un API, obtendremos como resultado al menos una solicitud por cada componente.
Si tenemos varias peticiones en el aire, e intentamos almacenarlas en un store global o si el hook mantiene el estado, terminaremos con un estado fuera de sincronización o peticiones posteriores sobrescribiéndose entre sí.

Una forma de resolver esto es dejar la petición fuera de los hooks y solo ejecutarla en un componente que puede garantizar que será una instancia única(también conocido como un componente singleton, como una página/ruta tal vez). Dependiendo de cómo se usen esos datos, esto a veces puede ser complejo de manejar.

Posibles Soluciones

Entonces, ¿qué podemos hacer? He aquí algunas opciones:

Asegúrate de que los datos que provienen de tu API vayan en contexto o por medio de algún tipo de manejo de estado global, aceptando las múltiples peticiones (potencialmente sobrecargando la API de nuestro servidor)
Al hacer lo anterior + usando una librería como react-singleton-hook, asegúrate de que solo haya un componente con useEffect haciendo la llamada al API, o similar para evitar múltiples peticiones.
Implementar algún tipo de caché de datos (mientras sea posible invalidarlo según sea necesario) para que podamos extraer los datos primero desde esa caché.
Usar React Query o SWR

La Solución Real

La solución real aquí es usar la opción 4. Ambos paquetes han implementado una solución sofisticada para resolver estos problemas y evitar que tengas que hacerlo por ti mismo. El almacenamiento en caché es complejo de implementarlo "bien" y podría tener consecuencias inesperadas si se hace mal, que podría derivar en una aplicación "rota" parcial o totalmente.

Otros Problemas Resueltos

A continuación, se muestran algunos ejemplos de otros problemas que estos paquetes pueden resolver. Se muestran ejemplos de código para cada uno(se usa React Query pero es similar a SWR).

Recuperación de Foco en Ventana(Window Focus Refetching)

Un gran problema que encontramos usualmente con sitios y aplicaciones grandes con JavaScript, es que un usuario puede estar en una pestaña o ventana del browser manipulando datos y luego cambiar a otra de la misma aplicación. El problema aquí es que si no mantenemos nuestros datos actualizados, estos pueden no estar sincronizados. Ambos paquetes resuelven esto volviendo a obtener datos una vez que la ventana tiene el foco activo nuevamente. Si no necesitas este comportamiento, simplemente puedes deshabilitarlo como opción.

    const { data: syncedData } = useQuery(id, id => getSyncedData(id), {
        refetchOnWindowFocus: true /* No necesita especificarse, se activa por defecto */
    })

Reintentar Peticiones, Revalidación y Polling

A veces una petición falla temporalmente, sucede. Ambos paquetes resuelven este problema permitiendo la configuración de reintentos automáticos, por lo que cada vez que detecten un error, reintentarán la cantidad de veces especificada hasta que finalmente retorne un error. Además, puedes usar cualquiera de las dos opciones para hacer un poll de un endpoint de manera constante simplemente estableciendo un intervalo de milisegundos para un refetch/refresh.

Ejemplo de Reintento(Retry)

    const { data: books } = useQuery(id, id => getBooks(id), {
        retry: 5, //intentar 5 veces antes de fallar nuevamente
        retryDelay: 1000 //intentar cada segundo
    })

    /* valores por defecto: {
        retry: 3,
        retryDelay: attemptIndex => Math.min(1000 * 2 ** attemptIndex, 30000)
    }*/

Ejemplo de Polling

    const indexing = useRef(false);
    const { data: searchResults } = useQuery(['search', keyword], (key, keyword) => search(keyword), {
        //obtener datos cada segundo hasta que se haya finalizado el "indexing"
        refetchInterval: indexing.current ? 1000 : undefined,
        //invalidar la caché de consultas después que esta sea exitosa,
        //hasta que se deje de indexar
        onSuccess: async data => {
            if (data.indexing) {
                await queryCache.invalidateQueries(keyword)
            }
        }
    });

    //actualizar nuestra referencia 
    indexing.current = !!searchResults?.indexing;

Mutación con Actualizaciones Optimistas

Supongamos que tienes una lista de usuarios y deseas actualizar la información de uno de ellos, una operación bastante habitual. La mayoría de los usuarios estarán contentos al ver un indicador de progreso cuando el servidor esté trabajando para actualizar a dicho usuario y esperarán a que termine antes de ver la lista actualizada.

Sin embargo, si sabemos cómo se verá la lista de usuarios actualizada localmente (porque el usuario acaba de realizar dicha acción), ¿Realmente necesitamos mostrar un cargador? No, ambos paquetes permiten hacer mutaciones(cambios) en los datos guardados en caché que se actualizarán de inmediato localmente e iniciarán la actualización en el servidor en segundo plano. También se asegurarán de que los datos se vuelvan a recuperar/validar para que sean los mismos una vez se obtenga la respuesta del servidor, y si no, los datos devueltos estarán en su lugar.

Imagina que tenemos una página donde el usuario puede editar su información. Primero, necesitamos obtener los datos del backend.

    const cache = useQueryCache()
    const userCacheKey = ['user', id];
    const { data: user } = useQuery(userCacheKey, (key, id) => {
        return fetch(`/user/${id}`).then(res => res.json());
    });

A continuación, necesitamos configurar una función que permita actualizar los datos del usuario una vez que estos se envíen desde el formulario.

    const [updateUser] = useMutation(
        newUser => fetch(`/user/${id}`, {
            method: 'POST',
            body: JSON.stringify(newUser)
        }).then(res => res.json()),
        ...

Si queremos que nuestros datos se mantengan actualizados con la interfaz de usuario(UI) de manera optimista, se tiene que agregar algunas opciones para dicha mutación. El atributo onMutate establecerá los datos localmente en el caché antes de la actualización real para que la interfaz de usuario no muestre un indicador de progreso. El valor de retorno se usa en caso de error y necesitaremos restablecer al estado anterior.

    onMutate: newUser => {
        cache.cancelQueries(userCacheKey)

        const oldData = cache.getQueryData(userCacheKey)
        cache.setQueryData(userCacheKey, newUser)

        return oldData
    }

Si estamos actualizando de manera optimista, debemos poder manejar los posibles errores y también asegurarnos de que el servidor devuelva los datos esperados. Entonces es necesario agregar dos hooks más a las opciones de mutación. onError usará los datos devueltos por onMutate para que sea factible restablecer el estado anterior. En cambio, onSettled asegura que se vaya a obtener los mismos datos del servidor para que todo esté sincronizado.

    //Reestablece los datos previos cuando surge un error
    onError: oldUser => {
        cache.setQueryData(userCacheKey, oldUser)
    },
    onSettled: () => {
        cache.invalidateQueries(userCacheKey)
    }

Prefetching y Fetching en Segundo Plano

Si se tiene una idea sobre algunos datos que el usuario podría necesitar, se puede usar estos paquetes para obtener esos datos con antelación(prefetch). Para cuando el usuario llega, los datos ya están listos, lo que hace que la transición sea instantánea. Esta implementación puede hacer que tu aplicación se sienta más ligera.

    const prefetchUpcomingStep = async (stepId) => {
        await cache.prefetchQuery(stepId, stepId => fetch(`/step/${stepId}`))
    }

    //más tarde...

    prefetchUpcomingStep('step-137')
    //esto permite obtener los datos antes de llegar a la consulta misma

Como nota adicional, si el usuario ya ha recibido datos, pero es hora de actualizar, los paquetes buscarán obtenerlos en segundo plano y reemplazarán los datos antiguos si y solo si son diferentes. Esto evita mostrar al usuario un indicador de progreso, notificando únicamente si hay algo nuevo, lo que mejora la experiencia de usuario.

Imagina que tenemos un componente que lista novedades al estilo de Twitter y que constantemente está recibiendo nuevas publicaciones.

    const Feed = () => {
        const { data: feed, isLoading, isFetching } = useQuery(id, id => getFeed(id), {
            refetchInterval: 15000
        });

        ...

Podemos notificar a los usuarios que los datos se están actualizando en segundo plano al "escuchar" que isFetching es true, que se activará incluso si hay datos de caché.


    <header>
        <h1>Your feed</h1>
        {
            isFetching && 
            <Notification>
                <Spinner /> loading new posts
            </Notification>
        }
    </header>

Si no se tiene ningún dato en la caché y la consulta está obteniendo datos, podemos escuchar por isLoading como true y mostrar algún tipo de indicador de progreso. Finalmente, si isSuccess es true y recibimos datos, podemos mostrar las publicaciones.

    <FeedContainer>
        {   
            isLoading && <LoadingCard /> 
        }
        {
            feed && isSuccess && feed.posts.map(post => (
                <Post {...post} />
            ))
        }
    </FeedContainer>

Comparación

El autor de React Query hizo un gran trabajo al crear una tabla de comparación para React Query, SWR y Apollo para que puedas ver qué funciones están disponibles. Una gran característica que me gustaría mencionar de React Query sobre SWR es su propio conjunto de herramientas de desarrollo que son realmente útiles para depurar consultas que puedan estar fallando.

Conclusión

Durante mi tiempo como desarrollador, he intentado resolver estos problemas por mí mismo, y si hubiera tenido un paquete como React Query o SWR, habría ahorrado mucho tiempo. Estos problemas pueden ser realmente un reto a resolver y una solución propia puede terminar inyectando errores sutiles en tu aplicación, que pueden ser difíciles de depurar o que requieren mucho tiempo. Afortunadamente, tenemos código abierto(open source) y estas personas fueron generosas al ofrecer sus soluciones robustas para nosotros.

Si te gustaría conocer más sobre los problemas que resuelven estos paquetes y el esfuerzo necesario para resolverlos, Tanner Linsley hizo un gran relato por lo que estuvo experimentando y cómo lo resolvió. Puedes ver su tutorial aquí:

En general, considero que estos paquetes son excelentes adiciones al ecosistema de desarrollo y nos ayudan a escribir mejor software. Me gustaría ver otros frameworks con opciones similares, porque los conceptos que se mencionan aquí son bastante habituales. Espero que esto te haya resultado útil y nos hagas saber alguna estrategia tuya al usar dichas opciones.

PD. ¿Qué hay de GraphQL? 😂

Bueno, muchas de los paquetes GraphQL que existen en realidad incorporaron estos conceptos desde el principio, por lo que si estás usando algo como Apollo o Urql, muy probablemente ya estés obteniendo estas ventajas. Sin embargo, ambas librerías son compatibles con cualquier función que retorne una Promesa, por lo que si tu librería GQL favorita no tiene estas características, intenta usar React Query o SWR. 😁

Este artículo es una traducción al español de su versión en inglés

How to Set Up Environment Variables using JSON files with Rollup and TypeScript

Luis Aviles — Tue, 02 Feb 2021 15:42:21 +0000

In previous posts, I explained How to setup a TypeScript project using Rollup.js from scratch. Also, I covered How to Serve a Single Page Application(SPA) using Rollup.js and Web Dev Server step by step. Then, I covered How to Build a LitElement Application with Rollup.js and TypeScript.

In this article, I'll take the result of those tutorials as a starting point to set up environment variables using JSON files.

Environment Variables

Reading environment variables is very common in software development. It's a helpful way to cover security concerns and even provides the convenience to set configuration parameters in your application.

For example, in the Node.js world, you may need to set the port number to serve your application. For example:

const app = require('http').createServer((req, res) => res.send('Hello world'));
const PORT = process.env.PORT || 3000;

app.listen(PORT, () => {
  console.log(`Server is ready to listen on port ${PORT}`);
});

In the previous code, the app will read the value of PORT through process.env.PORT. If the value doesn't exist, it will take 3000 as a fallback.

JSON Modules

In today's JavaScript world, it's possible to read JSON Modules as follows:

import config from '../../config.json';

Also, recent versions of Node.js enables the use of --experimental-json-module flag for the module to work.

Let's explore a practical way to add the same support to the current Single-Page Application which is based on TypeScript, LitElement, Rollup.js, and Web Dev Server.

Project Setup

Base Project

Let's create a clone or download the project seed before adding the new configurations and tools:

git clone https://github.com/luixaviles/typescript-rollup.git
cd typescript-rollup/
git checkout tags/03-build-litelement -b 04-env-config-json

The previous commands will download the project and create a new branch 04-env-config-json to get started.

Source Code Files

The previous project already contains a set of files and configurations ready to configure and support JSON Modules. Open it with your favorite code editor and take a look at the project structure:

|- typescript-rollup
    |- src/
        |- math/
            |- math.ts
            |- index.ts
        |- string/
            |- string.ts
            |- index.ts
        |- main.ts
    |- index.html
    |- package.json
    |- rollup.config.js
    |- tsconfig.json
    |- web-dev-server.config.js

Installing Rollup Plugins

Since the Single-page application considers Rollup.js as the module bundler, we'll need to install a couple of node modules first:

npm install --save-dev @rollup/plugin-json @web/dev-server-rollup

@rollup/plugin-json will be in charge to convert .json files to ES6 modules.
@web/dev-server-rollup is an adapter for using rollup plugins in Web Dev Server, which is used to "serve" the web application in development mode.

The package.json file should have the new dependencies listed as follows:

{
  ...
  "devDependencies": {
    ...
    "@rollup/plugin-json": "^4.1.0",
    "@web/dev-server-rollup": "^0.3.2",
    ...
  },
}

Reading the JSON Configuration

Let's add the following env-config.json file into the root of the project:

{
  "environment": "production",
  "host": {
    "protocol": "http",
    "hostname": "localhost",
    "port": 8080
  }
}

Of course, you can set your variables according to the requirements: access keys, platform, etc.

Since you may have sensitive data in that file, it should not be versioned in any case. It's good practice to add it to the .gitignore file:

# Environment variables
env-config.json

Also, you can provide a env-config.json.example file as an example so that developers, Dev Ops, or any member of the team can create a configuration file from it:

{
  "environment": "development",
  "host": {
    "protocol": "http",
    "hostname": "localhost",
    "port": 8080
  }
}

Creating the TypeScript Model

It's time to define the TypeScript model for our configurations. First, let's create a src/environment/environment-model.ts:

// environment-model.ts
export interface Host {
  protocol: string;
  hostname: string;
  port: number | string;
}

export interface EnvConfig {
  environment: string;
  host: Host;
}

Next, create a src/environment/environment.ts file with the following content:

import { EnvConfig } from './environment-model';
import envConfig from '../../env-config.json'; 

export const env = envConfig as EnvConfig;

From now on, the configurations will be available in the env variable.

TypeScript Configuration

You may see a couple of compilation errors from TypeScript after adding the environment.ts file. To avoid them, it's required to add new compiler options in the tsconfig.json file:

{
  "compilerOptions": {
    ...
    "resolveJsonModule": true,
    "allowSyntheticDefaultImports": true
  }
}

Why are these changes needed?

The resolveJsonModule flag allows the compiler to include modules with .json extension.
The allowSyntheticDefaultImports flag allows default imports from modules with no default export. As the documentation says, it's just type checking.

Reading Configuration Values

Let's read the configuration values to be rendered into an existing web component. Update the main.ts file with the following content:

// main.ts
import { LitElement, html, customElement, css, property } from 'lit-element';
import { env } from './environment/environment';

@customElement('comp-main')
export class CompMain extends LitElement {

    static styles = css`
    :host {
        display: flex;
    }
    `;

    @property({ type: String }) message: string = 'Welcome to LitElement';

    render() {
        return html`
        <div>
            <h1>${this.message}</h1>
            <span>This App uses:</span>
            <ul>
                <li>TypeScript</li>
                <li>Rollup.js</li>
                <li>es-dev-server</li>
            </ul>
            <span>Running environment: ${env.environment}</span>
            <ul>
                <li>Protocol: ${env.host.protocol}</li>
                <li>Hostname: ${env.host.hostname}</li>
                <li>Port: ${env.host.port}</li>
            </ul>
        </div>
        `;
    }
}

Just pay attention to the import line: import { env } from './environment/environment'. Then the EnvConfig object (TypeScript model) will be available as the env variable.

Rollup Configuration

As stated above, the project is already configured and uses Rollup as the module bundler. Let's move forward to allow reading the JSON content for the build.

// rollup.config.js
import merge from 'deepmerge';
import { createSpaConfig } from '@open-wc/building-rollup';
import json from '@rollup/plugin-json';

const baseConfig = createSpaConfig({
  developmentMode: process.env.ROLLUP_WATCH === 'true',
  injectServiceWorker: false
});

export default merge(baseConfig, {
  // any <script type="module"> inside will be bundled by rollup
  input: './index.html',
  plugins: [
    json()
  ]
});

For every building process, the new json() plugin will be in charge to process the .json files. You can call any other Rollup plugin in the plugins array.

Web Dev Server Configuration

If you try to serve the application at this point, you'll find a blank page and some errors in the browser's console:

Failed to load module script: The server responded with a non-JavaScript MIME type of "application/json". 
Strict MIME type checking is enforced for module scripts per HTML spec.

That is because we configured Rollup for the build process only. However, for serving the app in a "development mode", we're using Web Dev Server.

Let's apply a couple of changes in the web-dev-server.config.js file to fix it:

// web-dev-server.config.js

const { rollupAdapter } = require('@web/dev-server-rollup');
const json =  require('@rollup/plugin-json');

module.exports = {
    port: 8000,
    nodeResolve: true,
    open: true,
    watch: true,
    appIndex: 'index.html',
    mimeTypes: {
      // serve all json files as js
      '**/*.json': 'js'
    },
    plugins: [rollupAdapter(json())],
  };

Let's explain what's happening in that code:

The @web/dev-server-rollup package allows using Rollup plugins in Web Dev Server.
Instead of using json() plugin directly, it needs to be passed through the rollupAdapter function first.

When you're done with those changes, run npm run start again to see the final result.

Source Code of the Project

Find the complete project in this GitHub repository: typescript-rollup. Do not forget to give it a star ⭐️ and play around with the code.

Feel free to reach out on Twitter if you have any questions. Follow me on GitHub to see more about my work.

Introduction to RxJS

Luis Aviles — Mon, 25 Jan 2021 23:18:06 +0000

RxJS is becoming more and more popular these days. It's used in a wide range of applications and frameworks have included it as part of their implementations.

The library's implementation is constantly evolving and the next major version, RxJS 7, is close to being released.

What is RxJS?

RxJS is a popular library with more than 20 Million downloads per week on average. According to the official website:

RxJS is a library for composing asynchronous and event-based programs by using observable sequences...

However, there's another popular definition of this library:

Think of RxJS as Lodash for events.

The original implementation was based on JavaScript (Reactive Programming library for JavaScript = RxJS).

The TypeScript support

It's interesting to know that the RxJS project is using TypeScript actively and it helped to find bugs when the library was migrating from JavaScript.

In the next section, you can find more articles to learn and keep improving your skills through RxJS.

More about RxJS

The This Dot Blog has been publishing several articles around RxJS lately. Find a list of useful resources below to keep up-to-date with this technology:

How to Build a LitElement Application with Rollup.js and TypeScript

Luis Aviles — Wed, 20 Jan 2021 04:47:03 +0000

In this article, I'll take the result of both tutorials as a starting point to integrate LitElement into the game to write the first Web Components through the latest web standards and powerful TypeScript features.

Project Setup

Prerequisites

You'll need to have installed the following tools in your local environment:

Node.js. Preferably the latest LTS version.
A package manager. You can use either NPM or Yarn. This tutorial will use NPM.

Initialize the Project

Let's create a clone or download the project seed before adding the new configurations and tools:

git clone https://github.com/luixaviles/typescript-rollup.git
cd typescript-rollup/
git checkout tags/02-serve-spa -b 03-litelement-app

The previous commands will download the project and create a new branch 03-litelement-app to get started.

Source Code Files

The previous project already contains a set of files and configurations ready to go with TypeScript and Rollup. Open it with your favorite code editor and take a look at the project structure:

|- typescript-rollup
    |- src/
        |- math/
            |- math.ts
            |- index.ts
        |- string/
            |- string.ts
            |- index.ts
        |- app.ts
    |- index.html
    |- package.json
    |- rollup.config.js
    |- tsconfig.json
    |- web-dev-server.config.js

Installing LitElement and lit-html

The Single-Page Application will be based on LitElement, hence we'll need to install some development dependencies to the project:

npm install --save lit-element lit-html

LitElement will be the main tool for writing the class-based web components for the application.
lit-html is an efficient and extensible HTML templating library.

Your package.json file should have the new dependencies listed as follows:

{
  ...

  "dependencies": {
    "lit-element": "^2.4.0",
    "lit-html": "^1.3.0"
  }
}

Rollup Configuration

The project is already configured and it uses Rollup as the module bundler. Verify the content of rollup.config.js as follows:

// rollup.config.js
import merge from 'deepmerge';
import { createSpaConfig } from '@open-wc/building-rollup';

const baseConfig = createSpaConfig({
  developmentMode: process.env.ROLLUP_WATCH === 'true',
  injectServiceWorker: false
});

export default merge(baseConfig, {
  // any <script type="module"> inside will be bundled by rollup
  input: './index.html'
});

The baseConfig content will be generated from createSpaConfig function, which is defined in @open-wc/building-rollup package.

When createSpaConfig is used, a service worker is generated using Workbox. However, the service worker is injected into the index.html file when the injectServiceWorker flag is enabled.

The Serve and Build Scripts

Now it's time to pay attention to the package.json file. It already defines a set of scripts to both serve and build the project:

{
  ...
  "scripts": {
    "start": "concurrently --kill-others --names tsc,web-dev-server \"npm run tsc:watch\" \"web-dev-server --config web-dev-server.config.js\"",
    "build": "rimraf dist && tsc && rollup -c rollup.config.js"
  },
}

Let's explain what's going to happen with those scripts:

"tsc:watch" is the script to start with the compilation process through tsc, which is the TypeScript compiler. The --watch param stands for a compiler option to run the compiler in watch mode(it trigger recompilation on file changes).
"start" is the script to add the execution of some commands in parallel: npm run tsc:watch and web-dev-server that includes some CLI flags through a configuration file.
- You already noted that concurrently command is called first!
- The --kill-others parameter will kill all the invoked commands if one dies(either tsc or web-dev-server).

It's important to note that any time you need to configure or customize the web-dev-server behavior, the web-dev-server.config.js file should be updated.

TypeScript Configuration

The TypeScript configuration is defined in tsconfig.json file. It already contains some relevant content for the compilation process:

{
  "compilerOptions": {
    "target": "es2018",                          
    "module": "esnext",
    "moduleResolution": "node",                     
    "noEmitOnError": true,
    "lib": ["es2017"],                            
    "strict": true,  
    "esModuleInterop": false,                 
    "outDir": "out-tsc",
    "rootDir": "./"
  }
  ,
  "include": ["./src/**/*.ts"]
}

However, it would be good to add some capabilities to start working with LitElement. To do that, let's add the experimentalDecorators support along with the dom library(to be included in the compilation process). The final state of this fill would be:

{
  "compilerOptions": {
    "target": "es2018",                          
    "module": "esnext",
    "moduleResolution": "node",                     
    "noEmitOnError": true,
    "lib": ["es2017", "dom"],                            
    "strict": true,  
    "esModuleInterop": false,                 
    "outDir": "out-tsc",
    "rootDir": "./",
    "experimentalDecorators": true,
  }
  ,
  "include": ["./src/**/*.ts"]
}

"experimentalDecorators": true provides the Decorators support for TypeScript. It involves the use of annotations and meta-programming syntax for class declarations and attributes. LitElement support them too. For example:

import {LitElement, html, customElement, property} from 'lit-element';

@customElement('my-custom-element')
class MyCustomElement extends LitElement {

 @property()
 propName = 'value';

 render() {
   return html`Hello world`;
 }
}

Both @customElement() and @property() decorators will make the web components definition compact.

"lib": ["es2017", "dom"] as the name states, provides a configuration with a list of library files to be included in the compilation. Take a look at the list of possible values for this parameter in the official documentation.

Just to clarify, without adding dom into lib configuration, you may find several errors at compilation time. For example:

[tsc] node_modules/lit-element/lib/css-tag.d.ts(16,19): error TS2304: Cannot find name 'CSSStyleSheet'.
[tsc] node_modules/lit-element/lib/decorators.d.ts(46,108): error TS2304: Cannot find name 'HTMLElement'.
[tsc] node_modules/lit-element/lib/decorators.d.ts(203,47): error TS2304: Cannot find name 'AddEventListenerOptions'.
[tsc] node_modules/lit-element/lit-element.d.ts(105,49): error TS2304: Cannot find name 'Element'.
[tsc] node_modules/lit-element/lit-element.d.ts(105,59): error TS2304: Cannot find name 'DocumentFragment'.
[tsc] node_modules/lit-element/lit-element.d.ts(140,45): error TS2304: Cannot find name 'ShadowRoot'.
[tsc] node_modules/lit-html/lib/dom.d.ts(23,49): error TS2304: Cannot find name 'Node'.
[tsc] node_modules/lit-html/lib/parts.d.ts(137,29): error TS2304: Cannot find name 'EventTarget'.
[tsc] node_modules/lit-html/lib/render.d.ts(32,69): error TS2304: Cannot find name 'DocumentFragment'.
[tsc] node_modules/lit-html/lib/template-result.d.ts(29,27): error TS2304: Cannot find name 'HTMLTemplateElement'.
[tsc] node_modules/lit-html/lib/template.d.ts(64,42): error TS2304: Cannot find name 'Comment'.

Using LitElement

Adding the Web Component Definition

It's time to add some TypeScript code with the first Web Component through LitElement. Let's create a new file src/main.ts with the following content:

import { LitElement, html, customElement, css, property } from 'lit-element';

@customElement('comp-main')
export class CompMain extends LitElement {

    static styles = css`
      :host {
          display: flex;
      }
    `;

    @property({ type: String }) message: string = 'Welcome to LitElement';

    render() {
        return html`
        <div>
            <h1>${this.message}</h1>
            <span>This App uses:</span>
            <ul>
                <li>TypeScript</li>
                <li>Rollup.js</li>
                <li>es-dev-server</li>
            </ul>
        </div>
        `;
    }
}

The previous code defines a new component for your project. You can use it in your template files as if it were a new member of the HTML vocabulary:

<comp-main></comp-main>

Also, it supports a custom attribute too!

<comp-main message="Welcome to the TypeScript and LitElement world"></comp-main>

Update the index.html File

At this point, the index.html file of the project defines almost the same content as the Web Component. Let's change the <body> content a little bit:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Single Page Application</title>
</head>
<body>
    <comp-main></comp-main>
    <script type="module" src="./out-tsc/src/main.js"></script>
</body>
</html>

Two important things are happening now:

The <comp-main></comp-main> element will render the brand new component
The <script> tag will load the content of the file that contains the component definition.

That's it! You already have a Single-Page Application based on LitElement and TypeScript.

Running the Application

Run the App in Development mode

Serve the application (development mode) using the following command:

npm run start

You should see an output with the host and port:

Web Dev Server started...
[web-dev-server] 
[web-dev-server]   Root dir: /Users/luixaviles/projects/typescript-rollup
[web-dev-server]   Local:    http://localhost:8000/
[web-dev-server]   Network:  http://192.168.1.2:8000/
[web-dev-server]

The default browser will be opened to display the index.html content.

Run the Build Version

First, run the build command:

npm run build

This will generate a dist folder with the following content:

|- dist/
    |- b8c5e46a.js
    |- index.html
    |- ... other scripts

A simple way to serve these files locally would be to use the http-server tool (a command-line http server):

http-server dist/ -o

The output of this command will show you the host and the port you need to use to access the build version of the app:

Starting up http-server, serving dist/
Available on:
  http://127.0.0.1:8080
  http://192.168.1.2:8080
Hit CTRL-C to stop the server
open: http://127.0.0.1:8080

Source Code of the Project

Find the complete project in this GitHub repository: typescript-rollup. Do not forget to give it a star ⭐️ and play around with the code.

Feel free to reach out on Twitter if you have any questions. Follow me on GitHub to see more about my work.

How to Serve a Single Page Application (SPA) using Rollup.js and Web Dev Server

Luis Aviles — Wed, 20 Jan 2021 04:44:06 +0000

In a previous post, I explained How to setup a TypeScript project using Rollup.js. In that article, I covered the necessary steps to have a Project Setup ready to generate a build using TypeScript and Rollup configurations.

So let's take that project as a starting point to serve a Single-page Application using modern web tools.

What is a SPA (Single-page Application)?

According to MDN Documentation:

An SPA (single-page application) is a web app implementation that loads only a single web document, and then updates the body content of that single document via JavaScript APIs such as XMLHttpRequest and Fetch when different content is to be shown.

A single-page application allows updating only some portions of the current page instead of doing a page refresh. Think about some applications you use every day:

Gmail
Facebook
Twitter
LinkedIn

All of these applications have been built with the user experience in mind along with a good loading speed and navigation between pages.

There are very good reasons to keep building applications following the SPAs approach.

What is Web Dev Server?

Web Dev Server, as its name states, it's a web server for development. It helps development using native browser features like ES modules. It has a plugin architecture for code transformations.

Web Dev Server is the successor of es-dev-server

It's worth mentioning that Web Dev Server allows configuring auto-reload on file changes along with efficient browser caching for faster reloads. It's configurable and supports rollup plugins too!

Project Setup

Prerequisites

You'll need to have installed the following tools in your local environment:

Node.js. Preferably the latest LTS version.
A package manager. You can use either NPM or Yarn. This tutorial will use NPM.

Initialize the Project

Let's create a clone or download the project seed before adding the new configurations and tools:

git clone https://github.com/luixaviles/typescript-rollup.git
cd typescript-rollup/
git checkout tags/01-setup-ts-rollup -b 02-serve-spa

The previous commands will download the project and create a new branch 02-serve-spa to get started.

Source Code Files

Once you have the project ready, open it with your favorite code editor and pay attention to the current project structure:

|- typescript-rollup
    |- src/
        |- math/
            |- math.ts
            |- index.ts
        |- string/
            |- string.ts
            |- index.ts
        |- app.ts
    |- package.json
    |- rollup.config.js
    |- tsconfig.json

Installing Web Dev Server and Concurrently

Let's add some development dependencies to the project.

Install Web Dev Server

npm install --save-dev @web/dev-server

As I mentioned before, Web Sev Server will be the main tool to configure and run our project this time.

Also, if you already know es-dev-server tool, used actively on the Open Web Components initiative, you'll understand that this project migrated to Modern Web website. That does not mean anything other than this new tool continues to be actively developed and can be used in any JavaScript project (TypeScript included ;-)).

Install Concurrently tool

npm install --save-dev concurrently

If you are familiar with any command-line tool, you may have wanted to run commands in parallel.

Concurrently has the same goal. However, it's hard to keep track of every command output and concurrently allows you to run any command you want. It's possible to kill all of them if anyone fails.

TypeScript Configuration

In this case, the tsconfig.json file will remain the same, without any changes:

{
  "compilerOptions": {
    "target": "es2018",                          
    "module": "esnext",
    "moduleResolution": "node",                     
    "noEmitOnError": true,
    "lib": ["es2017"],                            
    "strict": true,  
    "esModuleInterop": false,                 
    "outDir": "out-tsc",
    "rootDir": "./"
  }
  ,
  "include": ["./src/**/*.ts"]
}

Remember, this file is required to be present in the root of any TypeScript project.

Rollup Configuration

The project is configured to use Rollup as the module bundler. It's possible to run it through command-line parameters. However, if you're looking for advanced functionality, you can consider a rollup.config.js file:

import merge from 'deepmerge';
import { createBasicConfig } from '@open-wc/building-rollup';

const baseConfig = createBasicConfig();

export default merge(baseConfig, {
  input: './out-tsc/src/app.js',
  output: {
      dir: 'dist',
  }
});

This file contains a basic configuration. I's needed to set the input files and the output directory for the build.

Since we intend to compile a Single-page application now, it will be necessary to apply some changes:

import merge from 'deepmerge';
import { createSpaConfig } from '@open-wc/building-rollup';

const baseConfig = createSpaConfig({
  developmentMode: process.env.ROLLUP_WATCH === 'true',
  injectServiceWorker: false
});

export default merge(baseConfig, {
  // any <script type="module"> inside will be bundled by Rollup
  input: './index.html'
});

The baseConfig content will be generated from createSpaConfig, which is defined in @open-wc/building-rollup package.

When createSpaConfig is used, a service worker is generated using Workbox. However, the service worker is injected into the index.html file when injectServiceWorker is enabled.

HTML file as an Input

Once the input parameter is set using an index.html file, any module defined as part of it will be bundled by Rollup. This content will be injected into the HTML file result.

The index.html File

Let's create an index.html file into the root folder with the following content:

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>My Single Page Application</title>
</head>
<body>
    <h1>Welcome to your Single Page Application</h1>
    <span>This App uses:</span>
    <ul>
        <li>TypeScript</li>
        <li>Rollup.js</li>
        <li>es-dev-server</li>
    </ul>
    <script type="module" src="./out-tsc/src/app.js"></script>
</body>
</html>

We can say the content of this file is common. However, the most important line would be the reference to the app.js file:

<script type="module" src="./out-tsc/src/app.js"></script>

Let's explain what is happening there:

As you will remember, the tsconfig.json file sets "outDir": "out-tsc" and that means the TypeScript compiler will generate the output files in ./out-tsc folder.
Then, the index.html file does reference to the entry point of the source code, the compiled version of the ./src/app.ts file.
When the Rollup configuration starts to build the app, it will take the module defined in index.html file to generate a bundle ready for it.

Adding Serve and Build Scripts

If you pay attention to the package.json file, it already defines a script to generate the build:

...
"scripts": {
    "build": "rimraf dist && tsc && rollup -c rollup.config.js"
},
...

The change we introduced into the rollup.config.json file doesn't affect the build process.

Now let's move forward with the addition of some scripts to "serve" the application:

... 
"scripts": {
    "tsc:watch": "tsc --watch",
    "start": "concurrently --kill-others --names tsc,web-dev-server \"npm run tsc:watch\" \"web-dev-server --app-index index.html --node-resolve --open --watch\"",
    "build": "rimraf dist && tsc && rollup -c rollup.config.js"
},
...

"tsc:watch" is the script to start with the compilation process through tsc, which is the TypeScript compiler. The --watch param stands for a compiler option to run the compiler in watch mode(it triggers recompilation on file changes).
"start" is the script to add the execution of some commands in parallel: npm run tsc:watch and web-dev-server that includes some CLI flags.
- You already noted that concurrently command is called first!
- The --kill-others parameter will kill all the invoked commands if one dies (either tsc or web-dev-server).

Think for a while how the "start" command is going to look if we're planning to add more configurations in the future: a script that is hard to read and maintain, of course.

Adding the web-dev-server.config.js File

The alternative option to include the CLI flags as parameters is the creation of the web-dev-server.config.js file.

The file extension can be .js, .cjs or .mjs. A .js file will be loaded as an es module or common js module based on your version of node, and the package type of your project.

By default, the Web Dev Server looks at the configuration file in the current working directory.

Let's create the web-dev-server.config.js file in the root folder:

// web-dev-server.config.js

module.exports = {
    port: 8000,
    nodeResolve: true,
    open: true,
    watch: true,
    appIndex: 'index.html',
};

This file now contains the same options we used in the start script with the addition of a custom port number: port: 8000, which can be configured now.

For the sake of simplicity, let's update the start script with a reference to the new configuration file:

... 
"scripts": {
    ...
    "start": "concurrently --kill-others --names tsc,web-dev-server \"npm run tsc:watch\" \"web-dev-server --config web-dev-server.config.js\"",
    ...
},
...

That's it! You're ready to serve your first application using:

npm run start

You should see the following output:

Web Dev Server started...
[web-dev-server] 
[web-dev-server]   Root dir: /Users/luixaviles/projects/typescript-rollup
[web-dev-server]   Local:    http://localhost:8000/
[web-dev-server]   Network:  http://192.168.1.2:8000/
[web-dev-server]

Also, your default browser will be opened to display the index.html content.

On the right side (when you open the Developer Tools), you'll see the output of the main script file. That is proof that the module is running correctly when the SPA is loaded.

Running the Build

The script is ready and doesn't need an update. Execute the following command:

npm run build

This will generate a dist folder with the following content:

|- dist/
    |- 7b857f5b.js
    |- index.html
    |- ... other scripts

A simple way to serve these files locally would be to use the http-server tool (a command-line http server):

http-server dist/ -o

The output of this command will show you the host and the port you need to use to access the build version of the app:

Starting up http-server, serving dist/
Available on:
  http://127.0.0.1:8080
  http://192.168.1.2:8080
Hit CTRL-C to stop the server
open: http://127.0.0.1:8080

I suggest you review the content of dist/ files and make sure you have http-server installed before running the latest command.

Source Code of the Project

Find the complete project in this GitHub repository: typescript-rollup. Do not forget to give it a star ⭐️ and play around with the code.

Feel free to reach out on Twitter if you have any questions. Follow me on GitHub to see more about my work.

How to Setup a TypeScript project using Rollup.js

Luis Aviles — Wed, 20 Jan 2021 04:39:04 +0000

A couple of months ago, I started to work through web standards, Rollup.js, and TypeScript. It’s my first experience using Rollup although I’ve been working with TypeScript on different projects and using it along with other frameworks like Angular.

So far, it has been a good experience in terms of performance and tools integration.

What is Rollup?

In words of the official documentation:

Rollup is a module bundler for JavaScript which compiles small pieces of code into something larger and more complex, such as a library or application...

What does that mean? Let’s start by saying that JavaScript improved drastically since ES6, and now it’s possible to define small portions of code that can be shared using two magical keywords: import and export. This specification is supported by modern browsers and tools. Rollup allows writing a future-proof code using the new module system without missing the compatibility with other module systems like CommonJS, AMD, and others.

Rollup also is considered as the "Next-generation ES module bundler", an alternative to the very known bundler Webpack.

Project Setup

Let's start building a small application based in TypeScript. Our first goal would be to compile and build it using Rollup.

Prerequisites

You need to install the following tools in your local environment:

Node.js. Preferably the latest LTS version.
A package manager. You can use either NPM or Yarn. This tutorial will use NPM.

Initialize the Project

You'll need a new folder to get started, you can create it from a command-line interface or from your favorite IDE/Code Editor:

mkdir typescript-rollup
cd typescript-rollup

Let's start running the first command inside that folder to create the package.json file and have an initialized project. This will be useful to manage and install packages later.

npm init -y

The previous command will create the package.json with some defaults. You can edit that file later according to your needs:

{
  "name": "typescript-rollup",
  "version": "1.0.0",
  "description": "A basic TypeScript project built using Rollup.js",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
    "type": "git",
    "url": "git+https://github.com/luixaviles/typescript-rollup.git"
  },
  "keywords": [],
  "author": "Luis Aviles <@luixaviles>",
  "license": "MIT",
  "bugs": {
    "url": "https://github.com/luixaviles/typescript-rollup/issues"
  },
  "homepage": "https://github.com/luixaviles/typescript-rollup#readme"
}

Use npm init only if you want to set your preferences with the interactive mode of the command.

Source Code Files

Let's create a library to perform basic Math operations and perform strings processing. The project will contain the following source files:

|- typescript-rollup
    |- src/
        |- math/
            |- math.ts
            |- index.ts
        |- string/
            |- string.ts
            |- index.ts
        |- app.ts

Add the Math operations in math/math.ts file:

export function add(x: number, y: number): number {
  return x + y;
}

export function substract(x: number, y: number): number {
  return x - y;
}

Then, the strings operations will be defined in string/string.ts file:

export const toLowerCase = (input: string): string => {
  return input.toLocaleLowerCase();
};

export const toUpperCase = (input: string): string => {
  return input.toUpperCase();
};

In the latest file, we're exporting a function using the ES6 Arrow function expression.

In order to import related functions regardless of the filenames, we can create the index.ts files in both directories:

// src/math/index.ts
export { add, substract } from './math';

// src/string/index.ts
export { toLowerCase, toUpperCase } from './string';

Pay attention to the src/app.ts file:

import { add, substract } from './math';

const x = 20;
const y = 10;

console.log(`${x} + ${y} = ${add(x, y)}`)
console.log(`${x} - ${y} = ${substract(x, y)}`);

The app.ts file is the starting point of our application. Also, take a look at the first import line. We don't need to import those functions from ./math/math.ts file, since all of them have been exported in /math/index.ts file. Again, this is a convenient way to organize the library content using TypeScript.

Installing Rollup and TypeScript

Let's continue installing Rollup and TypeScript as development dependencies:

npm install --save-dev rollup typescript

Additional tools are needed:

@open-wc/building-rollup, as a rollup plugin for integration between Rollup.js and TypeScript,
rimraf, which is the UNIX command rm -rf for Node.js
deepmerge, a tool to merge enumerable properties or more objects deeply.

Use a single command to have all of them as new dependencies:

npm install --save-dev @open-wc/building-rollup rimraf deepmerge

TypeScript Configuration

For every TypeScript project, it's required to create the tsconfig.json file. It indicates that the directory is the root of a TypeScript project.

tsc --init
message TS6071: Successfully created a tsconfig.json file.

Let's apply some changes to that file:

{
  "compilerOptions": {
    "target": "es2018",                          
    "module": "esnext",
    "moduleResolution": "node",                     
    "noEmitOnError": true,
    "lib": ["es2017"],                            
    "strict": true,  
    "esModuleInterop": false,                 
    "outDir": "out-tsc",
    "rootDir": "./"
  }
  ,
  "include": ["./src/**/*.ts"]
}

The most important thing here is the outDir option since the value says where the JavaScript files will be generated. Also, the include parameter will list a set of patterns of the files to be included in the compilation.

Learn more about the compilerOptions and the tsconfig.json file in TsConfig Reference documentation.

Rollup Configuration

It's time to configure the module bundler tool: Rollup. You can use Rollup from a command-line interface along with parameters. However, you can provide a configuration file to simplify the usage and provide advanced functionality.

Let's create a rollup.config.js file with the next content:

// rollup.config.js

import merge from 'deepmerge';
import { createBasicConfig } from '@open-wc/building-rollup';

const baseConfig = createBasicConfig();

export default merge(baseConfig, {
  input: './out-tsc/src/app.js',
  output: {
      dir: 'dist',
  }
});

Take a look at the documentation if you're curious about the different ways to use these configuration files. Also, find an example of the TypeScript support provided by @open-wc/building-rollup package.

The Build script

In the package.json file, define a script to compile the input files and run the previous configurations:

{
  ...
  "scripts": {
    "build": "rimraf dist && tsc && rollup -c rollup.config.js"
  },
  ...
}

Here's what is happening with the script:

rimraf dist, will make sure to clean up the output directory for Rollup: dist
tsc, will run the TypeScript compiler through the configurations defined in tsconfig.json file. The output content will be located in the ./out-tsc directory, as defined in the TypeScript configuration file.
rollup -c rollup.config.json, will run Rollup and take the ./out-tsc directory as input and put the result in a dist folder. Those configurations are defined in the rollup.config.js file.

Generate the Build and Run the App

Run the build script using:

npm run build

You'll have the following output:

npm run build

> typescript-rollup@1.0.0 build /Users/luixaviles/projects/github/typescript-rollup
> rimraf dist && tsc && rollup -c rollup.config.js

./out-tsc/src/app.js → dist...
created dist in 300ms

Finally, run the single file generated as a result of the build script:

node dist/7b857f5b.js 
20 + 10 = 30
20 - 10 = 10

You'll see the expected output.

The Final Project Structure

You should have the following project structure, including the source code files and configurations:

|- typescript-rollup
    |- src/
        |- math/
            |- math.ts
            |- index.ts
        |- string/
            |- string.ts
            |- index.ts
        |- app.ts
    |- package.json
    |- rollup.config.js
    |- tsconfig.json

Alternatives to integrate Rollup and TypeScript

In case you're planning to build a SPA project(Single Page Application), you can use the createSpaConfig in Rollup configuration. Also, you can install the @rollup/plugin-typescript for seamless integration between Rollup and TypeScript.

// rollup.config.js
import merge from 'deepmerge';
import { createSpaConfig } from '@open-wc/building-rollup';
import typescript from '@rollup/plugin-typescript';

const baseConfig = createSpaConfig();

export default merge(baseConfig, {
  input: './index.html',
  plugins: [typescript()],
});

The @rollup/plugin-typescript will load any compilerOptions from the tsconfig.json file by default. However, there's an option to override those configurations:

// rollup.config.js

...
export default merge(baseConfig, {
  input: './index.html',
  plugins: [typescript({target: "es5"})],
});

In case you prefer a simple configuration, then you can set the rollup.config.js file using only this plugin:

// rollup.config.js
import typescript from '@rollup/plugin-typescript';

export default {
  input: 'src/app.ts',
  output: {
    dir: 'output',
    format: 'cjs',
  },
  plugins: [typescript()],
};

Or even better, use the open-wc project generator for an automated setup through Rollup, TypeScript, and even Web Components.

Source Code of the Project

Find the complete project in this GitHub repository: typescript-rollup. Do not forget to give it a star ⭐️ and play around with the code.

You can follow me on Twitter and GitHub to see more about my work.