<![CDATA[ Andrico Karoulla - freeCodeCamp.org ]]> https://www.freecodecamp.org/news/ https://cdn.freecodecamp.org/universal/favicons/favicon.png <![CDATA[ Andrico Karoulla - freeCodeCamp.org ]]> https://www.freecodecamp.org/news/ Eleventy Sun, 24 May 2026 16:29:53 +0000 60 <![CDATA[ What is a Component Library? When to Build Your Own and When to Use Someone Else's ]]> https://www.freecodecamp.org/news/what-is-a-component-library-when-to-build-your-own/ 66bb74b0b66bb7f4d49a11bb Tue, 13 Aug 2024 14:58:56 +0000 If you've built a frontend project in the last five years, you will have likely written some components, and maybe even used a component library.

Components and libraries have been an important part of the web development landscape for multiple decades now, and they're as useful and as important as ever.

Now, there are going to be times when you should build your own component library, and times when it's better to use a third-party option. By the end of this article, you'll know the benefits and drawbacks of each approach, and you'll be able to make the right call for your next project.

Table of Contents:

An Analogy: What if Pre-Recorded Music Albums Didn't Exist

I’m a huge music fan. One of my favourite pastimes is to put on a record and listen to it front to back. A music album is simple in concept: it’s a suite of recorded tracks by an artist and is considered a complete and coherent set of songs.

But what if recorded music didn’t exist? Instead of putting songs to tape, CD, or mp3 (or FLAC if you’re that way inclined), you could only listen to an album if the artist played it live for you. You’d need to go to the band, ask them to set up their equipment, and get them to play the album front-to-back. They’d need to play it the same way every time to ensure that everyone had the exact same experience.

The cracks would start to show. It’s not an efficient way to ensure that anyone interested in the band’s music could listen to it. If Taylor Swift were to play her song Fortnight personally for every person who listened to it on Spotify, it would take her 3,179 years. And that doesn’t account for any plane travel. Artists would get bored, maybe even careless, leading to a poorer experience for their listeners.

So how does this relate to web development? Every time you build a UI control, you have to ensure it’s functioning, robust, and accessible. You’ll get bored if you keep rewriting the same UI every time. Mistakes will slip through, leading to a bad experience for your end users.

Why I'm Writing this Guide

I’ve been a web developer for nearly 10 years, and I’ve written hundreds of components, often the same UI pattern many times. I’ve used dozens of component libraries, and have built admin dashboards, component libraries, mobile applications, blogs, Figma plugins, VSCode extensions, and more.

In this article, I'll discuss the role of components and libraries in web development, and whether developers should write their own.

I'm also the creator of Component Odyssey, a course that'll teach you to build your own component library that works in any frontend framework.

What is a Component?

When building user interfaces, we don’t write all the HTML markup from scratch every single time. We write our UIs using components – reusable building blocks that encapsulate common UI patterns. Writing a component lets you use it multiple times in a single project or even in independent projects.

Here I’ve written a counter component. I’ve written it once and used it in multiple places on the page.

<body>
  <div class="wrapper">
    <counter-button></counter-button>
    <counter-button></counter-button>
    <counter-button></counter-button>
  </div>

  <script type="module">
    import { LitElement, html } from 'lit';

    class CounterButton extends LitElement {
      constructor() {
        super();
        this.count = 0;
      }

      static properties = {
        count: { type: Number }
      };

      _increment() {
        this.count++;
      }

      render() {
        return html`
          <button @click=${this._increment}>Count: ${this.count}</button>
        `;
      }
    }

    customElements.define('counter-button', CounterButton);
  </script>
</body>

We tutorial creators like to demo counters like they’re going out of style – but a real-world application will contain dozens of different UI patterns written as components.

In this article, I’ll group CSS rules that provide styling for certain UI patterns under the components umbrella. The definition can get murky depending on whom you ask.

What is a Component Library?

Not all components are standalone. It makes sense for many components to be grouped within a single package, called a component library.

If you want your site to have a specific look or feel, you can use a component library. There are component libraries that:

  • offer components that adhere to a design specification.

  • offer multiple solutions for a specific UI pattern.

  • work with a specific toolchain

But they come in different shapes and sizes. The definition I’ve come to use when defining a component library is the following:

A component library is a set of reusable components that are cohesive in their utility, or appearance (or both). A great component library will help developers achieve their UI needs efficiently, while offering an exemplary experience for the end user.

What’s the Difference between a Component Library and a Design System?

I talk about guidelines and design systems later in this article, so I’ll take a moment to disambiguate them. It can be difficult to see where one ends, one begins, or one subsumes the other.

Design Systems

I see a design system as a specification for how things should look, feel, and behave. A design system can encompass a product, a brand, or a company to ensure consistency across the suite of experiences. A comprehensive design system will dictate everything from font families, font sizes, and spacing sizes, to UI patterns and copy guidelines.

A few of the most well-known design systems include:

While many design systems are specific to companies, there are design systems, like Material Design, that teams across the globe use to shortcut their way to building familiar feeling products. You’ve probably used a handful of products that use Material Design principles, but they’re certainly not free from basic usability issues.

Component Libraries

As for component libraries, they may or may not be the code implementation of a design system. If you work for a company with a design system, it’s likely that the corresponding component library (if one exists) is tightly integrated with it.

For instance, Google’s Material Web is a web component implementation of Material Design. Base Web and Lightning Web Components are also open source.

A Brief History of Component Libraries

The concept of UI components (or widgets) has been around for a long time. If you want to see a museum’s worth of retro user interfaces, grab some popcorn and watch this 2+ hour video of "all the widgets" from 1974-1990.

From the early 2000s, we started seeing component libraries made to help developers build for the web.

The web browser landscape back then was unrecognisable from what we see now. Versions of Internet Explorer deviated away from the spec entirely, which was particularly problematic given the huge market share that IE had back in the day. Internet Explorer 6 was famously known for being a pain to develop for. This was mainly due to its incorrect implementation of the box model, and lack of CSS2 support.

💡 TIL, Internet Explorer supported a “quirks mode” that let developers write non-standard HTML and CSS to appease older browsers that didn’t support the standards.

Fortunately, when I started web development in earnest, many of these issues were ironed out. By this point, there were still a handful of libraries that made writing complex interfaces with cross-browser support a little easier.

jQuery UI, the first component library I used, supported accordions and other widgets. But the browser is constantly evolving, and we now have a native way of implementing this accordion pattern using the details and summary elements, available in all browsers in 2020.

With these elements, you can get pretty far along creating interactive accordions without JavaScript.

Contrast this with 2009, before these elements had been implemented in any browser. It required a fair bit of JS to get working. Have a look at the jQuery UI v1.7 source code, and CTRL+F “accordion” if you want to see how web devs were implementing accordions 15 years ago.

Over the next couple of decades, the capabilities of the web grew. More powerful devices meant more powerful browsers. More powerful browsers meant web applications became more ambitious.

Developers responded by creating the tools to help us build these applications by allowing us to create UIs using building blocks – that is, a component model. We saw a proliferation of these component-based frameworks. I’m talking Angular, React, and Vue. And each has its own rich ecosystem of component libraries.

There's a reasonable argument to be made that there has been an over-correction and that the frontend landscape is now oversaturated with tools that are too powerful for most people's needs...but let's not go there.

What Makes a Good Component Library?

The challenge with building a component library is that they’re not a one-and-done deal. Many of the most popular libraries have been around for years and have had heaps of research, usage feedback, and contributions to get them to where they are now.

I’ve found that a good component library often has the following traits:

  • It understands the problems of its target developers and solves those problems well

  • It has great documentation

  • It ensures a good experience for the end-user

  • It’s robust and caters to appropriate input modes and devices.

On the flip side, a way to discern if a component library isn’t good is if it doesn’t consider accessibility, has an inconsistent API, has little to no project stewardship, or has no clear and consistent documentation.

What Are the Benefits of Using a Component Library?

We know what a good component library looks like – so let’s see how one can make your life, and the lives of your users, a little better.

Component Libraries Save You Time

If you’re on a project with a tight deadline, it’s important to be efficient. But efficiency shouldn’t come at the cost of crafting a robust web experience. Using a component library lets you spend less time reinventing the wheel and more time focusing on the finer details.

Component Libraries Make You and Your Users Happier

We’re not motivated by repetitive work. We enjoy technical challenges, and writing the same components over and over again is not a fun challenge. We’ve already spoken about what happens when we get bored and let mistakes slip through.

If you wanted to implement a dialog component from scratch, you’d need to:

  • Handle focus trapping correctly

  • Make the rest of the page inert

  • Position the dialog correctly

  • Ensure that it works with assistive technologies

It takes work to remember and implement the above, but the consequence of getting it wrong can render your interface literally unusable. Such is the case if you incorrectly handle focus.

By using a component library that’s been built with the end users in mind, you can prevent the risk of introducing broken experiences, while spending less time rebuilding the same components.

Component Libraries Lead to Consistent Experiences

If you work for a company with several different web applications, they’ll generally follow a set of guidelines. These guidelines might dictate the colour palette to use, the size of your typography, or how UI elements should look and behave.

But you increase the likelihood of your application deviating from the style guide if you’re re-writing components. By having a component library, you can more easily audit your component’s UI against the brand guidelines so they look great, wherever they’re used.

Uber has several different apps that share the same user interface elements. I’m almost certain that they use the same component library across these apps. That way each new app is virtually guaranteed to adhere to the brand’s guidelines.

Different Uber apps side by side, showing how similar they are in terms of appearance

What Are the Drawbacks of Using a Third-Party Component Library?

The benefits I’ve mentioned above are irrespective of whether you’re using your own component library or a third party. If you or your team has decided that they don’t want to build a library, and instead lean on a third-party, then it’s worth considering the following.

Vendor Lock-in

By choosing a component library, you’re picking a partner who will greatly impact how you write your frontend code and how your interfaces will look and behave.

The former will have a big impact on you, and the latter will have a big impact on your end users. Using a component library is locking you into the standards of that component library.

The library could introduce massive breaking changes in a major version that could require dedicated development time, and a lot of testing to ensure that no serious regressions were introduced.

A few years back I used React Admin to build a complex admin dashboard to an internal division. The library offered a suite of components specifically dedicated to fetching and displaying complex data.

Because our application at the time relied heavily on React Admin, upgrading between major versions was challenging, especially as many of the internal tools used by React Admin had been swapped out for others. The change surface was huge, and we spent a good deal of time upgrading and flagging the issues that we spotted.

I don’t believe that building our own solution would have saved us any time in the long term, but this kind of vender lock-in is worth considering, especially before going all in on a tool.

Code Bloat

Shocking as it is, libraries with a lot of components tend to be written using lots of code. Code that you download when installing dependencies, and code you're sending over to your end users.

Modern tooling makes it easier to perform bundle optimisations like tree-shaking to remove unused code, but there’s no guarantee that you’re removing all of the code that your users won’t need.

Unless you dig deep into the libraries that you’re using, you may not be aware of all the separate packages they’re importing. You could end up with hundreds of unnecessary dependencies. The folks in the e18e community have been working hard at bringing this problem to light, while also fixing it too.

Many of these problems could also be said about rolling out your own component library. The biggest difference is that you have stewardship over your component library. You’re able to define how it solves your specific problems, and you have control over improving its shortcomings.

The Different Shapes a Component Library Can Take

The initial proposal for the World Wide Web was a tool to improve communication between researchers at CERN. The proposal outlined how documents could be shared, and linked to one another through the use of hypertext.

This is the fundamental cornerstone of the web, and we still use the humble <a> tag to link between other HTML documents across the web.

But the web has grown in scope over the last few decades, and the browsers we use to navigate the web have become beasts of their own. The browsers today can enable powerful forms of creative expression, and the running of native-like software.

There are hundreds of different solutions out there, some general purpose, others hyper-niche, but finding the right tool for your next project requires a complex decision process that might look like this:

The different kinds of component libraries, and when you should use them. The diagram's context is explored below

This isn’t a comprehensive list of ALL use cases or component library types, but it illustrates how component libraries differ in terms of:

  • the technologies involved.

  • the levels of abstraction they offer.

  • the problems they solve.

Let’s take a look at some of the most common component library types.

💡 A quick side note: If you're interested in building your own web component library, then consider checking out my course Component Odyssey. You'll learn how to build and publish a component library that works in any frontend framework.

Utility Class Libraries / CSS Style Guides

For me, Bootstrap is the first that comes to mind. Back in the day, if you wanted to give your site a quick lick of paint, you’d drop the CDN link to the bootstrap CSS file and immediately get that Bootstrap look. It was everywhere in the mid-2010s.

A demo example of a Bootstrap web, circa 2013

The technical scope of these kind of tools range from

  • A single CSS file (Pico)

to

  • A toolchain to generate CSS classes based on your configuration (Tailwind)

Dozens of other tools, like Open Props, fit somewhere in between.

Off-the-Shelf Component Libraries

If you’re building an interactive web application, you might just want to grab a suite of components that look great and function well. There are many of these off-the-shelf component libraries that give you everything you need and more.

Regardless of which framework you’re writing your app with, there’s likely to be a set of great looking components for you to use.

Another great component library is Shoelace, which provides dozens of fully interactive and fully-styled components.

What makes libraries like Shoelace particularly interesting is that it’s built using web components, the browser’s built-in way of writing components. Building your UIs with tools like Shoelace gives you the added benefit of being able to use them across different frontend frameworks. This is something I’ve spoken a little about in the past.

Here's the same Shoelace component being used in Vue and React:

Shoelace buttons in Vue and React

Un-styled Components

Depending on your project’s specs, you might not have the luxury of using an off-the-shelf tool. Your design specs might be very specific.

I’ve seen teams roll out components at the first sign of friction. And in one case of a hand-rolled data picker, it led to a way worse user experience. In retrospect, using an un-styled component library would have given the team flexibility with appearance, while ensuring that the notoriously tricky time-related behaviour was correct.

That’s why you can reach for a library out there that offers completely un-styled components with flexible styling hooks. If it’s a good library, it’ll also take care of all those complex interactions. It’s a best of both worlds situation.

It’s easy to mess up a checkbox if you want to push beyond the styling hooks that the browser provides, unless you test with a wide-range of devices and input modes.

Radix is a popular example of a library, but it’s built using React.

Other examples of component libraries like this are Lion and HeadlessUI.

Copy-Pastable Component Libraries

Some developers might want the best of both worlds. They might want a component built by a trusted third-party library, while also having full control over the markup, styles, and functionality.

Libraries like ShadCN allow for this kind of work flow by allowing developers to copy and paste the component definition into their own projects, effectively letting them own the component.

Why Isn’t There One Component Library to Rule Them All?

At this point, it’s probably clear why no such single component library exists. We’ve taken a non-exhaustive look at different groups of component libraries.

There is, however, a movement to introduce a “Global Design System”, a concept spearheaded by Brad Frost.

In the announcement, Brad outlines that in the hundreds of projects he’s been a part of, many of the UI controls behave (or should behave) similarly across these various projects – but developers reimplement the same thing in every single project.

This has lead to lots of wasted time and effort, and inconsistencies between projects. This also expands to the existing component libraries out there. You’ll see that the keyboard behaviour for a combobox in React Aria, is different to that of the combobox in ShadCN.

Brad Frost is proposing a Global Design System as a set of web components that should be adoptable by almost any frontend project to ensure a baseline of functionality for the controls that are not yet available in HTML.

There are discussions going on within the Open UI to see how this could start taking shape within the next few years.

Should You Build Your Own Component Library?

This article has delved deeply into component libraries. And with all that context, you’ll inevitably start asking yourself, when you're staring at the empty HTML page for your next big project, whether you should build your own component library or use an existing one.

My first thought is: I don’t think you should build your own library.

I generally favour picking a battle-tested library. Particularly one that has:

  • Been used across thousands of projects

  • A strong community, in Discord or GitHub

  • Great documentation

  • A strong focus on accessibility

  • Worked with the strengths of the chosen framework

Most importantly out of all of these is to use a component library that puts care into building accessible components.

Take a combobox, for instance. It’s a search input and a select menu mixed into one. If you’ve built your own, you may get it looking good, and working with your mouse. But you’ll also need to consider:

  • Cross browser support

  • Tab and focus behaviour

  • Screen reader support

  • Handling states for async loading of search results

Konnor Rogers, who does excellent work in the web + web component space, has shared countless frustrations with his experiences building an accessible combobox. Here’s one such tweet he shared.

Screen reader support is particularly complex, and is worth of its own bullet-point list. To support screen readers, you’ll also need to handle:

  • live regions

  • interactive controls

  • selected items

  • support between different screen readers

As a side note, I only have access to Voiceover, meaning it’s difficult for me to test these complex UI patterns using different screen readers. Like browsers, there are differences between screen readers. In this article, Are We Live?, Scott O’Hara describes how there’s variance among the difference with how they treat the live regions.

This means it’s also up to you, as the developer, to pick a component library that you can trust has been developed with accessibility in mind. This is why it’s also important to pick a component library that has a strong community.

You should be able to:

  • See the bugs and issues others have flagged for a given library

  • Suggest (or even contribute) improvements and changes to the library

  • Discuss ideas with members of the community and build working relationships with active members of the community or even maintainers themselves

Finally, and not least, a great component library will consider much more than the aesthetics of its components. For a component library designed for the web, it should try it’s best to:

  • adhere to the Web Content Accessibility Guidelines (WCAG)

  • ensure that the components work across different input modalities (touch, keyboard, screen reader)

  • ensure that the components are usable for folks with additional requirements, like those living with vestibular disorders, vision impairments, or a broken hand.

When (and Why) It's Useful to Build Your Own Component Library

If I haven’t scared you off from building a component library, then let me contradict myself and explain why it can be a really good thing to build your own.

If you take the time to put care and attention into building a component library, then you’ll find yourself a becoming developer who better understands the browser platform, accessibility best practices, testing practices, and more.

But it doesn’t just stop there: there are some excellent reasons to build your own library.

For starters, you can build something tailored to your needs, and avoid some of the bloat you might get form an off-the-shelf component library. It’s up to you and your team to understand your end users, and you can build something specifically for them.

You also have the opportunity to experiment with novel approaches. If you have a hyper-niche problem, there might not be a component library out there to solves that need. It could be a component library that:

  • Visualises data in specific way

  • Has a distinct and unique visual identity

  • Is built on a new framework

That gives you the opportunity to build something tailored to your needs. You then have the opportunity to change and fix things as your needs change, or as you understand the problem space better.

Importantly, you’ll learn more about the web by doing so. If it’s your first time building a component library, it can be an opportunity to dive deeper into the HTML browser specs, or brush up on your web accessibility knowledge. This will improve your abilities as a web developer, which will serve you well in any frontend project in the future. It could even help you land your next job.

So whether you should build a component library depends on your end goals. Consider questions like:

  • Do I want to better understand the browser?

  • Do I want to build something quickly?

  • Do I want to make it usable for as many users as possible?

  • Do libraries exist that solve my current problem?

Depending on what your answers are, you can make the right call for your project.

Thanks for Reading!

Thanks for learning about component libraries with me. If you're interested in building your own web component library, then consider checking out my course Component Odyssey. You'll learn how to build and publish a component library that works in any frontend framework.

💡 I want to give a special shoutout to stephband (Mastodon, Bluesky) for proofreading and providing feedback.

]]> <![CDATA[ How to Use New CSS Features to Build a Progress Indicator ]]> https://www.freecodecamp.org/news/use-new-css-features-to-build-a-progress-indicator/ 66bb8e04b0d3ac3d7acde3ee Tue, 09 Jan 2024 15:39:50 +0000 For the last 7 months, I’ve had my head down building Component Odyssey. It’s been a richly fulfilling project and I’m eager for people to take the course and learn heaps about building component libraries using web components.

I’ve seen some incredible demos over the past year, and wanted to sink my teeth into some of these cool new features. So I used some downtime over the Christmas period to cram tons of new CSS features into a lesson progress indicator for the Component Odyssey platform.

The result is the following progress indicator that shows how much of the page the user has scrolled:

the fully completed progress indicator as it exists on Component Odyssey

Building it gave me some exposure to some of the latest CSS features like:

  • animation-timeline: scroll()
  • CSS trig functions, sin() and cos()
  • color-mix()
  • the @property at-rule

I know the risks of building something with a particular tool in mind. As the saying goes “When all you have is a hammer, then something something nails”.

Yes, I have a hammer, and I’m going to smash the walls down with it.

In this article, I’ll run through how to create a pared-down version of this swanky progress animation while still using all of the CSS features mentioned above. I’ll also show you how to gracefully handle browsers that don’t support these features through progressive enhancement.

If you want to follow along, then it’s best to use the latest versions of Chrome or Safari – currently Firefox doesn’t have general support for properties like animation-timeline. Get started by jumping into the starter Codepen.

If you want to peruse the finished code, you can check it out here.

How to Create the Markup

I’ve already provided a little markup to simulate a page with enough content that you'll need to scroll to get to the bottom. To get started creating the progress indicator, you’ll need to add some more markup.

The markup itself is really simple – we’ll only need to create 3 div elements.

The outer element is responsible for the positioning and layout of the loader. We’ll give this a class of wrapper.

The middle element is responsible for rendering the track to the screen. We’ll give this element a class of progress. We’ll later use an ::after pseudo-element to create the indicator thumb.

The innermost element will be used to create the circular hole in the middle, making the indicator look like a low-calorie doughnut. This will have a class of inner.

Take a look at the following if you need a hand visualising the structure:

A visual representation of the information outlined above Illustration of the markup structure

Provide the following markup as the first child of the main element creates the following markup:

<div class="wrapper">
    <div class="progress">
        <div class="inner"></div>
    </div>
</div>

Applying the Base CSS to the Markup

You’ll also need to apply the following styles to give the markup a base visual appearance:

.wrapper {
    --size: 80px;

    position: fixed;
    width: var(--size);
    aspect-ratio: 1/1;
    top: 24px;
    left: 24px;
    display: flex;
    align-items: center;
    justify-content: center;
}

.progress {
    --track-size: 16px;

    width: var(--size);
    aspect-ratio: 1/1;
    border-radius: 50%;
}

.inner {
    position: absolute;
    width: calc(100% - var(--track-size));
    aspect-ratio: 1/1;
    background: var(--background-color);
    border-radius: 50%;
    top: 0;
    left: 0;
    right: 0;
    bottom: 0;
    margin: auto;
}

Most of the CSS here shouldn’t come as a shock to you, so I won’t go over it line by line. But I will touch on some of the more interesting bits.

In .wrapper, we’re fixing the element to the top left of the screen, and we're using Flexbox to center the children horizontally and vertically.

💡 I learned that if you want an element to share the same value for both its width and height, you just set the width and use aspect-ratio: 1/1. The browser will implicitly set the height.

This is a neat trick because you won’t have to define the same value twice, and it makes it easier to guarantee that the width and the height share the same value.

As for the .inner element, I’ve used a mix of absolute positioning and the margin: auto to center it in the middle of the .progress element. We’ve also deducted the --track-size from the full width of the container, to ensure that it’s correctly positioned over the .progress element.

You won’t be able to see anything just yet, but if you add a temporary background-color: red to the .progress element, it should render as follows:

a basic doughnut shaped indacator without any animation Image showing the current state of the progress indicator - a red circle

How to Create an Animated Progress Indicator

Creating a scroll-driven animation of this kind requires a lot of new CSS features that you may have not used before. Instead of learning everything all at once, we’ll start by decoupling the animation from the scrolling mechanics.

That way, by the end of this section, you should have the following animation that plays automatically:

A progress indicator playing automatically in an infinite loop Animation showing the initial stage of the progress indicator

We’ll start by creating a new animation called load:

@keyframes load {
    0% {
        --progress: 0%;
    }

    100% {
        --progress: 100%;
    }
}

All this does is move the progress along from 0 to 100 over the course of the animation.

Using conic-gradient to Indicate the Current Progress

In your .progress rule, add the following CSS properties:

.progress {
    # Existing rules

    animation: load linear 1s infinite;
    background: conic-gradient(
        from 0deg at 50% 50%,
        var(--red) var(--progress),
        var(--black) var(--progress)
    )
}

The animation property should be pretty straightforward, but there’s a lot going on with the background rule, so let’s step through it.

For starters, we’re using a conic-gradient as it makes it easy for us to animate the background over 360 degrees, in the way shown in the animation above. We’re starting from the 0deg position, which is top and center. We’re describing where we want the center of the gradient to be using at 50% 50%.

conic-gradient(from 0deg at 50% 50%) alone would render something like the following:

A visualisation of a radial gradient starting from the center, like a sonar radar Image showing a red circle witha slight gradient, the result of conic-gradient(from 0deg at 50% 50%) alone

Hopefully I’ve made it clear why that’s the case.

As for the the second and third arguments of the conic-gradient function, we’re linking the --progress variable (which is being calculated via the load animation) to the two colors. The --red is used to denote the completed progress, while the --black is used to denote the remaining position.

It might be confusing why they share the same --progress value. The --progress value for the --red value denotes where the gradient stop ends, while the --progress value for the --black denotes where the gradient stop begins.

Because it’s the last stop on the gradient, it’s implied that it ends at 100%. By setting the same --progress value to both stops in the gradient, we create a hard transition between the two colors. Without doing so, our progress indicator (with a --progress value set to 16%) would look like this:

The progress indicator where the color gradient goes slowly from red to black Progress indicator with a red to black gradient and no animation

Animating the Gradient

Now, something strange is probably happening. Instead of your progress indicator transitioning gracefully across the entire perimeter of the circle, it’s instead flashing between the black and red.

Why is this happening?

This is because we’re making the browser interpolate between percentage values, which is something it can’t do automatically. Even though we’ve given the --progress variable a percentage value, the browser doesn’t assume that it’s always going to be a percentage value.

We can solve this by telling the browser that --progress will always be a percentage value. We can do this by explicitly defining the --progress property using the @property CSS rule. Just add the following to the top-level of your CSS:

@property --progress {
    syntax: '<percentage>';
    inherits: false;
    initial-value: 0%;
}

We’re telling the browser that --progress should only support percentage values and that the initial value is 0%. We’re also not interested in having the custom element inherit its value.

Finally, I don’t quite like the use of the --black variable to signify empty progress. It looks too stark. I’d like to create a lighter shade created from the black to ensure a more homogenous visual palette. This is something we can easily achieve using the color-mix() CSS function.

Jump back up to the :root CSS rule and add the following variable:

:root {
    # your other CSS variables

    --grey: color-mix(in srgb, var(--black), transparent 60%);
}

The color-mix function lets us mix two colors together. In this case, we’re mixing the color stored in our black variable with some transparency, which will result in a partially see-through grey color. You’ll need to replace the reference to the --black variable in the conic-gradient function with --grey to see the color change in effect.

Now that we’ve defined our custom property, the browser will be able to interpolate the correct values during the entire animation, so it should now transition smoothly from start to finish.

A progress indicator playing automatically in an infinite loop Showing the animation functioning properly

How to Enable Scroll-driven Animations

The next stage of our animation journey is to tie our animation to the scrolling of the page.

This should only take us a couple of lines of CSS.

You’ll need to do two things: first adjust the animation property in your .progress class to remove the infinite value, and to change the duration from 1s to 1ms. We can’t remove the value altogether because Firefox needs it for scroll animations to work.

Next update your .progress class to include the following:

.progress {
  # other CSS properties

    animation-timeline: scroll(nearest block);
}

The animation-timeline property tells the browser to tie the progress of the animation with a specific timeline. In this case it’s the scroll timeline, which we specify using the scroll function.

You can see I’m providing two arguments to scroll(): nearest and block.

The nearest value is used to tie the animation to the nearest ancestor that has a scrollbar. In this case it’s the document. If you’re certain that you only ever want to tie the animation to the document’s scrollbar, then you can swap out nearest for root instead.

The block property denotes the axis that we want to tie our animation to. For most cases this will be the vertical scrollbar, but for vertical writing modes, this will be the horizontal scrollbar.

Now that you’ve hooked up the animation to your page’s scroll, you should be able to scroll up and down the page and watch how your animation changes accordingly.

The basic progress indicator whose animation is tied to the progress of the page scroll Demo showing a user scorlling and the animation of the scroll element changing

How to Progressively Enhance Your Scroll Animation

While it’s exciting to use these new features in the browser, the animation-timeline property doesn’t have universal support across browsers yet. It’s still very new in Chrome, and it’s only available in Firefox behind a feature flag. If you try opening the code in Firefox, you’ll notice that the progress ring just appears with a finished animation.

In cases like this, it’s important to set up a solid base experience for all browsers, and then progressively enhance your webpage with the newer features on compatible browsers. Because the progress indicator isn’t critical for the application to function, we can just hide it away if the browser doesn’t support the animation-timeline property.

We can do this by moving our .wrapper, .progress, and .inner classes within CSS’s @supports at-rule, like so:

@supports (animation-timeline: scroll()) {
    .wrapper {}

    .progress {}

    .inner {}
}

Doing so ensures that if the browser doesn’t support scroll(), then it will ignore all of the styles contained within the rule.

How to Add the Indicator Thumb

The final thing for us to add is a cool little indicator thumb, to both give our progress indicator a little more visual interest and to also let us play with the swanky CSS trigonometric functions.

The indicator thumb is the little circular element that indicates the exact current progress

The indicator thumb placed at 4 o'clock on the progress indicator Illustration showing the indicator thumb (a dark dot on the progress indicator)

Creating the Thumb's Visual Appearance

To create the indicator thumb, start by writing the following CSS inside of the @supports block:

.progress::after {
    --radius: calc(var(--size) / 2);
    --track-offset: calc(var(--track-size) / 4);

    content: '';
    position: absolute;
    aspect-ratio: 1/1;
    width: calc(var(--track-size) / 2);
    background: var(--red-dark);
    border-radius: 50%;
    left: calc(50% - var(--track-offset));
    top: calc(50% - var(--track-offset));
    transform: scale(1.5);
}

This creates a new pseudo-element off of the .progress class, and gives it its visual appearance. Once added, the indicator thumb should live in the center progress element. We’re using the --track-offset variable to position the thumb correctly by taking into consideration the dimensions of the track.

⚠️ I’m also increasing the size of the thumb to using scale() so that its size in the DOM is still relative to the --size variable. This just means a little less math for us to worry about when setting the value for --track-offset. Using scale() makes it easy to change the size of the element without causing a shift in the DOM.

The next step is to use the color-mix() function again to create a dark red from the base red color. Add the following to your :root rule.

:root {
    # your other CSS variables

    --red-dark: color-mix(in srgb, var(--red), var(--black) 60%);
}

Your progress indicator should look less like a UI widget and more like a dartboard:

the thumb is in the center of the progress indicator Animation/indicator thumb in progress

Positioning the Thumb on the Track

Let’s position the thumb on to the track.

.progress::before {
  # rest of properties

    translate: calc((var(--radius) - var(--track-offset)) * cos(var(--angle)))
      calc((var(--radius) - var(--track-offset)) * sin(var(--angle)));
}

This is probably the gnarliest piece of CSS in this entire article. It isn’t anywhere near as complex if we break it down in half. Here’s the first half:

calc((var(--radius) - var(--track-offset)) * cos(var(--angle)))

This uses a little trigonometry to calculate the position of the thumb based on the current angle (which will be tied to the scroll progress) and the radius of the circle. The cos() function is used to determine the horizontal value of the position.

The second half of the value is identical, except we’re using the sin() function to determine the vertical position of the indicator:

calc((var(--radius) - var(--track-offset)) * sin(var(--angle)))

⚠️ I’m not going to use this article as an introduction into trigonometry, but I can point you in the direction of some amazing resources:

You may have noticed that I’ve specified a variable, --angle, that I haven’t yet defined. Because we’ll be animating the --angle, we need to explicitly define it using the @property rule, much like we did for the --progress property. The only difference is that we’ll need to specify a different syntax value. Instead of <percentage> the value will need to be <angle>:

@property --angle {
    syntax: '<angle>';
    inherits: false;
    initial-value: -90deg;
}

By setting the initial value to -90deg, we ensure that the thumb is placed at the 12 o’clock position on the progress indicator.

Your indicator should now look like this:

The thumb is positioned at the top center of the progress indicator Showing the thumb now on the track of the progress indicator

The next step is to create the animation for the thumb and then bind the animation timeline to the scroll position of the page.

Animating the Thumb Indicator

Let’s start by creating a new animation:

@keyframes rotate {
    0% {
        --angle: -90deg;
    }

    100% {
        --angle: 270deg;
    }
}

Over the course of the entire animation, the thumb will rotate 360 degrees, performing a full revolution over the progress element.

Finally we need to add the following two properties to the thumb:

.progress::after {
    # other CSS properties

    animation: rotate linear 1ms;
    animation-timeline: scroll(nearest block);
}

Doing so applies the rotate animation to our thumb and binds it to the scroll position.

Everything should now work flawlessly:

The completed progress indicator UI Final product showing the animation working smoothly as a user scrolls

Wrapping up

I created this progress indicator specifically to become more familiar with the amazing tools that CSS has shipped in the last couple years. Hopefully you learnt just as much from this lesson as I did making it.

There were other CSS features I wanted to explore, like popover and :has but I couldn’t find a way to fit them in with this animation. If you find this article interesting, I might try and create more little changes to the Component Odyssey platform, using cutting-edge CSS features.

By wary, because a lot of the CSS features I’ve covered are still very new. So you should check the browser support before using them in production.

If they’re not supported in one or more browsers, but you’re desperate to use them, then use a progressive enhancement strategy (as I went over in this tutorial) to ensure that those with compatible browsers get the full experience, while still offering users of unsupported browsers a solid baseline experience.

If you enjoyed this article, and would love to learn more about Component Odyssey or other cool web development tips, then consider subscribing to the newsletter.

Resources

]]> <![CDATA[ How to Write Components that Work in Any Framework ]]> https://www.freecodecamp.org/news/write-components-that-work-in-any-framework/ 66bb8e07bec1b237336e9685 Mon, 06 Nov 2023 20:25:12 +0000 The browser has a built-in way of writing reusable components in the form of web components. They’re an excellent choice for building interactive and reusable components that work in any frontend framework.

With that said, writing highly interactive and robust web components isn’t simple. They require a lot of boilerplate and feel much less intuitive than the components you may have written in frameworks like React, Svelte, or Vue.

In this tutorial, I’ll give you an example of an interactive component written as a web component, and then refactor it using a library that softens the edges and removes heaps of boilerplate.

Don’t sweat it if you’re not familiar with web components. In the next section, I’ll do a (brief) overview of what web components are, and what they’re made out of. If you have some basic experience with them, you can skip the next section.

What are Web Components?

Before web components, the browser didn’t have a standard way of writing reusable components. Many libraries solve this problem, but they often run into limitations like performance, interoperability, and issues with web standards.

Web components are a technology made up of 3 different browser features:

  • Custom elements
  • Shadow DOM
  • HTML Templates

We’ll do a quick crash course covering these technologies, but it’s by no means a comprehensive breakdown.

What are Custom Elements?

With Custom Elements you can author your own custom HTML elements that you can reuse across your site. They can be as simple as text, images, or visual decorations. You can push them further and build interactive components, complex widgets, or entire web applications.

You’re not just limited to using them in your projects, but you can publish them and allow other developers to use them on their sites.

Here are some of the reusable components from my library A2K. You can see that they come in all shapes and sizes, and have a range of different functionalities. Using them in your projects is similar to using any old HTML element.

A small collection of web components from the A2K library A small collection of web components from the A2K library

Here’s how you’d use the progress element in your project:

<!DOCTYPE html>
<html>
    <head>
        <title>Quick Start</title>
        <meta charset="UTF-8" />
    </head>

    <body>
        <!-- Use web components in your HTML like regular built-in elements. -->
        <a2k-progress progress="50" />

        <!-- a2k web components use standard JavaScript modules. -->
        <script type="module">
            import 'https://cdn.jsdelivr.net/npm/@a2000/progress@0.0.5/lib/src/a2k-progress.js';
        </script>
    </body>
</html>

Once you’ve imported the third-party scripts, you can start using the component, a2k-progress in this case, just like any other HTML element.

If you’re building your own web components, there’s virtually no limit to how complex you can make your custom elements.

I recently created a web component that renders a CodeSandbox code editor in the browser. And because it’s a web component, you can use it in any framework you like! If you’d like to learn a little more about that, you can read more here.

What is the Shadow DOM?

If you have a working knowledge of CSS, you’ll know that vanilla CSS is scoped globally. Writing something like this in your global.css:

p {
  color: tomato;
}

will give all p elements a nice orange/red color, assuming that no other, more specific CSS selectors are applied to a p element.

Take this select menu, for example:

A select menu component with a visual design reminiscent of the old Windows operating systems

It has a distinct character which is driven by the visual design. You might want to use this component, but if your global styles affect things like the font family, the color, or the font size, it could cause issues with the appearance of the component:

<head>
    <style>
        body {
            color: blue;
            font-size: 12px;
            font-family: system-ui;
        }
    </style>
</head>

<body>
    <a2k-select></a2k-select>
</body>

The same select menu, but with a lot of its defining characteristics overridden by global CSS.

This is where the Shadow DOM comes in. The Shadow DOM is an encapsulation mechanism that prevents the rest of the DOM from interfering with your web components. It ensures that the global styles of the web application don’t interfere with any components that you consume. It also means that component library developers can author their components with the confidence that they’ll look and behave as expected across different web applications.

There’s a lot more nuance when it comes to the Shadow DOM, as well as other features that we’re not going to touch on in this article. If you’d like to learn more about web components though, I have an entire course (Component Odyssey) dedicated to teaching you how to build reusable components that work in any framework.

HTML Templates

The last feature in our whistle-stop tour of web component features is HTML Templates.

What makes this HTML element different from other elements, is that the browser doesn’t render its content to the page. If you were to write the following HTML you wouldn’t see the text “I’m a header” displayed on the page:

<body>
    <template>
        <h1>I'm a header</h1>
    </template>
</body>

Instead of being used to render the content directly, the content of the template is designed to be copied. The copied template can then be used to render content to the page.

You can think of the template element much like the template for a 3D print. The template isn’t a physical entity, but it’s used to create real-life clones.

You would then reference the template element in your web component, clone it, and render the clone as the markup for your component.

I won’t spend any more time on these web component features, but you’ve probably already noticed that to write vanilla web components, there are a lot of new browser features that you need to know and understand.

You’ll see in the next section that the mental model for building web components doesn’t feel as streamlined as it does for other component frameworks.

How to Build a Basic Web Component

Now that we’ve briefly covered the fundamental technologies powering a web component, here’s how to build a hello world component:

const template = document.createElement('template');
template.innerHTML = `<p>Hello World</p>`;

class HelloWorld extends HTMLElement {
    constructor() {
        super();
        this.attachShadow({ mode: 'open' });
        this.shadowRoot.append(template.content.cloneNode(true));
    }
}

customElements.define('hello-world', HelloWorld);

This is the most simple component you can write, but there’s already so much going on. For someone completely new to web components, and without the background knowledge I provided above, they’re going to be left with a lot of questions, and a lot of confusion.

For me, there are at least two key reasons why web components can be challenging to write, at least within the context of the hello world examples.

The markup is decoupled from the component logic

In many frameworks, the markup of the component is often treated as a first-class citizen. It’s often the content that gets returned from the component function, or has direct access to the component’s state, or has built-in utilities to help manipulate markup (like loops, conditionals, and so on).

This isn’t the case for web components. In fact, the markup is often defined outside of the component’s class. There’s also no built-in way for the template to reference the current state of the component. This becomes a cumbersome limitation as the complexity of a component grows.

In the world of frontend, components are designed to help developers reuse markup in several pages. As a result, the markup and the component logic are inextricably linked, and so they should be colocated with one another.

Writing a web component requires understanding all of its underlying technologies

As we saw above, web components are made up of three technologies. You can also see in the hello world code snippet, that we explicitly need to know and understand these three technologies.

  1. We’re creating a template element and setting its inner HTML
  2. We’re creating a shadow root, and explicitly setting its mode to ‘open’.
  3. We’re cloning our template and appending it to our shadow root
  4. We’re registering a new custom element to the document

There’s nothing inherently wrong with this, since web components are supposed to be a “lower-level” browser API, making them prime for building abstractions on top of. But for a developer coming from a React or a Svelte background, having to understand these new browser features, and then having to write components with them can feel like too much friction.

More Advanced Web Components

Let’s take a look at a more advanced web component, a counter button.

A simple counter button. There's a clickable button, and some text showing how many times the button has been clicked

You click the button, and the counter increments.

The following example contains a few extra web component concepts, like lifecycle functions and observable attributes. You don’t need to understand everything going on in the code snippet. This example is really only used to illustrate how much boilerplate is required for the most basic of interactive interfaces, a counter button:

const templateEl = document.createElement("template");

templateEl.innerHTML = `
<button>Press me!</button>
<p>You pressed me 0 times.</p>
`;

export class OdysseyButton extends HTMLElement {
  constructor() {
    super();
    this.attachShadow({ mode: "open" });
    this.shadowRoot.appendChild(templateEl.content.cloneNode(true));
    this.button = this.shadowRoot.querySelector("button");
    this.p = this.shadowRoot.querySelector("p");
    this.setAttribute("count", "0");
  }

    // Note: Web components have lifecycle methods,
  // If we're setting event listeners when the component is added to the DOM, it's our job to clean
  // them up when it gets removed from the DOM
  connectedCallback() {
    this.button.addEventListener("click", this.handleClick);
  }

  disconnectedCallback() {
    this.button.removeEventListener("click", this.handleClick);
  }

  // Unlike frameworks like React, Web Components don't automatically rerender when a prop (or attribute)
  // changes. Instead, we need to explicitly define which attributes we want to observe.
  static get observedAttributes() {
    return ["disabled", "count"];
  }

  // When one of the above attributes changes, this lifecycle method runs, and we can
  // react to the new attribute's value accordingly.
  attributeChangedCallback(name, _, newVal) {
    if (name === "count") {
      this.p.innerHTML = `You pressed me ${newVal} times.`;
    }
    if (name === "disabled") {
      this.button.disabled = true;
    }
  }

  // In HTML, attribute values are always strings. This means that it's our job to
  // convert types. You can see below that we're converting a string -> number, and then back to a string
  handleClick = () => {
    const counter = Number(this.getAttribute("count"));
    this.setAttribute("count", `${counter + 1}`);
  };

As web component authors, we need to consider a lot of things:

  • Setting up the shadow DOM
  • Setting up the HTML templates
  • Cleaning up event listeners
  • Defining properties that we want to observe
  • Reacting to properties when they change
  • Handling type conversions for attributes

And there are still so many other things to consider that I haven’t touched on in this article.

That isn’t to say that web components are bad and that you shouldn’t write them. In fact, I’d argue that you learn so much about the browser platform by building with them.

But I feel that there are better ways to write components if your priority is to write interoperable components in a much more streamlined and ergonomic way.

How to Write Web Components with Less Boilerplate

As I mentioned earlier, there are a lot of tools out there to help make writing web components much easier.

One such tool is called Lit, which is developed by a team at Google. Lit is a lightweight library designed to make writing web components simple, by removing the need for the boilerplate we’ve already seen above.

As we’ll see, Lit does a lot of heavy lifting under-the-hood to help cut down the total lines of code by nearly half! And because Lit is a wrapper around web components and other native browser features, all your existing knowledge about web components is transferable.

To start seeing how Lit simplifies your web components. Here’s the hello world example from earlier, but refactored to use Lit instead of a vanilla web component:

import { LitElement, html } from "lit";

export class HelloWorld extends LitElement {
  render() {
    return html`<p>Hello World!</p>`;
  }
}`

customElements.define('hello-world', HelloWorld);

There’s a lot less boilerplate with the Lit component, and Lit handles the two problems I mentioned earlier, a little bit differently. Let’s see how:

  1. The markup is directly defined from within the component class. While you can define your templates outside of the class, it’s common practice to return the template from the render function. This is more in line with the mental model presented in other UI frameworks, where the UI is a function of the state.
  2. Lit also doesn’t require developers to attach the shadow DOM, or create templates and clone template elements. While having an understanding of the underlying web component features will help when developing Lit components, they’re not required for getting started, so the barrier for entry is much lower.

So now for the big finale, what does the counter component look like once we’ve migrated it over to Lit?

import { LitElement, html } from "lit";

export class OdysseyCounter extends LitElement {
  static properties = {
        // We define the component's properties as well as their type.
        // These properties will trigger the component to re-render when their values change.
        // While they're not the same, you can think of these "properties" as being
        // Lit's alternatives to "observed attributes"
        // If the value is passed down as an attribute, Lit converts the value
        // to the correct type
    count: { type: Number },
    disabled: { type: Boolean },
  };

  constructor() {
    super();
        // There's no need to create a shadow DOM, clone the template,
        // or store references to our DOM nodes.
    this.count = 0;
  }

  onCount() {
    this.count = this.count + 1;
  }

  render() {
        // Instead of using the attributeChangedCallback lifecycle, the
        // render function has access to all of the component's properties,
        // which simplifies the process of manipulating our templates.
    return html`
      <button ?disabled=${this.disabled} @click=${this.onCount}>
        Press me!
      </button>
      <p>You pressed me ${this.count} times.</p>
    `;
  }
}`

The amount of code we’re writing is cut down by almost half! And this difference becomes more noticeable when creating more complex user interfaces.

Why am I going on about Lit?

I’m a big believer in web components, but I recognise that the barrier to entry is high for many developers. Writing complex web components requires understanding heaps of browser features and the education around web components isn’t as comprehensive as other technologies, like React or Vue.

This is why I think it’s important to use tools like Lit can make writing performant and interoperable web components much easier. This is great if you want your components to work within any frontend framework.

If you’d like to learn even more, this is the approach I teach in my upcoming course Component Odyssey. This course is excellent for anyone who wants to understand how to write components that work in any framework.

I do this by covering the absolute basics of web components, before moving on to tools like Lit that simplify the process of writing web components without complicating your development environment. By the end, you’ll learn how to build and publish a component library that works across any frontend framework.

If you want early-bird discount codes for Component Odyssey, then head on over to the site to get notified.

]]> <![CDATA[ How to Write Helpful Error Messages to Improve Your App's User Experience ]]> https://www.freecodecamp.org/news/how-to-write-helpful-error-messages-to-improve-your-apps-ux/ 66bb8dfb3e3fa59ecfecb866 Mon, 05 Apr 2021 22:07:00 +0000 Gone are the days of useless and generic error messaging.

A generic error message displaying: "Oops, something went wrong. Please try again later" Screenshot taken moments before a rage-quit

If you're here, you're likely concerned with making your user-facing products as delightful as possible. And error messaging plays an important role in that.

Having useful error messages can go a long way toward making a frustrating scenario for an end-user as pleasant as possible.

This article is split into two parts. The first builds context around error messages and why they're important. This section should be useful, regardless of whether you're a JavaScript developer or not.

The second part is a short follow-along to help get you started managing your own error messages.

The current state of error messaging

In a perfect world, error messages would be redundant and users would be able to use anything you've built a-okay, no problem-o. But errors will happen, and your end-users will run into them.

These errors can stem from:

  • Failing validation
  • Server-side failures
  • Rate limiting
  • Borked code
  • Acts of god

And when things go wrong, often the client-facing error messaging takes shape in one of two ways:

  • Generic errors with no meaningful information, e.g. Something went wrong, please try again later
  • Hyper specific messages from the stack trace sent by the server, e.g. Error 10x29183: line 26: error mapping Object -> Int32

Neither are helpful for our end-users.

For our users, the generic error can create a feeling of helplessness and frustration. If they get such a message, they can't complete an action, and have no way of knowing why the error happened and how (or if) they can resolve it. This can result in loss of end-user trust, loss of customer, or an angry review.

On the other hand, hyper-specific error messages are a leaky abstraction and shouldn't be seen by our end-user's eyes.

For one, these kind of errors provide implementation information about our server-side logic. Is this a security concern? probably? I'm no pen-tester.

Secondly, if we're in the business of crafting engaging user experiences, (and why wouldn't you be?) our error messages should feel human and be service-oriented. This is a sentiment shared in a number of resource I've come across, many of which of I've included in a further reading section at the end.

Why should I create sane error messaging?

To help maintain developer sanity

Hunting bugs is hard, and scanning logs is tedious. Sometimes we're provided with context about why things failed, and other times we aren't. If an end-user reports a bug it's important they can present to us as much useful information as possible.

A report from a user that says:

Hi, I was using the app sometime last night updating my profile and all of a sudden it stopped working. The error said something about a validation error, but I don't know what that means

is much less useful than:

Hi, I was using the app sometime last night updating my profile and all of a sudden it stopped working. The error said "We had trouble updating your details. Your address must be located within the EU" but I live in England

This saves us time and cuts down on red herrings. A clear and specific error message may also help an end-user understand what they themselves have done wrong, and can allow them to fix their mistake.

To help maintain organisation sanity

Sane error messages also yield benefits on an organisation level. For those working in larger companies, copy/messaging may be the responsibility of an entirely separate department. The more places in the code that require copy changes, the easier it is for the copy to get out of sync with your company's brand guidelines.

Conversely, keeping all of your error messages in a single source makes it much easier for those owning copy to adhere to those brand guidelines.

Other departments, like the support team, may be inundated with support tickets from users. If you're an engineer, why not reach out to your support team to see how many support tickets could be avoided with improved error messaging.

Fixing the problems with your messaging when a user incorrectly fills out a form, has missing data, or doesn't have permissions for a specific action could positively impact the lives of the support team.

To help maintain end-user sanity

By providing sane error messaging we hope to not leave our end users feeling helpless.

As described earlier, our messaging should be service-oriented. They should guide our user on how to complete their process, or at least let them know where they can go and get help if the problem is beyond their control.

In Jon Yablonski's book, the Laws of UX, he describes a psychological concept called the Peak-end Rule:

People judge an experience largely based on how they felt at its peak and at its end rather than the total sum or average of every moment of the experience

In the context of this article, if people become so frustrated that they rage quit your site, their lasting memory of your application is of how frustrating it is to use.

Error messages play a large part in preventing this, as they can act as the final gatekeeper preventing a user who is simply stuck from turning to one so frustrated they quit your app.

If someone is using your product for a transactional purpose like buying an airplane ticket or shopping online, and they've been stopped dead in their tracks during a task with no way to continue, the likelihood of them leaving your site for another skyrockets. Another lost customer.

While this is wholly anecdotal, I've rage quit sites often from not knowing how to complete a process – either nothing happened when I clicked a button, or I just kept getting vague error messages.

Unless these sites/apps are one of those few ubiquitous platforms (like Google, Instagram, Apple), I likely haven't have used them since. I'm sure you can even remember a time this happened to you. In fact, I'll openly welcome pictures of awful error messages via Twitter

Using sane error messaging can help offset this frustration if something doesn't go right. Surprisingly, creating a useful error message only requires a handful of qualities.

What makes a good error message?

Taken from Microcopy: A complete guide. A useful error message should satisfy these qualities:

  • Explain clearly that there is a problem
  • Explain what the problem is
  • If possible, provide a solution so that the user can complete the process, or
  • Point them to where they can go for help
  • Make a frustrating scenario as pleasant as possible

This might sound like a lot to cover with just a couple of sentences, but here are some examples of what I deem to be good error messages:

  • We've limited how many times you can reset your password every hour. You can try again later.
  • Please log in to view this profile
  • We couldn't create your profile, only UK residents can use our app.

It's worth noting that I'm not a UX researcher/designer, just a frontend developer with a keen interest in UX. It may be that my above examples miss the mark on what's required within your project or organisation.

Saying that, if you're a frontend engineer, improving your organisation's error messaging makes for an excellent opportunity to upskill and collaborate with your UXer colleagues.

How can I start writing sane error messages?

I've open-sourced a simple tool called sane-error-messages. Running the tool will generate a brand new repo designed to house your default error messaging. You can tweak the default values, add or remove messages, and then publish it to consume within your client facing apps.

sane-error-messages works by aggregating all of your messaging in to a single JavaScript object. The key is an error code, and the value is a corresponding message.

The error codes should be the same codes you receive from your server, such as POSTS_NOT_FOUND or CONFLICTING_USER_RECORD. Your error messaging repo exposes a function to get your error message from an error code.

This approach was inspired by how tools like Cypress handle their error messaging.

As long as your server returns predictable error codes, the server-side implementation doesn't matter. The following sequence is just one way of implementing sane-error-messages

A sequence diagram showing the process of displaying a sane error message. Having a separate repo becomes more important the more user-facing apps you have.

In short:

  • The user "views all products"
  • The frontend makes a network request
  • The network request fails and returns an error code "USER_NOT FOUND"
  • The frontend requests the corresponding error message from your error-messages package.
  • The frontend applies any relevant contextual information
  • The frontend displays this information to the end user.

If you want to try something hands on, you can play with this CodeSandbox. The CodeSandbox fires off a request to a mock server which returns 1 of 12 error codes at random.

The client side will use the error code to retrieve a sane error message from the error messages repo. The client side then displays the error message to the user. If the code doesn't have a specified message, the generic fallback gets shown (and it sucks).

A gif of relevant error messages displaying on a code sandbox Some sane error messages in the wild

How to set up your error messages

Note: You can find the repo here. If you come across any problems during the tutorial process you can file a GitHub issue.

Begin by running

yarn global add sane-error-message

then

sane-error-messages create <dirName>

to scaffold your project. Doing so will create a brand new module for you to customise with your default error messages.

Your new module uses tsdx under-the-hood to handle all of the module management scripts, such as running, building, and testing.

You can learn more about tsdx here.

In short, the contents of your new package will look like this:

/* errorCodes.ts: The file that defines each error code like */
const USER_NOT_ADMIN = '403_USER_NOT_ADMIN'

/* defaultErrorMessages.ts: Maps each code to a default message */
const errorCodes {
  // your codes and messages go here...
  [USER_NOT_ADMIN]: "We're afraid only administrators have access to "
}

/* ErrorMessages.ts: The class you'll use to instantiate your error messages object in the consuming project */
class ErrorMessages {
  // You can override default messages with more specific ones
  constructor: (customErrorMessages: Partial<Record<string | number, string>>): ErrorMessages;

  // Pass through an error code to get your custom message
  getErrorMessage: (code: string | number, fallbackMessage?: string): string;

  // Checks to see if the argument is a valid error code and acts as a guard for non-ErrorCode values
  isErrorCode(code: string | number): boolean;

  // Returns the errorCodes object with your custom messages
  messages: Record<ErrorCode, string>
}

type ErrorCode = ValueOf<errorCodes>

How to consume your error messages

If you created a repo with the name custom-error-messages and published it to npm, you'd be able to consume it within your apps by doing the following:

import { ErrorMessages } from 'custom-error-messages';

const customErrorMessages = {
  '400_validation': 'Please enter the fields in your form correctly',
};

// Initialise your errorMessages object with your custom messages
const errorMessages = new ErrorMessages(customErrorMessages);

function riskyFunction() {
  try {
    // Throws an error 
    await boom();
  } catch (err) {
    // Get the error code our server sent over
    const { code } = err;

    // Get the code's corresponding message
    const message = errorMessages.getErrorMessage(code);

    // Display the message to the client
    displayNotification(message);
  }
}

You can then take all of the error codes that your server-side returns and apply corresponding messages to them.

Once you're ready, you can publish your tool to NPM, and then consume it from your client-facing apps.

Conclusion

I hope you've enjoyed learning about an often overlooked aspect of web development.

I've done a bunch of reading to learn about error messaging and I've shared some of my favourite resources below. Some are books and others are short articles, but they're all worth your time.

You can also reach out if any part of the tutorial wasn't clear, or if you feel I can streamline things. Thanks for reading.

FAQs

Why can't the server-side just return these messages?

The server shouldn't be concerned with any client-facing logic. But if you're fortunate enough to work with an API that gives useful error codes with each failed request, then you're nearly there.

Will I need to create an instance of error-messages for every API consumer?

Not necessarily. Because this package can take a list of default messages and codes, as long as it's in sync with the APIs, your frontends will be able to consume the same package.

In each client-side instance, you can pass through additional error codes, or override existing messages to tailor your frontend messaging.

I think this package should have X or do Y differently

I'm dogfooding this internally at my job, and this is a problem space I'm very new to. I would love to hear of any suggestions, or improvements to the overall architecture or feature-set of sane-error-messages.

Further Reading

Microcopy: A Complete Guide
I mentioned this book a little earlier, and it's one of my favourites when it comes to making my user-facing products a lot more personable.

The book's author Kinneret Yifrah, has graciously provided a coupon for 10% off, you can purchase it here.

Coupon code for the eBook: andrico-ebook

Coupon code for the bundle: andrico-bundle

Error messaging guidelines: NN Group
A short article on the importance of sane error messaging which shares some very useful tips on how to create sane error messaging.

In short:

  • Errors should be expressed in plain language
  • Indicate what the problem is
  • Suggest a solution

Error Messages (Design basics): Microsoft
An in-depth article that covers both design guidelines messaging practices

Laws of UX
A short book that introduces how a handful of psychology concepts can be used to improve your products UX.

]]> <![CDATA[ beautiful-skill-tree is officially v1! ? ]]> https://www.freecodecamp.org/news/beautiful-skill-tree-is-officially-v1/ 66bb8df5d2bda3e4315491bb Wed, 13 Nov 2019 15:07:07 +0000 Visualise a satisfying feeling of progression in your app with the help of beautiful-skill-tree.

What is beautiful-skill-tree? ?

beautiful-skill-tree came about as as result of my love for video games, web development and fitness. BST was never intended to be a standalone package, but a feature in a fitness progress app. After discovering that there were no easy-to-use libraries that empower developers to create their own versatile skill trees, BST ended up manifesting as exactly that.

My key motivation for beautiful-skill-tree is to create a package that can be used across a series of browsers and devices, with interactions that feel intuitive, sleek, and gratifying.

While developer experience was a major consideration when creating BST, I wanted usability to be BST's key measurement for success. Thanks to tools like Browserstack, BST has been tested and validated across a series of operating systems, browsers and devices. And thanks to my friends, family (incl. my grandmother), coworkers, and strangers in ensuring that it has been tested across a diverse range of people.

What can I do with beautiful-skill-tree? ?

Currently, the most comprehensive use of beautiful-skill-tree in the wild is Calisthenics Skills.

Image

Setting up BST in your own application is straightforward, with the official README guiding you through the key features in great detail.

Once you've imported the components and configured the SkillTree, all that's left is to supply your own data. For those, like myself, who are TypeScript nerds, BST exports types to ensure that your data adheres to the structure required. If usability is my bottom-line measure for success, developer experience places a close second.

Here's what beautiful-skill-tree offers you:

  • ? A way to visualise user progression in your application
  • ?️ Responsive, cross-browser compatible trees
  • ?️ Silky smooth animations
  • ⌨️ Keyboard navigable trees
  • ? Collapsible trees
  • ? Custom theming
  • ? Saving to localstorage out-of-the-box
  • ✍? Option to implement custom saving
  • ❓ Optional nodes
  • ? Access to your tree's data and methods

What can I expect beyond v1? ?

  • Custom pre-requisites to to unlock/select skills
  • Searching/Filtering through trees and skills
  • Features as a result of insight received from feedback

In the future, I'll talk about some of the challenges I've come across during the creation and development of BST, and the User Experience lessons I've learnt along the way. Stay tuned!

And a big thanks to everyone that has used beautiful-skill-tree in the past!

Have you used beautiful-skill-tree in your own project? You can leave anonymous feedback and feature suggestions here. You can try it out here

If you're interested in keeping up-to-date with any of my projects you can find me in the following places:

]]> <![CDATA[ How to create a Borderlands-style skill tree in 5 minutes ]]> https://www.freecodecamp.org/news/create-a-borderlands-style-skill-tree-in-5-minutes/ 66bb8df85d242388375d3872 Tue, 01 Oct 2019 14:00:00 +0000 Growing up, I spent my spare time doing what most programmers did: played video games every waking moment. I loved Adventure games and what a time sink they were. If time was the Mary Rose, and I was the French, my artillery were games like Kingdom Hearts, Ōkami, and Borderlands.

Why did I, and others, spend so much of our spare time exploring, surviving, dying, and (so, so much) grinding? Hundreds of factors contribute toward making an engaging experience, but the one I’m going to focus on is the notion of progression.

The idea of gamification isn’t new. Many popular applications (like todoist, or challenge timer) have incorporated some sort of progression scheme to make us, the consumers, use their app, give them money, and hand over our personal data. So I decided to go about my way of enabling others to do just that, through beautiful skill trees! Note: I expect neither money nor data from those using my skill trees.

The last few weeks have seen me toil away to create what I hope to be a pleasant plug’n’play React package to help you create exciting skill trees. You can test it yourself by following the tutorial. I hope it will be a frictionless experience.

We hope to have something resembling the skill tree below:

Image “A dying puppy. A baby in tears. If the previous statements elicited any emotional reaction report to your supervisor for summary destruction.”

beautiful-skill-tree@0.7.5

Grab the starter repo by using git clone git@github.com:andrico1234/borderlands-skill-tree.git

Move into the directory and run the starting script, yarn start. Give the site a whirl, you'll see nothing but the Borderlands logo and environment.

beautiful-skill-tree exposes three components: the SkillProvider, SkillTreeGroup, and the SkillTree components.

SkillProvider: This takes in no props and supplies the children with the skill tree's context. This puppy handles all of the global data related to the skill tree.

SkillTreeGroup: Is more involved in that it can take an optional theme property, where we can pass in some custom styling, to make our skill tree feel very Borderlands. The SkillTreeGroup also uses the children-as-a-function pattern to give us access to some imperative api functionality, such as skill tree reset, selected skills counter, etc. We don't need to worry about any of those for the scope of this article.

SkillTree: This is the most exciting of the package's exports, unless you're a sucker for typings (which are also exported, for all you TS fans). The SkillTree doesn't take any children but requires 3 props: treeId, title, and data. The treeId should be an id that's unique to each skill tree, but should be persistent across user sessions as this is used as the key for getting and setting the data to local storage. I'm not going to explain what the title prop does, I'll leave you to experiment. The data is the mixing pot of the application. You'll pass in your skill tree data structure which the app will use to render a beautiful-skill-tree. Let's get a real basic tree going before we move on to our multi-tree, multi-branch Borderlands spectacular.

In App.tsx, import the 3 components like so:

import { SkillProvider, SkillTreeGroup, SkillTree } from 'beautiful-skill-tree';

Place it underneath your img tag, outside of the image's container div, but within the outer div. Add the SkillProvider, passing the SkillTreeGroup as a child. Before you do the same with the SkillTree, remember that as SkillTreeGroup uses function-as-a-child pattern, you'll need to render a function that returns the child components. Return a single SkillTree and give it a treeId and a title prop. Pass an empty array into the data prop so your App.tsx looks like this:

function App() {
  return (
    <div>
    // <div headercontent />
      <SkillProvider>
        <SkillTreeGroup>
          {() => {
            return (
              <SkillTree treeId="basic-birch" title="First Skill Tree" data={[]} />
            )
          }}
        </SkillTreeGroup>
      </SkillProvider>
    </div>
  );
}

Go to localhost:3000 to see the application running. You should see the logo, background, and a grey rectangle. If you’re running into any errors, go through the introduction again and check to see if there any syntax error or incorrect imports.

Next, let’s create a real basic tree. Just 3 items that move in a linear line. The data structure for data looks like this:

type Skill = {
  id: string;
  icon?: string;
  title: string;
  tooltip: {
    description : string;
  },
  children: Skill[];
}

Each skill requires four properties, with one being optional. You should also notice that the children property is a recursive type, meaning that it takes an array of the same data structure, which it uses to render the children of the skill. This can go on infinitely, and make for some real complicated, winding trees. I'll create the first skill for you, and I'll trust you with carrying on for the next two items.

const data = [{
  id: 'first-skill',
  title: 'The root node',
  tooltip: {
    description : "The parent node, all of the descendants will be locked until it's selected",
  },
  children: [
  // rinse and repeat; always repeat.
]}

Add the above snippet to the App.tsx file, and replace the empty array inside of the SkillTree's data property with our data definition. Load your page, and you should have an interactive node. Give it a hover and a click and it should be reacting to your actions. If things are working, then I'll task you with creating two (or more) child nodes. Experiment with children and sibling lengths, to see what you can come up with. (If you also happen to break my precious package, leave me a GitHub issue so I can patch things up).

Once you’re comfortable with creating a skill tree, let’s go ahead and create our Borderlands skill tree. Fortunately, I’ve done all of the tedious work for you and have already created the data structures and accumulated the images.

You’ll need to import the three trees from the data file, which can be done via

import { motion, harmony, cataclysm } from "./data/data";

The next step is creating two additional SkillTrees alongside the current one. You'll need to wrap them in a React.Fragment as your SkillTreeGroup will now be trying to render 3 top level components. Pass in the data accordingly, and if you're unsure, I've posted the code snippet below.

<React.Fragment>
  <SkillTree treeId="motion" title="Motion" data={motion} />
  <SkillTree treeId="harmony" title="Harmony" data={harmony} />
  <SkillTree treeId="cataclysm" title="Cataclysm" data={cataclysm} />
</React.Fragment>

Go ahead and check your web browser, it should be aaallmoost ready. We’ve got the skills rendered, but the styling feels a little lackluster. It doesn’t feel very Borderlands. Fortunately for you, I’m a regular Neil Buchanan and prepared a custom theme. Import the theme and pass it through to the SkillTreeGroup's theme prop. The theme object is export via import theme from './data/theme';. Easy!

Image “I HAVE ONE QUESTION FOR YOU. EXPLOSIONS?”

Once you’ve done the above, check out the finished product. If you’re still not satisfied with the styles, check out the theme object and customise it yourself, there are a bunch of additional attributes whose styles can be adjusted, so just peek into the typings of the package.

I mentioned earlier that there are a few additional properties and values that can be used to tweak the skill tree, so have a mess around yourself, and link me to any cool trees you create. I’d love to add it to the growing list of trees found here. Here’s an example of the skill tree that kickstarted this obsession.

I hope you’ve enjoyed tinkering with the beautiful-skill-tree package. I'm always adding new features and updating, so give it a star on github! You can find an online demo of the borderlands skill tree here

You can find me on Instagram or GitHub if you want to chat code, music, or fitness!

]]> <![CDATA[ My favorite way to keep programming when I’m traveling or don’t have internet ]]> https://www.freecodecamp.org/news/my-favorite-way-to-keep-programming-when-im-traveling-or-don-t-have-internet-d1c2d26618b7/ 66bb8dfe5d242388375d3874 Wed, 14 Nov 2018 17:32:46 +0000 This is a short guide on sharpening your skills and keeping productive when in transit. And it doesn’t involve burying your face in a book.

Books can only get you so far

Now don’t get me wrong, I love a good programming book. Jon Duckett’s series on HTML, CSS, and JavaScript were the guiding beacons during my formative years as a Web Developer. Robert C Martin’s seminal tome Clean Code has its pages bent. It is misshapen through years of being wrung dry for each drop of information. Even Simon Holmes’ Getting MEAN, while now dated, had its time by my side in the local café. It was my companion as I created my first full-stack application.

With a little preparation, most of these books could’ve been used with no, or much more frighteningly, slow internet. Download the packages in advance. Get your local environments working. If the book’s comprehensive enough, you’ll likely make solid progress without needing Google, GitHub or StackOverflow.

On the flip-side, we as programmers thrive best when tasked with a challenge. Having an author walk us through solutions is nice, but it’s not enough. The best way for us to improve our problem-solving skills is to solve problems.

If you’re a professional programmer then you’re likely to be solving your fair share of problems on a day-to-day basis. If you’re a hobbyist then you might find pleasure from creating your own JSF**k applications. Or even killing time by solving algorithm challenges online. It’s why sites like CodeWars or HackerRank are so popular.

The underlying problem with most of these, particularly the latter, is continuing when the internet breaks. Or without connection to begin with. Both are common scenarios as developers are becoming more nomadic. How do you kill time during your 12-hour flight from London to Shanghai, while still reaping the rewards gained from solving problems?

I have had the displeasure of being on such a long flight. There’s about enough space on said flight to prop your laptop on the foldout tray. Everything beyond that becomes a game of Tetris, trying to make your comfort and possessions fit in the limited space given to you on your budget flight. So you’ve got your laptop, headphones, jumper, snacks, and water all within arms reach? It’s starting to feel cramped, right? Try pulling out your 600 page 2-kilo programming book. Yeah, not gonna happen.

The silver bullet

So how did I overcome this impediment? Well, I reimplemented the Lodash library.

Why did I choose a such an arbitrary task? There are many key reasons. Some I rationalized before taking on the challenge and others I discovered along the way. Here are some of the most notable:

  • Each function feels like a miniature code challenge
  • The documentation is on a single HTML page, easy to download and view offline
  • It encourages looking inside the source code when stuck
  • It allows you to build your own suite of utility functions
  • It’s a library with no dependencies, which keeps things simple
  • You will get more familiar with your programming language of choice

Let’s dive a bit more into each of these points.

Each function feels like a code challenge

As I mentioned earlier on, Codewars and HackerRack are two very popular programming challenge sites. For those unfamiliar, you’re given a programming task to complete within the built-in text-editor. When completed, you run your finished code against the curated suite of tests. The aim of the challenge is to get all tests passing.

It’s not difficult emulating this yourself. If anything, it’s a great way of improving your approach to TDD (test driven development). My general approach to reimplementing a function would be to stub out the method:

const concat = (arr, ...otherParams) => {
  // if array is invalid throw error

  // handle no input for second parameter

  // add each item to a new array
    // flatten 1 level if item is array

  // return new array
};

const concat = (arr, ...otherParams) => { // if array is invalid throw error // handle no input for second parameter // add each item to a new array // flatten 1 level if item is array // return new array};

The next step is to create my test suite with some assertions I’d expect my function to satisfy:

const concat = require('../concat');

describe('concat', () => {
  it('should return the expect results with valid inputs', () => {
    expect(concat([1, 2], [1], [2], 4939, 'DDD')).toEqual([1, 2, 1, 2, 4939, 'DDD']);
    expect(concat([], null, 123)).toEqual([null, 123]);
  });

  it('should throw errors with invalid inputs', () => {
    expect(() => concat(23, 23).toThrow(TypeError));
    expect(() => concat([1, 2, 3], -1).toThrow(TypeError));
  });

  it('should correctly handle strange inputs', () => {
    expect(concat([111], null, 'rum ham')).toEqual([111, null, 'rum ham']);
  });
});

Then I’d implement the code so the tests run successfully:

const { isValidArray } = require('../helpers');

const concat = (arr, ...otherParams) => {
  if (!isValidArray(arr)) throw new Error('Argument is not a valid array');

  if (otherParams.length === 0) return [];

  const concatenatedArray = otherParams.reduce((acc, item) => {
    if (isValidArray(item)) return [...acc, ...item];

    return [...acc, item];
  }, [...arr]);

  return concatenatedArray
};

Knocking out one of these functions will leave you with a sense pride and accomplishment.

Simple HTML documentation

Most libraries have a GitHub page with an API reference. These are usually a single page of Markdown that’s available for download. Take a snippet from the Recompose library:

branch()

branch(
  test: (props: Object) => boolean,
  left: HigherOrderComponent,
  right: ?HigherOrderComponent
): HigherOrderComponent

Accepts a test function and two higher-order components. The test function is passed the props from the owner. If it returns true, the left higher-order component is applied to BaseComponent; otherwise, the right higher-order component is applied. If the right is not supplied, it will by default render the wrapped component.

There’s plenty of information here to get you on your way. If you’re learning React and want to get your head around HOCs (higher order components), then implementing this library might be a gratifying challenge to take on.

Reviewing the source code

Up until recently, I wouldn’t take much time to see how the packages I use most frequently work under the hood. Being without Google or StackOverflow made me desperate and so I started to look inside. I don’t know what I expected to see, but it wasn’t a minified, garbled mess.

Opening Pandora’s box didn’t send a swarm of scorn, hate and famine to taunt me and my family. Instead I was welcomed with cleanly written and well-documented code.

You can even take a peek to see how the people at Lodash write their solutions differently to yours:


function concat() {
  var length = arguments.length;
  if (!length) {
    return [];
  }
  var args = Array(length - 1),
      array = arguments[0],
      index = length;

  while (index--) {
    args[index - 1] = arguments[index];
  }
  return arrayPush(isArray(array) ? copyArray(array) : [array], baseFlatten(args, 1));
}

You’ll learn new ways of achieving the same goals. Maybe their solutions are more efficient, maybe yours are. It’s still a great way to open your eyes to new paradigms and patterns.

Developing your own utility functions

Lodash gets a bad rep as a library that has a large footprint. Projects may need a small number of the utilities. We will still import the whole library as a dependency.

You could download the couple of functions that you use. Why not use the methods you spent 8 hours writing whilst flying over the Pacific Ocean? It might not be quite as robust. But you’ll always be reminded of your journey to Angular Fest Hawaii ’19 whenever you whip out your implementation of _.memoize.

Keep things simple

Traveling’s draining and flying’s stressful. When feeling fatigued, any level of bureaucracy that sits in the way of any programming becomes a barrier. The idea is to choose a task that gets you coding with as little friction as possible.

I didn’t want to faff around with a bunch of random dependencies and messy vendor code when packed between two snorers on my overnight flight to Canada. It was a happy accident discovering that Lodash doesn’t rely on any external modules. The Lodash package itself is laid out simply. Each method has its own file, which may import a couple of base or utility methods.

Becoming familiar with your tools of choice

If you’re reading this article, chances are you’re familiar with JavaScript. Like most other modern programming languages, JavaScript receives semi-regular updates. These updates give you access to some new features. Implementing a library might take you to corners of your chosen language that you’ve never been before. It happened to me.

In fact, I recently came across some of JavaScript’s newer built-in objects. I’d never used them in code before, so I made a conscious effort to integrate some of them into the utility methods I made:

const difference = (arr, ...otherArgs) => {
  if (!isValidArray(arr)) throw new TypeError('First argument must be an array');

  const combinedArguments = otherArgs.reduce((acc, item) => [...acc, ...item], [])
  if (!isValidArray(combinedArguments)) throw new TypeError('2nd to nth arguments must be arrays');

  const differenceSet = new Set([...arr]);
  combinedArguments.forEach(item => {
    if (differenceSet.has(item)) differenceSet.delete(item);
  });

  return [...differenceSet]
}

Using Set() makes a lot of sense here. What separates it from a normal array is that only unique values can be stored. This means you can’t have any duplicate values inside of your set. This works well when trying to create a function that removes duplicate values.

Whether you’re a guitarist, a painter, or a molecular physicist, you’re not going to get far without familiarizing yourself with your guitar, or your paints, or your … molecules?

The same goes with being a programmer. Master your tools and actively seek gaps in your knowledge. Make a conscious effort to implement features that you haven’t come across before. Or use ones that you find intimidating. It’s one of the strongest ways to learn.

Conclusion

This isn’t the only way to stay productive when without internet, but it’s worked well for me. In fact, it’s something I recommend people do in the early stages of their programming careers.

I’d love to know if you’ve done something similar, or if you have your own ways of staying sharp without the internet. Let me know below!

Do you know any other packages that would lend themselves well to being rewritten?

Thanks for reading!

Knowledge sharing is one of the cornerstones of what makes the development community so great. Please don’t hesitate to comment your solutions.

If you’re interested in hosting me at a conference, meetup, or as a speaking guest for any engagement, then you can DM me on twitter!

I hope this article taught you something new. I post regularly, so if you want to keep up to date with my latest releases then you can follow me. And remember, the longer you hold the clap button, the more claps you can give. ???

Add a touch of Suspense to your web app with React.lazy()

How to use Apollo’s brand new Query components to manage local state

No need to wait for the holidays, start Decorating now

Managing local state with Apollo and Higher Order Components

The React Conference drinking game

Develop and Deploy your own React monorepo app in under 2 hours, using Lerna, Travis and Now

]]> <![CDATA[ How to use Apollo’s brand new Query components to manage local state ]]> https://www.freecodecamp.org/news/updated-for-apollo-v2-1-managing-local-state-with-apollo-d1882f2fbb7/ 66bb8e01bec1b237336e9683 Mon, 04 Jun 2018 07:52:49 +0000 Note: This article deals with utilizing Apollo’s brand new Query and Mutation components, instead of the HOCs. For those that have read the original article here, be aware that the two articles are very similar.

Introduction

One of Web Development’s biggest strengths — and weaknesses — is its approach to modularity. A key programming mantra is to choose something (a function, a package) to do a single job and to do it well. The downside to this approach is that a single project can involve juggling dozens of separate technologies and concepts, each focusing on something specific.

So choosing Apollo Client to handle my local state as well as my remote data seems like a no brainer. Why deal with Redux’s boilerplate and idioms when I’ve already got Apollo/GraphQL set up to get data from my backend?

While this article is going to deal with setting up Apollo to handle local state, it’s not going to be an introduction to the tech. (This legit howtographql tutorial is a good start for that).

Note: The finished repo can be found here. You can pore through the code if you get stuck or feel confused.

Getting set up

We’ll start by cloning the corresponding repo from here. This repo contains a simple react website, with a sidebar, header, and a body. It’s pretty static in nature, no dynamic content (…yet). By the end of this tutorial, we’ll have Apollo managing the state of the website. Clicking an item in the sidebar will change the state of the website, which in turn updates the header to display the new data.

If you check package.json you’ll see that we’ve only got the basics, plus some additional packages pertaining to our parcel setup.

After cloning the repo, run your standard commands in your command line interface.

> yarn
> yarn dev

To install all of your packages and to whip up a local server, go to localhost:1234 and you’ll hopefully see the demo website in all of its glory. It’s static right now, so clicking around won’t do a thing.

What we want to do first and foremost is to get Apollo in our project, so install these packages. apollo-client lets us configure our instance of Apollo, and react-apollo is the driver that allows us to integrate it into our React application. Due to an issue with parcel (I think) we’ll also need to install graphql.

> yarn add apollo-client react-apollo graphql

Create a new directory src/apollo, crack open an index.js file, and add the following:

import ApolloClient from ‘apollo-client’;
export const client = new ApolloClient({});

This initializes our Apollo Client, which we will then use to wrap our React application by adding the following inside of our src/index.js file.

import { ApolloProvider } from ‘react-apollo’;
import { client } from ‘./apollo’;

const WrappedApp = (
  <ApolloProvider client={client} >
    <App />
  </ApolloProvider>
);

ReactDOM.render(WrappedApp, document.getElementById(‘root’));
// Don’t be a sap. Wrap your app.

We now have Apollo ready to use in our app. Everything builds when we restart our dev server, but we get an error when we try and access it in the browser. The console will tell us that we need to specify the link and cache properties for our Apollo client, so let’s do that.

> yarn add apollo-link apollo-cache-inmemory apollo-link-state

The previous line adds the new Apollo dependencies to our application while the following code resolves the console errors we were getting. So go back to apollo/index.js and update it so the file looks like this:

import ApolloClient from ‘apollo-client’;
import { InMemoryCache } from ‘apollo-cache-inmemory’;
import { ApolloLink } from ‘apollo-link’;
import { withClientState } from ‘apollo-link-state’;

const cache = new InMemoryCache();
const stateLink = withClientState({
  cache
});

export const client = new ApolloClient({
  cache,
  link: ApolloLink.from([
    stateLink,
  ]),
})

Let’s create an instance of our cache. The cache is Apollo’s normalized data store that stores the results of the query in a flattened data structure. We will read from the cache when we make our GraphQL query, and we’ll write to the cache when we make our mutation resolver.

You can see we’ve also added link to our client object. The ApolloLink.from()method lets us modularly configure how our queries are sent over HTTP. We can use this to handle errors and authorization, and to provide access to our backend. We’re not going to be doing any of this in the tutorial, but we will set up our client state here. So we create const stateLink above and pass in our cache. We’ll add our default state and resolvers here later.

Going back to the browser, you’ll see our lovely static site displaying in all of its magnificence. Let’s add some default state to our project and fire off our first query.

Inside of the Apollo directory, create a new directory called defaults and add an index.js inside of it. The file will contain the following:

export default {
  apolloClientDemo: {
    __typename: ‘ApolloClientDemo’,
    currentPageName: ‘Apollo Demo’,
  }
}

We create an object which acts as the default state of our site. apolloClientDemo is the name of the data structure we want to access when we make our queries. The __typename is the mandatory identifier that our cache uses, and the currentPageName is the specific item of data that our header will use to — you guessed it — display the current page name.

We’ll need to add this to our apollo/index.js file:

import defaults from ‘./defaults’;

const stateLink = withClientState({
  cache,
  defaults,
});

Let’s clear this up a little bit. import and default are both keywords associated with importing modules, but coincidentally the name of the object we’re exporting from ./defaults is also called defaults (so don’t be thinking that I’m using import/export wrong). Treat this import line as if it was just any regular ol’ named import.

With that out of the way, let’s go make a query!

How to make a query

Add the following package to your project:

> yarn add graphql-tag

and create a new directory src/graphql. In there, create two new files: index.js and getPageName.js. The GraphQL directory will house all the queries and mutations. We’ll create our query in getPageName.js by writing the following:

import gql from ‘graphql-tag’;

export const getPageNameQuery = gql`
  query {
    apolloClientDemo @client {
      currentPageName
    }
  }
`;

export const getPageNameOptions = ({
  props: ({ data: { apolloClientDemo } }) => ({
    apolloClientDemo
  })
});

So we’re exporting two variables, the query and the options. If you’ve used GraphQL before, then the query will look familiar. We’re querying against the apolloClientDemo data structure, retrieving back nothing more than the currentPageName. You’ll notice that we’ve added the @client directive to our query. This tells Apollo to query our local state instead of sending the request to the backend.

Below you’ll see that we’re exporting some options. This is simply defining how we want the data to look when we map the results to the props. We’re destructuring the GraphQL response and sending it to our view so it looks like this:

props: {
  currentPageName: ‘Apollo Demo’,
}
// and not this
props: {
  data: {
    apolloClientDemo: {
      currentPageName: ‘Apollo Demo’,
    }
  }
}

Go to the graphql/index.js file and export the query as follows:

export { getPageNameQuery, getPageNameOptions } from ‘./getPageName’;

Again, while this isn’t completely necessary for a small demo/project, this file is handy should your application grow larger. Having your queries exported from a single centralized location keeps everything organized and scalable.

Add to your Header.js:

import React from 'react';
import { Query } from 'react-apollo';
import { getPageNameQuery } from '../graphql';

const Header = () => (
    <Query query={getPageNameQuery}>
        {({ loading, error, data }) => {
            if (error) return <h1>Error...</h1>;
            if (loading || !data) return <h1>Loading...</h1>;

            return <h1>{data.apolloClientDemo.currentPageName}</h1>
        }}
    </Query>
);

export default Header;

This is our first use of Apollo’s new Query Component, which was added in 2.1. We import Query from react-apollo and use it to wrap the rest of our component. We then pass the getPageNameQuery as a value in the query prop. When our component renders, it fires off the query and gives the rest of the component access to the data, which we destructure to gain access to loading, errors, and data.

The Query Component uses the render props pattern to give the rest of our component access to the information returned from the query. If you’ve used the React Context API in 16.3, then you’ve seen this syntax before. Otherwise it’s worth checking out the official React docs here, as the Render Props pattern is becoming increasingly popular.

In our component, we do a few checks to see if there were any errors when firing the query or if we’re still waiting for data to be returned. If either of these scenarios are true, we return the corresponding HTML. If the query was fired correctly, the component will dynamically display the title of the current page. As we haven’t added our mutation yet, it will only display the default value. But you can change whatever’s in the default state and the website will reflect that.

Now all that’s left to do is mutate the data in the Apollo cache by clicking on the sidebar item.

Image _A refreshing image to break up the text. [Jeff Sheldon](https://unsplash.com/@ugmonk?utm_source=medium&utm_medium=referral" rel="noopener" target="blank" title=")

Mutations

Things get a little more complicated when dealing with mutations. We no longer just retrieve data from the Apollo store, but we update it too. The architecture of mutation is as follows:

> User clicks sidebar item

> Sends variable to mutation

> Fires mutation with variable

> Gets sent to the instance of Apollo

> Finds corresponding resolver

> Applies logic to the Apollo store

> Sends data back to header

If that’s difficult to remember, then use this handy mnemonic created using a mnemonic generator: Urban Senile Fauns Groped Faithless Aslan Solemnly. (easy…)

Start by creating a file graphql/updatePageName.js.

import gql from ‘graphql-tag’;

export const updatePageName = gql`
  mutation updatePageName($name: String!) {
    updatePageName(name: $name) @client {
      currentPageName
    }
  }
`;

and export it just like we did with the query.

export { updatePageNameMutation } from ‘./updatePageName’;

You’ll notice a few differences regarding the mutation. First off we’ve changed the keyword from query to mutation. This lets GraphQL know the type of action we’re performing. We’re also defining the name of the query and adding types to the variables we’re passing in. Inside here we’re specifying the name of the resolver we’ll be using to carry out the changes. We’re also passing through the variable and adding the @client directive.

Unlike the query, we can’t just add the mutation to our view and expect anything to happen. We’ll have to go back to our Apollo directory and add our resolvers. So go ahead and create a new directory apollo/resolvers, and files index.js and updatePageName.js. Inside of updatePageName.jsadd the following:

import gql from ‘graphql-tag’;

export default (_, { name }, { cache }) => {
  const query = gql`
    query GetPageName {
      apolloClientDemo @client {
        currentPageName
      }
    }
  `;

  const previousState = cache.readQuery({ query });

  const data = {
    apolloClientDemo: {
      …previousState.apolloClientDemo,
      currentPageName: name,
    },
  };

  cache.writeQuery({
    query,
    data,
  });

  return null;
};

There are a lot of interesting things going on in this file. Fortunately, it’s all very logical and doesn’t add many new concepts to what we’ve seen before.

So by default, when a resolver gets called, Apollo passes in all of the variables and the cache. The first argument is a simple ‘_’ because we don’t need to use it. The second argument is the variables object, and the final argument is the cache.

Before we can make changes to the Apollo store, we’ll need to retrieve it. So we make a simple request to get the current content from the store and assign it to previousState. Inside of the data variable, we create a new object with the new information we want to add to the store, which we then write to. You can see that we’ve spread the previous state inside of this object. This is so that only the data we explicitly want to change gets updated. Everything else remains as it is. This prevents Apollo from needlessly updating components whose data hasn’t changed.

Note: while this isn’t completely necessary for this example, it’s super useful when queries and mutations handle larger amounts of data, so I’ve kept it in for the sake of scalability.

Meanwhile in the resolvers/index.js file…

import updatePageName from ‘updatePageName’;

export default {
  Mutation: {
    updatePageName,
  }
};

This is the shape of object that Apollo expects when we pass in our resolvers in to stateLink back in apollo/index.js:

import resolvers from ‘./resolvers’;

const stateLink from = withClientState({
  cache,
  defaults,
  resolvers,
});

All that’s left to do is add the mutation to our sidebar component.

// previous imports
import { Mutation } from ‘react-apollo’;
import { updatePageNameMutation } from ‘../graphql’;

class Sidebar extends React.Component {
  render() {
    return (
      <Mutation mutation={updatePageNameMutation}>
        {updatePageName => (
          // outer div elements
          <li className=“sidebar-item” onClick={() => updatePageName({ variables: { name: ‘React’} })}>React</li>
          // other list items and outer div elements
        )}
      </Mutation>
    );
  }
}

export default Sidebar;

Like our resolver file, there’s a lot going on in this file — but it’s new. We import our Mutation component from react-apollo, wrap it around our component, and pass the updatePageNameMutation inside of the mutation prop.

The component now has access to the updatePageName method which fires the mutation whenever it’s called. We do this by adding the method as a handler to the <li>’s onClick property. The method expects to receive on object containing the variables as a parameter, so pass in the name you want to update the header to. If everything works, you should be able to run your dev server and click the sidebar items, which should then change our header.

Wrapping up

Hooray! Hopefully everything worked out. If you got stuck, then check out the repo here. It contains all of the finished code. If you’re thinking of using local state management in your next React app, then you can fork this repo and continue from there. If you’re interested in having this article/topic spoken about at a meetup or conference, then send a message my way!

There’s a lot more I wanted to cover in this tutorial, such as async resolvers (think Redux thunk), type checking/creating a schema, and a mutation update. So who knows… maybe I’ll drop another article sometime soon.

I really hope that this tutorial was useful for you. I’d like to shout out Sara Vieira’s youtube tutorial too, as it helped me get my head around Apollo Client. If I haven’t done my job well enough by leaving you scratching your head, then follow the link. And finally, feel free to hit me up on social media, I’m a big music and tech fan so talk geek to me.

Thanks for reading!

If you’re interested in hosting me at a conference, meetup or as a speaking guest for any engagement then you can DM me on twitter!

How to use Apollo’s brand new Query components to manage local state

[Add a touch of Suspense to your web app with React.lazy()](http://Add a touch of Suspense to your web app with React.lazy())

No need to wait for the holidays, start Decorating now

Managing local state with Apollo and Higher Order Components

The React Conference drinking game

Develop and Deploy your own React monorepo app in under 2 hours, using Lerna, Travis and Now

]]>