DEV Community: Riley

New Courier Inbox: Add a full-featured notification center to your app in minutes

Riley — Wed, 15 Mar 2023 17:18:49 +0000

Email and SMS are becoming increasingly busy channels. Sometimes, there’s no better way to reach a user than by sending a message to a notification center right inside of your app. However, building an inbox experience like this, from scratch, was a significant engineering effort.

Today, we are announcing a major update to Courier Inbox, a solution for developers to add an in-app notification center to their web application in a matter of minutes.

If you’re using the previous version of Inbox, we’ll cover the upgrade steps later in this post.

"With Courier, we added a beautiful inbox and in-app push notifications in a matter of weeks. We used the great looking pre-built component to save even more time. Notifications are not our core competency, so it made complete sense to integrate rather than build out and support our own implementation."

James Pipe, VP of Product, DroneDeploy

What is Inbox?

Courier Inbox is an in-app notification center for web applications (and mobile inbox coming soon). Inbox acts as a convenient in-app notification feed with a clean interface where users can view notifications in real time directly inside your web app. It also lets them view their message history of all past notifications that you’ve sent to them.

Using in-app notifications allows you to get users’ attention when they are in the application. This makes your communication with your users more timely and convenient: instead of interrupting them with an email on their phone when they are busy doing something else, you can use an in-app notification to provide information that is relevant to what your users are trying to do right now. Showing notifications within your web application increases user engagement — and provides a more seamless experience, as you can link users directly to relevant parts of the web app within these notifications.

While many companies are considering building notifications into their web app, not everyone has the time or resources to build a full-fledged notification center. We first implemented Inbox two years ago together with the web-based pop-up notification functionality, and customers loved it exactly because it takes so little time to start using it.

The notifications that customers send via Inbox may include application activity such as discussions, new events, comments, alerts, and reminders, as well as news about feature updates.

Based on customer feedback, we’re excited to announce improvements to the Inbox functionality. Meet the new Inbox.

Introducing the new Inbox

The new Inbox has all the benefits of the original Inbox: it’s fast to implement via pre-built Courier JavaScript components, it offers an intuitive user experience, the design is customizable to your needs, and it natively integrates with the rest of the Courier platform. On top of that, Inbox includes a number of improvements, in terms of both design and functionality.

On the design side, we took customer feedback on board and simplified how the inbox looks and feels. Specifically, here’s what changed:

Visually, the inbox now looks more modern so that it fits better into customer apps.
There are no more separate tabs for read and unread messages — this separation into tabs previously led to confusion. Now everything is displayed more clearly in a single feed.
Hovering over a message now shows a check mark or cross to mark a message as read or unread, instead of a vertical three-dot menu taking up screen real estate.
Unread messages are identified by a colorful logo (vs. gray for unread), and the colors are customizable. A colored dot appears at the top showing how many unread messages there are in the inbox.
Hovering over a message makes the background of that message change color if it is clickable. Short messages where all the text can be viewed at a glance are not clickable and don't change color on hover.

Notification state is now synchronized between the inbox and other channels. For example, if a notification was sent as in-app and email, reading the email will mark the in-app notification as read.

Another new feature is message expiration. It’s now possible to set a timeline for the message to expire, say 7 days, and after that time the message will be removed from the inbox. This feature can help avoid a mess of older notifications for users that rarely sign into the web app.

The advanced branding options, including applying brand settings (we cover this below) and removing the Courier logo, as well as message retention are available on our Developer and Business tiers.

How We Use Internal Hackathons to Create New Product Features

Riley — Tue, 18 Jan 2022 21:09:39 +0000

An internal hackathon is an effective way to engage your employees in short-term collaborative events. It spurs innovation, increases employee engagement, explores new feature possibilities, imparts corporate culture, and builds teamwork and collaboration skills. By organizing internal hackathons in your company, your employees can challenge and compete to solve internal or customer problems—which can lead to real-life features in your product.

Courier’s internal hackathons have not only led to a better product and smoother customer experiences, but they have also engaged employees and promoted teamwork. Some of our hackathon projects that made it to production demonstrate the value of giving teams the time and space to innovate this way.

We do our best to support these hackathons and create the time and space for them, so these events don’t distract employees from their day-to-day work. Our employees, in turn, appreciate the internal hackathons because they get to explore all their ideas and opinions that they don’t have time to work on in their day-to-day jobs. We reflect our culture in our internal hackathons, and, in return, some of the projects make it to production as regular Courier features.

Internal Hackathons Represent Our Values at Courier

Our hackathons highlight our core values—“have an opinion,” “just f-cking do it,” and “talk to customers.” During these hackathons, team members turn their opinions into experiments, challenge each other, and solve problems. We even have friendly competitions and push each other to win, promote teamwork by sharing Loom videos and presentations, celebrate innovation, etc.

We also inform the product, sales, and customer service teams about these projects and talk to our existing customers. In the case when a customer shares similar ideas, they quickly chip in: “Oh, we’ve done this in a hackathon before. Let me sync with the engineer and see what it takes to get it production-ready.”

We host our hackathons twice a year and dedicate a full day each time. Employees are split into two to three technical and non-technical members on a team. Teams record their project demos using Loom, and on the hackathon day, teams give their presentations while the judges watch and vote on the best hackathon project.

Two Examples of a Hackathon Project Becoming a Live Feature

As an engineer at Courier, you feel the pain of some customers. You understand the features they would benefit from but have not yet scoped out technically, or you have no time to build them. Hackathons give you the time and space to experiment.

Sometimes, this experiment hits home with a common pain point, and we ship it or put it into production. Other times, it is just a fun project. Let’s look at two hackathon projects at Courier that made it to production.

Embedded Components Project Turned “Toast and Inbox” Feature

For our very first hackathon, my team experimented with the idea of embedding Courier functionalities in our clients’ websites to give them a better user experience. These components included features to provide an inbox, notification preferences, and a list of recent messages received for our customers.

For the hackathon, we built an embedded preferences component to allow end-users (our clients’ customers) to control notification preferences. This allowed our clients to let their customers control and manage their preferences. We presented our project and eventually won the first hackathon.

Building on top of this, for the second hackathon, my team pushed the idea further to another embedded component to improve the customer experience. For this second hackathon project, we noticed there were a lot of clients with multiple brands asking, “Hey, I love your notification designer, but I need to let my other brands design and change emails, logos, fonts, etc. We want to do that easily without managing every one of them.” So, we built a solution to embed Courier brand designers in an arbitrary website that will allow our clients to update their branding and edit their content seamlessly.

After the first two hackathons, we started getting questions from customers wanting to create an inbox to deliver messages to their end-users. So, we looked at the infrastructure of these embedding components’ projects and built react components for Toast and Inbox.

Because hackathon projects are not production-ready code, we use the codebase as a blueprint to build out the feature. The timeline of taking a hackathon project to a feature depends on the functionality. Some are relatively easy, while some are difficult depending on the project. Specifically, “Toast and Inbox” was built on top of the technology used for the hackathon but had so many more functionalities, so it took some time to get it out.

Column Block Project Turned “Column Element” Feature

At Courier, I am focused on the design and UI side of things—I built a lot of it from scratch. For the third hackathon, my team got creative with our notification block. We wanted to experiment with a new block that would benefit our customers in a different way.

With the version of the notification designer at that time, you could only make a list of blocks (up and down) but could not put blocks side by side. So, taking some inspiration from SendGrid Designer, we created an idea to make two blocks together in our notification designer. Although it was pretty buggy, we got the project out and presented it at the hackathon.

Six months later, UserVoice wanted to sign in with Courier and mentioned we lacked some functionalities they wanted. Specifically, they wanted to put two blocks next to each other in the notification designer. So, the sales and product team reached out to me, and I went, “Oh yeah, I hacked that together; it was cool but with a few bugs.”

We had to go back, resurface that code, cut out the buggy scope, clean it up, and build it. But we were able to put it into production in a week and signed the contract with UserVoice.

Moving to Developer-Focused Hackathons in the Future

Hackathon projects have helped us stay centered around a better product for our clients’ customers—which is great. In the future, we are shifting to focus these hackathons on improving the developer experience at Courier.

If our hackathon and processes inspire you, we have some open roles on our careers page. Come work with us!

React Inbox and React Toast Components for Notifications That Don’t Suck

Riley — Tue, 31 Aug 2021 15:28:30 +0000

We are excited to announce the availability of Courier’s newest provider, Courier Push! We have released Inbox and Toast, two open source React components that exemplify the potential future applications of this feature. With Toast, you can send your user a notification within your web application and Inbox allows you to create an embeddable notification repository so that your user can access all past in-app notifications.

Most importantly, Courier Push allows us the flexibility and customization to do app-to-user communication right. As software users ourselves, we are bombarded with messages constantly, which can...really suck. Yet, notifications are necessary to communicate with users. With Courier Toast and Inbox, developers can support custom notifications for their users’ specificities and communicate through multiple wide-ranging channels while maintaining a single in-app notifications repository. We are particularly excited about all the potential future applications of Courier Push in addition to Toast and Inbox and are looking forward to expanding its uses.

Here at Courier, we want to improve the integration experience for you, the developer, and the notification experience for your customers. We’ve done this with Courier Toast and Inbox.

Courier Toast and Inbox

What is Toast

One of the major tenets of Courier’s product offerings is sending notifications. Receiving them and displaying them in your application is game changing. The ease of implementation makes your job as a developer simple and enables you to build real-time web applications that provide a better user experience for your customers. Your end-users can see customized notifications pop up in your web application through a modular system you can easily customize.

What is Inbox

Alongside Toast messages is a customizable inbox, which is essentially a notification history. This takes the pressure off users to respond immediately, lessening the anxiety around the experience in general. Inside Inbox, a user can:

Read their messages
Mark messages as read or unread
Delete messages

How to Integrate Toast and Inbox in a React App

Let’s walk through how you can integrate Courier Toast and Inbox React Components in a React app. Check out the Courier React Components repository on GitHub.

Step 1: Install CourierProvider

@trycourier/react-provider

...to handle all of the authentication and integration with the backend.

yarn add @trycourier/react-provider or npm i @trycourier/react-provider

Step 2: At the top level in your React tree, add something that resembles the following code. The Client Key can be found here and the User Id is the identifier for identifying your user. Note that it will be used later in the API call to courier.

import { CourierProvider } from "@trycourier/react-provider";
import { Toast } from "@trycourier/react-toast";

const MyApp = ({ children }) => {
  return (
    <CourierProvider clientKey={CLIENT_KEY} userId={USER_ID}>
      <Toast />
      {children}
    </CourierProvider>
  );
};

N/B: You can add Toast to the frontend anywhere as long as it’s a child of the CourierProvider.

Step 3: Inbox should be added in the application as a child of CourierProvider, but where you want the Bell icon to display. For this example, we will just put it right next to Toast.

yarn add @trycourier/react-inbox or npm i @trycourier/react-inbox

import { CourierProvider } from "@trycourier/react-provider";
import { Toast } from "@trycourier/react-toast";
import { Inbox } from "@trycourier/react-inbox";

const MyApp = ({ children }) => {
  return (
    <CourierProvider clientKey={CLIENT_KEY} userId={USER_ID}>
      <Toast />
      <Inbox />
      {children}
    </CourierProvider>
  );
};

How to Customize Toast and Inbox

There are two ways to customize your Inbox and Toast. First you can use the studio to customize your application and the components will automatically update when the brand is published.

The second, you can pass properties right into each component. Each component supports a theme and also supports render properties. Here’s the code for props:

interface InboxProps = {
  //Icon Class Name
  className?: string;

  // Default Icon to use if no Icon is present in Message
  defaultIcon?: false | string;

  // Placement of the Bell relative to the Inbox
  placement?: "top" | "left" | "right" | "bottom";

  // Render Props for Custom Rendering
  renderTabs?: React.FunctionComponent<{
    currentTab?: ITab;
    tabs?: ITab[];
  }>;
  renderFooter?: React.FunctionComponent;
  renderHeader?: React.FunctionComponent;
  renderIcon?: React.FunctionComponent<{
    unreadMessageCount?: number;
  }>;
  renderMessage?: React.FunctionComponent<IMessage>;
  renderNoMessages?: React.FunctionComponent;

  // Tab Overrides
  tabs?: Array<ITab>;
  theme?: ThemeObject;

  // Inbox Title Override
  title?: string;
  trigger?: "click" | "hover";
}

Conclusion

Courier Push opens the doors to perfecting app-to-human communication with its flexibility and potential for customization. Communication is a two-way street that requires not only good messaging, but also a channel and style that works uniquely for a specific type of user using a specific app. With Toast and Inbox, developers can create an effective notifications system that reaches end users when they want, how they want, and the way they want. To learn more, check out the documentation.

We believe that providing contextual notifications from within your app is an opportunity to provide better, more intuitive, and more interesting user experiences. We also believe that if done right, these can take us a long way towards accomplishing our goal of making computer to human communication delightful. This is just the beginning of our investment in solving this problem, so please stay tuned for more.

Check out Inbox and Toast and let us know what you think! Your feedback helps us to continuously improve.

How We Built React Components for Any Front End

Riley — Fri, 09 Jul 2021 22:46:42 +0000

Put simply, building and maintaining a completely custom notification system in-house is a pain. It requires a lot of human effort in the beginning and will undoubtedly need to scale at some point. Maintaining a system like this takes away development time from core tasks and business needs.

To make sure teams don’t need to build an in-house solution for a notification systems problem, we adapted our offering. We created a lightweight solution using React that has a global state and runs independently in the background — so teams can render our components regardless of their tech stack.

We built custom Courier components

While React is a popular library, we recognize not everyone uses it, and it might not be as widely used in the future as competing front-end architectures emerge. This is why we wanted to find a way to create custom components that can work in any front end setup with any user interface.

To solve this we decided to make custom Courier components in React that take inspiration from Web Components. The idea behind Web Components is that they allow developers to build custom, reusable elements where the functionality lives independently from other parts of the codebase.

This modular setup is what allows for a custom solution that can be implemented anywhere, with any specific user interface, and with any front-end library or framework. Because the logic can live outside the context of your other code, our components can run independently in the background.

The initial setup is straightforward. You place two script tags in the body (the order of the tags is important). The first script tag holds a small amount of code where you identify configurations like your user with a userId and your Courier clientKey. The second script tag downloads the Courier components.

<body>
  <section>
    <h1>Hello World</h1>
    <courier-toast></courier-toast>
    <courier-inbox></courier-inbox>
  </section>
  <script type="text/javascript">
    window.courierConfig = {
      clientKey: "{{CLIENT_KEY}}",
      userId: "{{USER_ID}}"
    };
  </script>
  <script src="https://courier-components-xvdza5.s3.amazonaws.com/latest.js"></script>
</body>

Additional configuration options let you defer the initialization of Courier components, as well as map the configuration for each component you load on the page. The two components you can currently load are toast and inbox.

Our SDK is exposed on window.courier and is loaded asynchronously. Calling window.courierAsyncInit will let you know Courier has successfully loaded.

<script type="text/javascript">
  window.courierAsyncInit = () => {
    console.log("Courier is Ready!");
  };
</script>

If you’d prefer to separate the logic for each component (the toast and inbox components), you can also choose to set window.courierAsyncInit to an array.

After initialization, window.courier is ready, and you can listen for actions inside the Courier SDK. A small amount of code lets you init the toast component.

<script>
  window.courierAsyncInit = () => {
    window.courier.on("toast/init", () => {
      window.courier.toast({
        title: "Hello",
        body: "World",
      });
    };
  };
</script>

You can configure the components in two ways:

with inline HTML attributes

//inline
<courier-toast auto-close="false"></courier-toast>

with window.courierConfig

window.courierConfig = {
 components: {
  toast: {
   autoClose: false,
  }
 }
};

If you need to use multiple configuration options with a component, window.courierConfig gives you that ability without having to add too many attributes to your HTML element.

If you do choose to use the inline configuration, you’ll need to make sure you’re always formatting in kebab case since HTML attributes are not case sensitive.

We preserved context with React Portals

It’s pretty easy to get up and running with the components. But one hurdle we needed to overcome was making sure the data you need from us is accessible to every Courier React component. And this needs to happen anywhere in your project, regardless of component hierarchy. We make use of React Context and React Portals to inject components anywhere in your DOM.

If you’re unfamiliar with React Context and React Portals, here’s a quick rundown.

React Context

Context allows you to pass props between components without explicitly having to deal with tree structure. This allows for easy access to data regardless of UI requirements. The result is global data accessible by child components that live outside the nesting levels of parent components that contain necessary data.

React Portals

The use of a portal allows you to inject a child anywhere into the DOM, retaining the context of the parent node even though it’s outside the standard nesting structure. Even though the portal can be placed randomly in the DOM tree, the portal still retains its context in the React tree. This means events like bubbling will still function normally.

Putting it all together

After the initialization of Courier, we analyze the HTML and find components to dynamically import, making sure not to download any extra components you aren't using. We identify them by HTML tags and then render them inside the context of the Courier SDK. This allows us to then render them wherever you need in the DOM with the Courier context they need.

So through a combination of React Context and React Portals, we preserve the global state our Courier components rely on. Our toast and inbox components render into a portal, and the portal allows for those components to act as children out of the hierarchy order of the parent. This allows you to render our Courier components into anything that's not in the official React DOM tree.

We resourcefully packaged a solution

We’re not here to add code bloat. We purposefully found solutions that guarantee we keep our integration as small as possible.

We currently have two components you can render, the toast message and the inbox. We're cognizant that library size matters, and while some might see a need to integrate both components, others might only want to integrate one. We also have plans to add more components in the future, so it's important to dynamically load what's needed, not everything.

By providing a small amount of code for you to implement that handles the automatic download of desired components, we make sure your project remains as small and lightweight as possible. When you load our code, we analyze your HTML to see what components you’ve identified that you need. These components are loaded dynamically and are then cached. This ensures that subsequent renders aren’t refreshing the code.

We do this with React Suspense, which does exactly what it says. It suspends the rendering of React components until a condition is met. In the example below, the portal we’ve created is waiting to see if the toast component has a configuration set up. If it does, we will load it.

import React, { lazy, Suspense } from "react";

const toastElement = document.querySelector("courier-toast") ?? undefined;
const toastConfig = {
  ...componentConfigs?.toast,
  ...getAttrsAsJson(toastElement)
};

<CourierSdk
  activeComponents={{
    toast: Boolean(toastElement)
  }}
>
  {toastElement &&
    ReactDOM.createPortal(
      <Suspense fallback={<div />}>
        <Toast config={toastConfig} />
      </Suspense>,
      toastElement
    )}
</CourierSdk>;

When a component does need to render, it can do so asynchronously. This implementation method also allows us to scale in the future by adding new components that can be dynamically imported.

In addition to dynamically imported components, we also keep the bundle small by using Preact. Preact uses the same ES6 API as React, but Preact is more lightweight and able to load a faster, thinner virtual DOM. We’ve carefully built this implementation so Preact can fully replace all instances of React.

You can check out the repo here.

Try it yourself

Courier enables developers to deliver the right message to the right user at the right time. To find out more about Courier’s full offering and see how it can integrate into your stack, check out our docs and our API.

Who Knew Email Subjects Are So Complicated

Riley — Fri, 11 Jun 2021 16:40:27 +0000

Did you know that email subjects, by default, only support 127 characters?! I didn’t, and I ran into a “fun” puzzle of a problem earlier this year when a client of ours noticed a problem with Courier-built emails in Microsoft Outlook. Small rendering issues and bugs like this can give the wrong impression to a recipient of an email. It can make the end user feel the product they are using is poorly planned or not tested. Not even just that, but not having support for certain characters can prevent you from reaching customers in other languages and countries.

This is the screenshot we received (note the Black Diamonds):

Any guesses why this happened? Or what the email subject should be? Well, the email subject is French and should be “Vèrifiez votre email” (Verify your email). Let’s dive in, debug, and solve this problem together.

How we solved the problem

As any engineer in 2021, the first step was to Google the problem like: black diamond question mark email subject. This didn’t give us great answers, unfortunately. Some of the first results were from a Microsoft forum and the solution was asking people to update their local Outlook configuration thinking the problem was only a local one. The problem with this is that in order for us to be able to help, we would have needed to ask our customers (and all of their customers) to make this update. The lack of ability to reach all these people and clearly explain to them why they needed to do this meant that the solution was a no-go for Courier.

After digging deeper and making a few keyword changes, I found that this specific character, �, is actually the sign of using a non UTF-8 character when the client expects all characters to be UTF-8.

What is UTF-8?

Very basically, UTF-8 characters are the first 128 unicode characters representing a-z, A-Z, and 0-9 characters and keyboard codes (including punctuation, tabs, shift, etc.). This does NOT include accented characters like the ones we had seen used above. These characters are outside of the first 128 char codes.

Encoding to the rescue!

First some background. Emails (and http requests in general) consist of headers and a body. The email body (HTML) is relatively straightforward. The other parts of an email include fields like “From:, “To”, “Subject”, etc. are headers. Headers are where things start to get tricky. When an email server starts to decode headers, it expects the headers to be UTF-8. This means you cannot include any characters outside of the first 128 unicode characters as mentioned above.

To get around this limitation, we can encode our email subjects in base64. Base64 encoding schemes are commonly used when there is a need to encode binary data, especially when that data needs to be stored and transferred over media that are designed to deal with text. In layman's terms it takes unicode characters and converts them to UTF-8 readable text. This does mean the text will be longer, but it allows us to send over all the data we need in a header.

We can encode base64 like this in Node.js.

const buffer = Buffer.from(subject);
const base64 = buffer.toString("base64");

This doesn’t, however, tell the email server that the email subject is base64. To inform the server the email subject is encoded in base64, we can use this specific format (RFC 1342).

const buffer = Buffer.from(subject);
const encodedSubject = '=?UTF-8?B?${buffer.toString("base64");

Sending an email subject like this should “just work,” since this way, the server will decode the string and render it correctly! 🎉

But wait, there’s more!

Limitations! :(

We did run into problems with some email providers and the length of the base64 encoded string. Keep in mind, if I encode the string in base64, check the length, and determine that the length is too high, I cannot just trim the encoded string because it will break the encoding. I won’t be able to decode the string.

To solve this, I had to recursively encode the subject and check the string if it was too long. If it is too long we take the original string, trim it and then re-encode and check the length. We repeat this process until we get an encoded string at the right length for said email provider.

export const encode = (subject: string, maxLength?: number) => {
  if (!hasUnicode(subject) {
    return subject;
  }

  if (maxLength) {
    subject = subject.slice(0, maxLength).trim();

const buffer = Buffer.from(subject);
const encodedSubject = '=?UTF-8?B?${buffer.toString("base64")}?=';

// postmark breaks when we send encoded messages > 78
  if (maxLength && encodedSubject.length > maxLength) {
    return encode(subject.slice(0, -1), maxLength);
  }
  return encodedSubject;
};

This was our journey into email subjects when we found out that Microsoft Outlook didn’t like certain characters in our email subjects. The process took us from confusion to understanding, and finally building a solution that works for multiple providers.

It blows my mind that email in 2021 can (still) cause such a headache. Well, in reality, it is just Microsoft Outlook. This email client is notorious for causing headaches like this. Two of the other most popular clients, Gmail and Superhuman, both handled these email subjects just fine. I wish this was as easy as saying “we don’t support Internet Explorer,” but so many people still use these old versions of Microsoft Outlook. So to anyone reading this and building an email application. If anything funky happens, always check and see if it's Microsoft Outlook...and don’t get too frustrated when the solution obtuse and lengthy to implement.

I’d like to call out these websites which were great and helped us understand and test our solution:

Author: Riley Napier

How to use the Shadow DOM to isolate styles on a DOM that isn’t yours

Riley — Tue, 17 Nov 2020 20:01:34 +0000

There have been many times in my career of building web apps and frontend experiences that I have needed to embed a widget in a DOM that I did not build or have access to. For example, embedding e-commerce widgets in a CMS or building chrome extensions to augment a given website. One of the biggest frustrations I've had is the style collision. In my development environment, all the widgets look great but the second I add the widget to a customer’s page… everything is broken!

Why does this happen?

The difficulty with embedding widgets in a DOM that you don't own is every DOM is going to reference different default fonts and colors. It’s normal for a css stylesheet to look like:

body {
   font-family: my-awesome-font;
   font-size: 16px;
   color: #eee;
   line-height: 16px;
   box-sizing: border-box;
}

When I embed my widget into the body of this customer’s page, it will inherit the above styles. While sometimes this is okay, many times it will break the beautiful widget I designed because I designed the widget with a different font size or padding.

Classic solutions

Historically, we have had 2 solutions to this problem:

Use an iFrame.
Be crazy explicit with your styles.

While both solutions can work, they both have rather frustrating aspects you will have to deal with. Below I'll go over a few examples of what I’ve done in the past and then cover what this blog post is all about – the fancy, new, futuristic way to make composite user interfaces, or the Shadow DOM.

Working with iFrames

With an iFrame, I have no control over the element’s size, so the consumer of my widget will have to accurately carve out space in their DOM for my iFrame. If my widget is dynamic in size, this is going to cause all sorts of problems with scrolling and positioning.

The second issue we find with iFrames is the communication between the iFrame and the parent. While I can now use CustomEvents, I will need to build out an event system for both the parent and the iFrame context. This can be frustrating if the client already has a built-in SDK. It’s basically building a mini SDK for the SDK for iFrame communication.

Finally, and maybe the most simplistic issue, is my consumer can’t tweak ANY of the styles in my iFrame. This can lead to inconsistent user interfaces and is just a bad experience all around.

While iFrames will work, they are outdated, difficult to communicate with, and, if your widget is dynamic in size or you need any kind of customization, good luck.

CSS specificity

The more common approach I have taken is to just be super specific with my CSS. So namespace everything! This can be tedious and will most likely need to be tweaked for each new client integrating your components. The QA process for pushing out an update to the widget is going to be difficult too. There are so many ways clients can use CSS and have it break your integration.

Ok, so if I don’t want to use an iFrame or be anal about my CSS, what can I do?

Enter the Shadow DOM!

Wow, that sounds spooky… What is the Shadow DOM you ask? It’s an API for DOM encapsulation and we all know how important encapsulation is.

Shadow DOM allows hidden DOM trees to be attached to elements in the regular DOM tree — this Shadow DOM tree starts with a shadow root underneath which can be attached to any elements you want in the same way as the normal DOM.> -Using Shadow DOM

The most basic approach to creating a shadow is to attach it to any DOM element:

const shadow = element.attachShadow({mode: 'open' || ‘closed’});

The mode open or closed allows you to specify whether or not the page’s JavaScript can interact with the Shadow DOM. Open means it can interact and closed means it cannot.

After I’ve created my shadow element, I can append to it just like any normal DOM node.

const shadow = element.attachShadow({mode: 'open' || ‘closed’}); 
const styleNode = document.createElement(“style”);
style.textContent = `
    background: blue;
    font-size: 18px;
`;

shadow.appendChild(styleNode);

const contentNode = document.createElement(“div”);
contentNode.textContent = `Hello World`;
shadow.appendChild(contentNode);

The above code will create a shadow node, append a node style to the Shadow DOM, and append a div saying Hello World. The style will now be isolated, only affecting the shadow tree and not contaminating the parent. Success!

However, the above example is very verbose and simple and is showing us just the bare metal implementation of the Shadow DOM. It’s only scratching the surface of what the Shadow DOM can do. It’s not all that complicated and it’s pretty well supported right now.

Shadow DOM with React

I’d like to take a quick moment to highlight a really useful package that I’ve used in the past and really gave me the feeling of “WOW, I might actually be able to use this in production.”.

React Shadow makes working with the shadow DOM with React easy as pie! The example I used above with react-shadow will look like this:

import root from 'react-shadow';

export default () =>  (
    <root.div>
        <div>Hello World</div>
        <style type="text/css">
            background: blue;
            font-size: 18px;
        </style>
    </root.div>
);

Now, if that isn’t magic, I don’t know what else is. So, take a step with me into the future. Let’s not be afraid of our Shadow DOM and let’s make beautiful composite user experiences together!