DEV Community: Maroun Baydoun

Migrating a React codebase to web components

Maroun Baydoun — Mon, 02 Aug 2021 17:05:08 +0000

I recently migrated a browser extension from React to web components. This post describes my observations, learnings and pain points. Anything mentioned applies to native web components only. Third-party libraries such as stencil and lit offer a different set of solutions.

What does the extension do?

The extension controls the playback of Youtube™ videos from any tab in the browser. The user can assign shortcuts to play/pause videos even when the browser is in the background.

You can install the extension on Chrome and check the code on Github.

Why did I migrate?

The extension was originally written using vanilla JavaScript in 2015. As the codebase grew in complexity, it became difficult to maintain the UI. I wanted a tiny framework to help me organise the interface into components. I chose hyperapp for its small bundle size and seemingly easy API. It wasn’t that straightforward to learn after all and the documentation was lacking at the time.

A few months later, I migrated to React. I wanted a familiar library that I didn’t need to relearn from scratch. I was finally happy with the quality of the code. The more I thought about it, however, the more I realised I was over-engineering my solution.

Do I really need to ship two rather large packages, react and react-dom? The answer was no, even though extensions are loaded locally and package size is not a major concern. The other problem was minification. While minified code is not prohibited, it could delay the review process on some platforms.

I needed a light-weight solution that doesn’t rely on external libraries. Enter web components.

Overview of web components

Web components are a set of four standards that have very good browser support:

Custom HTML elements
Shadow DOM
Templates
EJS modules

Comparing web components to React

The following is a list of things I’ve learned during the migration.

Custom elements are classes

Since the release of hooks, I have completely stopped writing class components in React. Custom elements can only be declared as classes however. They have specific methods to hook (no pun intended) into the lifecycle of the element. In that sense, they are quite similar to class components in React. One of the biggest differences is the lack of a render method.

Back to imperative programming

Building React components boils down to describing the end result and letting the library take care of the rest. This is done in the render method of class components or as the returned result of functional ones. Custom elements, on the other hand, require direct DOM manipulation to achieve the same result. DOM Elements are queried, created, inserted and modified.

React:

const CapitalisedText = ({ text }) => {
  return <div>{text.toUpperCase()}</div>;
};

Web components:

class CapitalisedText extends HTMLElement {
  connectedCallback() {
    const text = this.getAttribute("text");
    const div = document.createElement("div");
    div.appendChild(document.createTextNode(text.toUpperCase()));

    this.appendChild(div);
  }
}

No binding in templates

Templates are not equivalent to the rendering blocks of React components. It is not possible to pass and render JavaScript data. Nor is it possible to run conditions or loops. All of that has to happen in the custom element lifecycle methods.

A template defined in the document:

<template id="capitalised-text-template">
  <div></div>
</template>

The web component consumes the template but has to do the necessary DOM updates:

class CapitalisedText extends HTMLElement {
  connectedCallback() {
    const template = document.querySelector("#capitalised-text-template");
    this.appendChild(template.content.cloneNode(true));

    const text = this.getAttribute("text");
    const div = this.querySelector("div");
    div.appendChild(document.createTextNode(text.toUpperCase()));
  }
}

Out of the box css scoping

Many solutions exist to scope css in React components. CSS modules, different CSS-in-JS libraries etc. Using the shadow dom in custom elements comes with out-of-the-box support for that. Styles defined in the custom element don’t leak out to the rest of the document, and styles declared elsewhere in the document don’t leak into the custom element. It is a powerful feature when writing reusable components but can be restrictive in other scenarios. It is always possible to write custom elements without shadow DOM however.

Using css modules with React to avoid style collisions:

import styles from "./stlyle.css";

const CapitalisedText = ({ text }) => {
  return <div className={styles.text}>{text.toUpperCase()}</div>;
};

Using the shadow DOM in the web component to encapsulate styles:

<template id="capitalised-text-template">
  <style>
    .text {
      font-weight: 600;
    }
  </style>
  <div class="text"></div>
</template>

class CapitalisedText extends HTMLElement {
  constructor() {
    super();
    const shadowRoot = this.attachShadow({ mode: "open" });

    const template = document.querySelector("#capitalised-text-template");
    shadowRoot.appendChild(template.content.cloneNode(true));
  }
  connectedCallback() {
    const text = this.getAttribute("text");
    const div = this.shadowRoot.querySelector("div");
    div.appendChild(document.createTextNode(text.toUpperCase()));
  }
}

Custom elements remain in the DOM tree

When React renders a component, it creates and appends DOM elements. The component itself is nowhere to be seen in the DOM tree. Custom elements are part of the DOM tree. This is important to note when considering querying and styling.

React:

Web component:

Attributes vs. properties

React components have props that can be of any data type. Custom elements, like any built-in html element, have attributes that can only contain strings. They also have properties that can contain any data type but can only be set using JavaScript. Learn more about attributes and properties.

Listening to attribute changes is opt-in

A react component re-renders when prop values change. Web components expose the attributeChangedCallback that can be used to update the UI in response to changes in attributes. This callback doesn’t fire by default however. Every web component has to explicitly list the attributes it wants to listen to using the observedAttributes static method.

Conclusion

Conclusion
Web components are surprisingly good at managing a code base using vanilla JavaScript. Some developers can perceive the current standards as bare-bones however. In fact, the term components is somewhat misleading. It draws parallels with existing frameworks and libraries whose components have many more features.

Overall, I'm satisfied with my decision to migrate to web components. I'll definitely use them again for other projects.

What's your opinion on web components? Do you think they can replace tools such as React or Vue?

Using media queries with JavaScript

Maroun Baydoun — Tue, 30 Mar 2021 19:18:54 +0000

Media queries are not limited to CSS. JavaScript can also react to them. This can be very useful when building applications.

If you're looking for an existing solution for using media queries in JavaScript, checkout my small library mediaq.

The window.matchMedia API

Browsers expose the window.matchMedia method. It takes a media query as an argument and returns a MediaQueryList object.

 const mediaQueryList = window.matchMedia("only screen and (max-width: 600px");

Checking if a media query matches

Once created, a MediaQueryList object has the boolean property matches. Use that property to check, at any time, if the media query is matching.

 if (mediaQueryList.matches) {
    console.log("It matches!");
 } else {
    console.log("It doesn't match.");
 }

Listening for updates

Instead of checking if the MediaQueryList object matches, you can attach an event listener to it. The listener will trigger whenever the media query matches or stops matching (the window is resized, the device orientation changes etc.).

Since MediaQueryList inherits EventTarget, listening to the events it fires is very straightforward.

const listener = (event) => {
    console.log(event.matches ? "It matches!" : "It doesn't match.");
};

mediaQueryList.addEventListener("change", listener);

Removing a listener is also as easy

mediaQueryList.removeEventListener("change", listener);

Internet explorer and Safari < 14 handle those event listeners differently. They use addListener/removeListener instead.

To support those browsers as well, you can conditionally call the correct method.

const listener = (event) => {
    console.log(event.matches ? "It matches!" : "It doesn't match.");
};

if (mediaQueryList.addEventListener) {
  mediaQueryList.addEventListener("change", listener);
} else {
  mediaQueryList.addListener(listener);
}


// For removal

if (mediaQueryList.removeEventListener) {
  mediaQueryList.removeEventListener("change", listener);
} else {
  mediaQueryList.removeListener(listener);
}

You can read more about browser compatibility.

Why use media queries with JavaScript?

When applied through CSS, media queries help create responsive layouts. They also allow hiding certain elements on the web page and loading higher/lower resolution background pictures.

In some scenarios that is not enough. That's when JavaScript can be used to optimize the webpage further.

Imagine a component of your webpage is computationally heavy and you decide you don't need it to display on smaller screens. In CSS, you can easily hide it, but it would still exist as part of your DOM and could still weigh down the performance of your web application.

@media only screen and (max-width: 480px") {
 .component {
   display: none; /* The component is hidden but is still part of the webpage.*/
 }
}

In JavaScript, on the other hand, you could decide whether or not to append the element to the document.

const mediaQueryList = window.matchMedia("only screen and (max-width: 480px");

if (!mediaQueryList.matches) {
 // Create/Append the element here
}

Another use case is loading certain scripts for certain screen sizes. If you application uses large graphing libraries, you can choose to include them only on desktop-size devices, where the graphs are being displayed.

const mediaQueryList = window.matchMedia("only screen and (min-width: 768px");

if (mediaQueryList.matches) {
  const script = document.createElement("script");
  script.src = "path to JavaScript script";
  document.body.appendChild(script);
}

JavaScript can detect screen resolution without using media queries. This can work for one-time checks. Listening to updates with the resize event on the window object can be expensive. Using media queries is much more efficient.

What Github commits get wrong

Maroun Baydoun — Thu, 18 Mar 2021 22:08:35 +0000

If you see this UI, what would you expect to happen when you click the username and profile picture respectively?

I'd expect to be shown the user profile in both cases. If not, then at least I'd expect those two elements to behave similarly.

It turns out that clicking on the profile picture leads to the user's profile. While clicking on the username shows all commits by that user.

To be fair, hovering the profile picture brings up a short preview of the user's profile.

Hovering the username displays a helpful tooltip.

However, that doesn't justify using two different patterns for two UI elements that are so closely related.

What do you think? Do you find it difficult to tell the difference? And how would you have designed it differently?

Scrum is not for humans

Maroun Baydoun — Thu, 20 Aug 2020 18:59:33 +0000

This post was originally published on my blog

Not a single workday goes by without hearing people praising the virtues of Agile. For many, Agile became synonymous with Scrum. In this article, I argue that Scrum is very hostile to developers. More generally, I will explain why Scrum is not designed for humans.

I'm not planning on explaining what Scrum is. There are numerous resources that could do that better. The Scrum guide is a good place to start. In a nutshell, Scrum is a framework for product development with its sets of roles, artifacts and ceremonies. No, I’m not talking about a cult or a secret society. I’m talking about something that has become at the core of many people's work life.

Scrum is anti-developer

In his book Developer Hegemony, Erik Dietrich makes a very interesting observation. He notes that developers are a hot commodity nowadays. Companies are willing to shell high salaries and incentive packages to recruit the best talent. However, once those developers join a company, they are faced with impediments that stop them from reaching their true potential. Mountains of bureaucracy, layers of management and interfering with their daily work are just a few examples of that. Dietrich imagines a future where developers flip the table and take back control. We are not talking communist revolution and seizing the means of production. We are talking about being in charge of their destiny and actually delivering their full potential.

Scrum is yet another red tape thrown at developers. Instead of allowing developers to self-organise, someone high in their lofty tower decides how the team should be working. Funny enough, the Agile bug seems to only infect developers. The remaining parts of the organisation are unphased. The same people forcing Scrum down developer’s throats would not be even there if the organisation were truly agile.

I dislike Scrum because it makes a few wrong assumptions. First, that developers are lazy and need to be micro-managed to deliver. While many developers can be underperforming, putting them under the spotlight will only make the problem worse. Second, that the process of software creation is indistinguishable from any industrial manufacturing process. Claiming that uncertainty and unpredictability are not inherent parts of software engineering is as good as relying on the planets' positions to determine one’s destiny.

It is true that not all developers are exemplary employees, but more often than not they want to give their best and be proud about the products they deliver. When things go wrong in the development team, people are quick to jump to the conclusion that developers have to be micromanaged to extract every ounce of productivity from them. However, the problem is often somewhere else in the chain.

A game of poker

Scrum advocates estimation as a way of managing the team's workload. At first glance, that seems to be a very developer-friendly measure. Who wouldn't want to achieve a constant pace of delivery that keeps the users happy and saves the development team from burndown?
In practice though, estimations end up being yet another pressure mechanism.

Humans work in different ways, at different speeds and at different times. The myth of a constant pace of delivery does not reflect the reality of working in software development. Developers have good days and bad days. They exist outside the realm of their roles at work. They get sick, go on holidays, lose motivation etc.

Uncertainty and unpredictability are hallmarks of software creation. That by itself is enough to invalidate the need for estimations. Pushing them on a team is a game of dishonesty and lack of trust. Everybody involved knows that those numbers carry little value. The time wasted making predictions and false promises should be used to bring real value to users instead.

Developers are not stupid. When they can't change the system, they start to game it. They will use estimations to advance their own agenda. They will overestimate and deliver less. They will underestimate to make sure something they feel passionate about is picked up for development.

What do you stand for?

The Scrum guide defines the daily stand-up as a short meeting for the development team to discuss their progress and impediments. In theory, I see some value in that. However, it makes the misinformed assumption that a team needs a specific ceremony to talk. In practice, team mates should and do exchange ideas all the time.

What happens more often than not is the liberal reinterpretation of the daily stand-up. Managers and product owners attend and turn this ceremony into a status update meeting. Developers are ~~forced~~ encouraged to share the teeny tiny details of their work with people who probably have little knowledge of and no interest in what is being said.

Worse still, many companies use the daily stand-up as a sneaky way to get everyone in the office by a certain hour. This hinders any prospects for flexible working hours or remote work. Attending the daily stand-up becomes the number one reason why people show up at work, not the work itself.

Build it and they'll come

Scrum is a great masquerade for agility. True agility requires no ceremonies and no artifacts. True agility is a cross-organisation mindset that doesn’t apply to the development team only.

By adopting Scrum and following its guide, either to the letter or not, people believe they will magically become agile. The belief is that a time-delimited sprint ensures the ability to change course. That having retrospective meetings will enable the team to iron out issues in their process. That estimating and measuring the team’s velocity will make people more productive. In reality, none of that is true.

Scrum has become a perfect example of cargo cult agile. Everyone is waiting for the benefits to come raining down. In reality, the sky is blue with no clouds in sight even though the team has been doing its rain dance for weeks.

Scrum often hides the fact that true impediments are not in the development team itself, but further up in the hierarchy. The “follow the Scrum guide” commandment is a great mirror and smoke show for denying true change elsewhere in the organisation. The narrative is often flipped to suggest that the team problems stem from not applying Scrum strictly enough, for being too lenient in estimations and too ineffective in their retrospective. They are encouraged to dive deeper into Scrum while the rest of the organisation remains unchanged.

Going clear

Some teams can and will use Scrum. A prepackaged workflow could work under certain circumstances, but it achieves nothing in terms of agility. Agility is the antithesis of process and ceremonies. Agility is giving a development team trust to self-organise. Agility transcends all layers of an organisation. In fact, a truly agile organisation does away with most of its layers.

Be careful anytime you buy into a methodology with inflated claims, rigid rules and unintuitive workflows. An ecosystem backed by certifications and “coaches” will create a feedback loop that perpetuates its shortcomings and hinders true progress.

Any team can and should decide its own workflow. Processes are discovered, adopted and improved along the way. If you are a developer, make sure you are part of that conversation. By deferring those decisions to the “wise” men and women of the organisation, you give up the agency to determine your own fate. Any process in place should be there to serve you and not the other way around.

Don't start with React

Maroun Baydoun — Mon, 27 Jan 2020 22:12:53 +0000

If you are getting started in web development, it is tempting to learn the most used technologies early on. More and more junior developers are investing in React through self learning or coding bootcamps.

The problem?

While React is a great choice for building many types of applications, it is important to understand that there are alternatives. More crucially, React exists to solve a set of problems that developers face. Understand those problems first, and learn React next.

A little bit of history

People doing web development from the mid 90s till the mid 2000s experienced the dominance of Internet Explorer, incompatibilities between browser engines, slow advancements in the web and a lack of good practices to organise code.

Creating anything using JavaScript meant worrying about problems such as:

Having the DOM reflect the application's state.
Organising the code and splitting it into different files.
Adding and removing event listener.

Several solutions to these problems were introduced. jQuery made it easier to manipulate the DOM. RequireJs gave developers a way to break down applications into multiple files and load them in the browser. Tools such as Gulp, Grunt and later Webpack improved the build experience even further. Frameworks such as BackboneJs, Ember and later AngularJs offered a way to structure applications and organise the code.

Enter React

At first glance, React looks like a step backwards. React focuses on the View layer instead of embracing the full MVC architecture. Unlike its predecessors and some of its peers, React offers no out-of-the-box solutions for common needs such as routing, state management or styling. The distinction gives React the status of a library and not a framework.

So what problems is react solving?

Having the UI reflect the app state

React’s goal is eliminating manual manipulation of the DOM. Instead of querying a certain node to update its attributes or children, you would describe the end result you want and React will take care of the rest.

To achieve that, React dumps the common paradigm of separating HTML and JavaScript. Your JavaScript code is no longer there to manipulate the UI created by HTML. Your JavaScript IS THE UI. (React still permits direct DOM manipulation using refs)

DOM updates are expensive

React makes updates to the DOM less expensive by comparing what the browser is rendering with what your UI is describing. This should improve the user experience in the browser.

Event management is messy

React simplifies event management by adding a single event listener to the root of the document. This should reduce memory leaks introduced by complex event listeners in an application.

Code is unorganised

React offers a way to organise code by breaking it down into components. This encourages the application to be broken down into simple units respecting the single responsibility principle.

The best of both worlds

Understanding how the DOM works, its limitations and bottlenecks is an essential skill to create client-side web applications. Learning libraries and frameworks early on masks those complexities. It deprives you from understanding what is going on in the browser.

Those libraries and frameworks are just syntaxic sugar around what the browser can natively do. It all boils down to what the JavaScript engine is doing and how the DOM is updated. This knowledge is essential to catch bugs and avoid performance issues.

Learn how to create an application using nothing more than HTML, JavaScript and CSS. Feel the pain of managing state, events and DOM updates manually. Understand the common pitfalls, the performance bottlenecks and memory leaks. Transition to an MVC framework. Understand that your front-end code can be organised and architected. Pick an old framework and give it a test drive. Backbone.JS is a great introduction to application frameworks. Finally,
learn React.

Conclusion

Don’t limit yourself to a certain library or framework. Eventually, the next big thing will come and sweep them off. Focus instead on what changes slowly. React will disappear but the browser will not.