DEV Community: Bruno Sabot

Crafting My Perfect Home Assistant Dashboard

Bruno Sabot — Sat, 13 Jul 2024 06:20:00 +0000

Inspired by the beautiful and functional dashboards I've seen online, I embarked on a journey to personalize my own Home Assistant experience. This post dives into the plugins I used, my customization choices, and a final glimpse of the finished product.

Introducing the Plugin Powerhouse

Several plugins played a pivotal role in building my dream dashboard, each offering unique functionalities that elevated the user experience.

I meticulously handpicked a select few from the vast plugin library, prioritizing consistency and cohesiveness around the versatile Bubble Card, to craft this personalized experience.

Bubble Card

I recently stumbled upon the Bubble Card plugin, and let me tell you, it was a game-changer!

This new plugin quickly became the star of my dashboard makeover. Its cool, rounded design elements totally revamped the whole look and feel, making everything smooth and visually appealing.

To take things to the next level, I also started using the Bubble theme, created by the same awesome creator.

Together, they work like magic, creating a consistent and stunning dashboard that's more than just the sum of its parts.

It's like my dashboard went from info central to an interactive and visually engaging masterpiece!

Card Mod

Anyone who's ever tinkered with their dashboard to make it look snazzy probably knows about Card Mod – it's kind of a no-brainer.

This awesome plugin lets you, well, mod your cards by taking styles from other cards. Need to change the background color, for example? Card Mod is your new best friend.

It helps if you know a little CSS, but even without it, you can do some pretty cool stuff and make your dashboard look way less, well, boring.

Decluttering Card

Card Mod is so cool, I went a little overboard and ended up customizing practically everything! But all those tweaks scattered throughout my config started to feel like a bit of a pain to manage.

That's when I discovered the magic of Decluttering Card. This plugin lets me create card templates that I can reuse everywhere, shrinking my configuration file down to a much more manageable size.

Now, I can make a change in one place, and it ripples through my entire dashboard – a total win!

Config Template Card

Decluttering Card definitely helps with the templating issue, but it can't handle everything, especially when things get a little more dynamic.

Thankfully, the Config Template Card swoops in to save the day! This plugin lets you use JavaScript to make pretty much any property of your card dynamic, putting the finishing touches on your template mastery.

It's like the final ingredient in the recipe for perfect dashboard customization.

Lovelace Layout Card

Now I have the power to create the perfect cards, I just needed the final touch: a stellar layout.

Thankfully, Lovelace Layout Card swoops in to save the day! This plugin allows me to craft a perfectly responsive dashboard that flawlessly adapts to both my desktop and mobile, ensuring a seamless Home Assistant experience no matter the device I'm using.

Bringing it to Life: My Customization Journey

In the following sections, I'll delve into the specifics of how I utilized these plugins to realize my desired dashboard functionalities.

I'll provide a detailed explanation for each, empowering you to replicate or adapt these approaches to craft your own personalized Home Assistant experience.

Alarm

Keeping tabs on my home alarm system's status is crucial. To achieve this, I needed a clear and immediate visual indicator right on my dashboard.

The ideal card would dynamically change its background color based on the alarm's state: green for disabled, orange for armed, and red for triggered. Luckily, the style customization of Bubble Card allowed me to create this functionality perfectly.

Now, with just a glance, I can see the alarm's status and take appropriate action if needed.

Here is the decluttering-card template:

default:
  - name: ''
  - columns: 2
card:
  type: custom:bubble-card
  card_type: button
  button_type: state
  entity: '[[entity]]'
  name: '[[name]]'
  show_state: true
  icon: mdi:alarm-light
  columns: '[[columns]]'
  card_layout: large
  styles: |
    .bubble-button-card-container {
      background-color: ${state === 'disarmed' ? 'var(--success-color)' : state === 'triggered' ? 'var(--error-color)' : 'var(--warning-color)'};
    }
    .bubble-icon {
      color: ${state === 'disarmed' ? 'var(--success-color)' : state === 'triggered' ? 'var(--error-color)' : 'var(--warning-color)'} !important;
      opacity: 0.6 !important;
    }

AQI

Monitoring air quality is a top priority for me, as I'm sensitive to pollution.

Having this data readily available on my dashboard helps me maintain my health, not only through automations with my air purifier but also by allowing me to check the current pollution level at a glance.

I envisioned a card that would display the Air Quality Index (AQI) using a color-coded system: green for good air quality (AQI below 50), orange for moderate air quality (AQI below 100), and red for poor air quality (AQI above 100).

This way, I could easily understand the air quality and take appropriate actions, if necessary.

Here is the decluttering-card template:

default:
  - name: ''
card:
  type: 'custom:bubble-card'
  card_type: button
  button_type: state
  entity: '[[entity]]'
  name: '[[name]]'
  icon: mdi:leaf
  show_state: true
  columns: 2
  card_layout: large
  styles: |
    .bubble-button-card-container {
      background-color: ${state < 50 ? 'var(--success-color)' : state < 100 ? 'var(--warning-color)' : 'var(--error-color)'};
    }
    .bubble-icon {
      color: ${state < 50 ? 'var(--success-color)' : state < 100 ? 'var(--warning-color)' : 'var(--error-color)'} !important;
      opacity: 0.6 !important;
    }

Covers

My cover cards demanded a presentation that was both information-rich and visually clear. To achieve this, I implemented a three-pronged approach:

Condensed Icon Spacing & Favorite Position Integration: I tightened the spacing between the cover icons, fostering a sense of cohesion for the linked actions they represent. Additionally, I incorporated a sub-button displaying the favorite position (set at 15% in my case) directly within the card itself.
Seamless Opening Percentage Display: The current opening percentage is crucial information, and I eliminated the need for a separate entity card by integrating it directly into the cover card.
Color-Coded Status Recognition: Finally, I implemented a color-coding system to provide instant status recognition. Blue signifies a fully open cover, while purple highlights the preferred 15% position. This visual language allows for quick comprehension and informed decision-making when interacting with my covers.

This combined approach effectively streamlined the cover card format, enhancing both information accessibility and user experience.

Here is the decluttering-card template:

default:
  - name: ''
card:
  type: 'custom:bubble-card'
  card_type: cover
  entity: '[[entity]]'
  name: '[[name]]'
  icon_open: mdi:window-shutter-open
  icon_close: mdi:window-shutter
  show_state: true
  columns: 2
  card_layout: large
  sub_button:
    - name: My
      icon: mdi:star
      show_background: false
      tap_action:
        action: call-service
        service: button.press
        target:
          entity_id:
            - '[[my]]'
  card_mod:
    style: |
      .bubble-cover-card-container {
        background-color:
          {% if state_attr(config.entity, 'current_position') == 15 %}
            var(--state-cover-active-color)
          {% elif state_attr(config.entity, 'current_position') > 0 %}
            var(--accent-color)
          {% else %}
            var(--background-color-2, var(--secondary-background-color))
          {% endif %}
        !important;
      }
      .large .bubble-buttons {
        gap: 8px;
      }
      .bubble-button {
        background: transparent;
        width: 40px;
        height: 40px;
      }
      .bubble-icon {
        justify-content: center;
        align-items: center;
      }
      .large .bubble-sub-button-container {
        margin-right: 8px;
      }
      .bubble-sub-button {
        background: transparent;
        width: 40px;
        height: 40px;
      }
      .bubble-state::after {
        content: " - {{ state_attr(config.entity, 'current_position') }}%";
        margin-left: 4px;
      }
      .bubble-icon-container {
        border-color: transparent;
        background-color: transparent;
      }
      .bubble-icon-container::after {
        content: "";
        background-color:
          {% if state_attr(config.entity, 'current_position') == 15 %}
            var(--state-cover-active-color)
          {% elif state_attr(config.entity, 'current_position') > 0 %}
            var(--accent-color)
          {% else %}
            var(--background-color-2, var(--secondary-background-color))
          {% endif %}
        !important;
        height: 25px;
        width: 25px;
        position: absolute;
        left: 50px;
        top: 25px;
        -webkit-mask-image: radial-gradient(circle at top right, transparent 0, transparent 25px, black 25.5px);
      }

Separator

To keep my dashboard organized, I grouped things into sections.

Bubble Card's separator mode was perfect for adding section titles, but I wanted to give them a little makeover.

So, I played around with some CSS to make the font lighter and bigger, and tweaked the line color so it stands out even when the cards aren't in a popup.

Now the section titles are easy to read and add a nice touch to the whole thing!

Here is the decluttering-card template:

default:
  - icon: ''
  - name: ''
card:
  type: custom:bubble-card
  card_type: separator
  name: '[[name]]'
  icon: '[[icon]]'
  card_layout: large
  styles: |
    .bubble-name {
      font-weight: 100;
      font-size: 20px;
    }
    .bubble-line {
      background-color: var(--background-color-2, var(--secondary-background-color));
      opacity: 0.2;
    }

Thermostat

Craving more from my smart thermostat display, I used custom-template-card to dynamically change the card's icon based on heating state.

Color cues joined the party: blue for off, green for achieved comfort, and orange for heating to reach temperature. I even incorporated the target temperature in this customized switch card.

Now, it's a one-stop shop for efficient and comfortable climate control!

default:
  - name: ''
  - offset: 1
card:
  type: custom:config-template-card
  variables:
    MODE: "states['[[entity]]'].state"
  entities:
    - "[[entity]]"
  card: 
    type: custom:bubble-card
    card_type: button
    button_type: switch
    entity: '[[entity]]'
    name: '[[name]]'
    icon: "${MODE === 'heat' ? 'mdi:thermometer': 'mdi:thermometer-off'}"
    show_state: true
    columns: 2
    card_layout: large
    card_mod:
      style: |
        .bubble-button-card-container {
          background-color: {% if is_state(config.entity, 'heat') %}{% if state_attr(config.entity, 'temperature') > state_attr(config.entity, 'current_temperature') %}var(--warning-color){% else %}var(--success-color){% endif %}{% else %}var(--info-color){% endif %} !important;
        }
        .bubble-icon {
          color: {% if is_state(config.entity, 'heat') %}{% if state_attr(config.entity, 'temperature') > state_attr(config.entity, 'current_temperature') %}var(--warning-color){% else %}var(--success-color){% endif %}{% else %}var(--info-color){% endif %} !important;
          opacity: 0.6 !important;
        }
        .bubble-state::after {
          content: " - {{ state_attr(config.entity, 'temperature') }} °C";
          margin-left: 4px;
        }

Weather

While Bubble Card forms the foundation, the true magic lies in the customization of my weather display. It leverages the power of sub-buttons to showcase a range of essential information: current conditions, daily highs and lows, wind speed, and the anticipated rain forecast.

But the key is the intuitive color-coding system I implemented:

Temperatures utilize a blue-to-red gradient, providing a quick glimpse of the expected highs and lows.
Wind speed follows a similar approach, transitioning from neutral to red as intensity increases.
Rain takes center stage with a prominent blue highlight whenever there's a chance of precipitation.

This visual language allows me to grasp the daily forecast at a glance, without getting bogged down in numbers. It's a testament to the power of visual communication and user experience design in action!

default:
  - name: ''
card:
  type: custom:bubble-card
  card_type: button
  button_type: state
  entity: '[[entity]]'
  name: '[[name]]'
  show_state: true
  scrolling_effect: false
  card_layout: large-2-rows
  sub_button:
    - name: Min
      icon: mdi:thermometer-low
      entity: '[[entity]]'
      attribute: forecast[0].templow
      show_background: false
      show_attribute: true
    - name: Wind
      icon: mdi:weather-windy
      entity: '[[entity]]'
      attribute: wind_speed
      show_background: false
      show_attribute: true
      show_icon: true
    - name: Max
      icon: mdi:thermometer-high
      entity: '[[entity]]'
      attribute: forecast[0].temperature
      show_background: false
      show_attribute: true
    - name: Rain
      icon: mdi:weather-pouring
      entity: '[[entity]]'
      show_background: false
      show_attribute: true
      attribute: forecast[0].precipitation
      show_icon: true
  card_mod:
    style: |
      .bubble-icon-container {
        background: transparent;
      }
      .bubble-name {
          border-radius: 20px;
          background-color:
          {% if state_attr(config.entity, 'temperature') < 10 %}
            var(--info-color)
          {% elif state_attr(config.entity, 'temperature') > 40 %}
            var(--error-color)
          {% elif state_attr(config.entity, 'temperature') > 30 %}
            var(--warning-color)
          {% endif %}
          ;
          margin-left: -8px;
          padding: 0 8px;
      }
      .bubble-name::after {
          content: " - {{ state_attr(config.sub_button[0].entity, 'temperature')  }}°C";
          margin-left: 4px;
      }
      .bubble-sub-button-1 {
          background-color:
          {% if state_attr(config.sub_button[0].entity, 'forecast')[0].templow < 10 %}
            var(--info-color)
          {% elif state_attr(config.sub_button[0].entity, 'forecast')[0].templow > 40 %}
            var(--error-color)
          {% elif state_attr(config.sub_button[0].entity, 'forecast')[0].templow > 30 %}
            var(--warning-color)
          {% endif %}
          ;
      }
      .bubble-sub-button-1::before {
        content: "°C";
      }
      .bubble-sub-button-2 {
          background-color:
          {% if state_attr(config.sub_button[0].entity, 'wind_speed') > 20 %}
            var(--warning-color)
          {% elif state_attr(config.sub_button[0].entity, 'wind_speed') > 50 %}
            var(--error-color)
          {% endif %}
          ;
      }
      .bubble-sub-button-2::before {
        content: "km/h";
        margin-left: 2px;
      }
      .bubble-sub-button-3 {
          background-color:
          {% if state_attr(config.sub_button[2].entity, 'forecast')[0].temperature < 10 %}
            var(--info-color)
          {% elif state_attr(config.sub_button[2].entity, 'forecast')[0].temperature > 40 %}
            var(--error-color)
          {% elif state_attr(config.sub_button[2].entity, 'forecast')[0].temperature > 30 %}
            var(--warning-color)
          {% endif %}
          ;
      }
      .bubble-sub-button-3::before {
        content: "°C";
      }
      .bubble-sub-button-4 {
          background-color:
          {% if state_attr(config.sub_button[3].entity, 'forecast')[0].precipitation > 0 %}
            var(--info-color)
          {% endif %}
          ;
      }
      .bubble-sub-button-4::before {
        content:" mm";
        margin-left: 2px;
      }

Weather forecast

While the current weather is important, I also crave a sneak peek at the next week's forecast.

To achieve this, I leveraged the same color-coded system from my weather card for a visually cohesive experience. Additionally, I cleverly formatted the current day using its attributes, while also extracting the high and low temperatures from the same source.

This way, I get a clear picture of the upcoming week's weather trends right on my dashboard.

default:
  - name: ''
  - offset: 1
card:
  type: custom:config-template-card
  variables:
    FORECAST: "states['[[entity]]'].attributes.forecast[[[offset]]].condition"
  entities:
    - "[[entity]]"
  card: 
    type: custom:bubble-card
    card_type: button
    button_type: state
    entity: '[[entity]]'
    name: Forecast
    icon: "${FORECAST === 'partlycloudy' ? 'mdi:weather-partly-cloudy': 'mdi:weather-'+FORECAST}"
    columns: 2
    card_layout: large
    show_state: true
    card_mod:
      style:
        .: |
          .bubble-name {
            color: transparent;
            white-space: nowrap;
          }
          .bubble-name:before {
            color: var(--primary-text-color);
            content: "{{ strptime(state_attr(config.entity, 'forecast')[[[offset]]].datetime, '%Y-%m-%dT%H:%M:%S%z').strftime("%A")  }}";
          }
          .bubble-state {
            color: transparent;
            white-space: nowrap;
          }
          .bubble-state:before {
            color: var(--primary-text-color);
            content: "{{ state_attr(config.entity, 'forecast')[[[offset]]].templow }} / {{ state_attr(config.entity, 'forecast')[[[offset]]].temperature }} {{ state_attr(config.entity, 'temperature_unit') }}";
          }
          .bubble-button-card {
            background-color:
            {% if state_attr(config.entity, 'forecast')[[[offset]]].temperature < 10 %}
              var(--info-color)
            {% elif state_attr(config.entity, 'forecast')[[[offset]]].temperature > 40 %}
              var(--error-color)
            {% elif state_attr(config.entity, 'forecast')[[[offset]]].temperature > 30 %}
              var(--warning-color)
            {% endif %}
            !important;
          }
          .bubble-icon {
            color: 
            {% if state_attr(config.entity, 'forecast')[[[offset]]].temperature < 10 %}
              var(--info-color)
            {% elif state_attr(config.entity, 'forecast')[[[offset]]].temperature > 40 %}
              var(--error-color)
            {% elif state_attr(config.entity, 'forecast')[[[offset]]].temperature > 30 %}
              var(--warning-color)
            {% endif %} !important;
            opacity: 0.6 !important;
          }

Is that it?

While I've highlighted some key customizations, there are additional tweaks throughout my dashboard that refine the presentation further. These refinements build upon the techniques described here. If you're curious to delve deeper, feel free to reach out – I'm always happy to chat about Home Assistant!

For a complete picture, here's a quick reference of the custom cards I've utilized:

Alarm Status: bubble_alarm (presented earlier)
Air Quality Index: bubble_aqi (presented earlier)
Cover Cards: bubble_cover (presented earlier)
Section Separators: bubble_separator (presented earlier)
Temperature Display: bubble_temperature
Thermostat Control: bubble_thermostat (presented earlier)
Trash Collection: bubble_trash
Vacuum Status: bubble_vacuum
Weather Display: bubble_weather (presented earlier)
Météo-France Alerts: bubble_weather_alert
Future Forecast: bubble_weather_forcecast
Website Status: bubble_website

Mastering Time: Using Fake Timers with Vitest

Bruno Sabot — Sun, 30 Jun 2024 12:08:59 +0000

Photo by Aron Visuals on Unsplash

In the world of testing, controlling time can be a real challenge. Real-world timers, like setTimeout() and setInterval(), can be cumbersome when writing unit tests: without the right technique, you will introduce external dependencies on actual time passing that will make your test either slower, wrong or difficult to understand.

This is where Vitest’s fake timers come in, giving you the power to manipulate time within your tests for a smoother and more efficient testing experience.

At PlayPlay, we create high-quality software while prioritizing efficient development practices. We leverage innovative tools like Vitest’s fake timers to write faster and more reliable tests, ensuring exceptional software from the ground up.

Why Fake Timers?

Imagine testing a function that debounces another one after a 2-second delay. Using real timers, your test would have to wait for the full 2 seconds to pass, making the whole test scenario longer by these 2 seconds. This is slow and inefficient, and even more when you’re dealing with multiple timers or complex timing interactions. Hopefully, fake timers are here to allow you to:

Speed up tests: Advance the virtual clock by any amount, making tests run significantly faster. This is particularly beneficial for tests that involve waiting for timers to expire or simulating longer time intervals. Vitest prioritizes test speed. Fake timers become even more crucial when dealing with functions that rely on timers. You can avoid waiting for long intervals, keeping your tests lightning fast.
Isolate functionality: By removing reliance on external timers, you ensure your tests focus solely on the code you’re testing. This eliminates external factors that could potentially cause flaky tests and makes it easier to pinpoint the source of any issues.
Simulate specific timeouts: Test how your code behaves under different time constraints. Fake timers allow you to create scenarios with specific delays or timeouts, helping you ensure your code functions as expected in various situations. You can check something’s state just before the timer is executed and right after.

Getting Started with Fake Timers

Vitest provides the vi.useFakeTimers() function to enable fake timers: this mocks out the behavior of setTimeout(), setInterval(), clearTimeout(), and clearInterval().

You can call this method globally, before each test or on-demand. Here is an example:

import { vi, beforeEach } from 'vitest';

beforeEach(() => {
    vi.useFakeTimers();
});

If you chose to do it on demand, you will need to restore the real behavior to ensure subsequent tests don’t inherit the fake timer behavior. Here is an example:

import { vi, afterEach } from 'vitest';

afterEach(() => {
    vi.useRealTimers();
});

Basic Usage

Let’s start with a simple example. Imagine you have a function that uses setTimeout() to execute a callback after a delay:

function getDelayedGreeting(callback) {
    setTimeout(() => {
        callback('Hello, World!');
    }, 1000);
}

To test this function with fake timers, you can write:

import { describe, expect, test, vi, afterEach } from 'vitest';

afterEach(() => {
    vi.useRealTimers();
});

describe('Given the getDelayedGreeting function', () => {
    describe('When we wait 1s', () => {
        test('Then it calls the callback with the right message', () => {
            // Arrange
            vi.useFakeTimers();
            const callback = vi.fn();
            getDelayedGreeting(callback);

            // Act
            vi.advanceTimersByTime(1000);

            // Assert
            expect(callback).toHaveBeenCalledWith('Hello, World!');
        });
    });
});

In this test, vi.advanceTimersByTime(1000) fast-forwards the timer by 1000 milliseconds, causing the setTimeout() to fire immediately. The expect() assertion then checks if the callback was called with the correct argument.

The true power of fake timers lies in their ability to ensure that time advances exactly as expected in your tests.. We can write the non-passing test as easy as the previous one:

import { describe, expect, test, vi, afterEach } from 'vitest';

afterEach(() => {
    vi.useRealTimers();
});

describe('Given the getDelayedGreeting function', () => {
    describe('When we wait 0.999s', () => {
        test("Then the callback hasn't been called yet", () => {
            // Arrange
            vi.useFakeTimers();
            const callback = vi.fn();
            getDelayedGreeting(callback);

            // Act
            vi.advanceTimersByTime(999);

            // Assert
            expect(callback).not.toHaveBeenCalled();
        });
    });
});

Advanced Usage

When writing tests, we will put a great importance to having the right situation at the right time. If the previous example is working, occasional delay could occurs and make the test flaky. So to ensure nothing more will happen with time passing, we would ideally cancel every running timer.

That’s where vi.clearAllTimers() can help us: by cancelling everything that is running, we make sure that nothing will prevent our test to work as expected. Here is the previous example improved:

import { describe, expect, test, vi, afterEach } from 'vitest';

afterEach(() => {
    vi.useRealTimers();
});

describe('Given the getDelayedGreeting function', () => {
    describe('When we wait 0.999s', () => {
        test("Then the callback hasn't been called yet", () => {
            // Arrange
            vi.useFakeTimers();
            const callback = vi.fn();
            getDelayedGreeting(callback);

            // Act
            vi.advanceTimersByTime(999);
            vi.clearAllTimers();

            // Assert
            expect(callback).not.toHaveBeenCalled();
        });
    });
});

This ensures that any timers scheduled after the specified time advancement with vi.advanceTimersByTime() won't interfere with the assertion, making our tests safe.

Using vi.clearAllTimers() after vi.advanceTimersByTime()ensures that no timers scheduled after the specified time advancement will interfere with the assertion. This makes your test more robust and less susceptible to unexpected timeouts caused by lingering timers.

But sometimes, what we want is more than just advancing time: we want to make the timer to be executed no matter how long it lasts.

Let’s imagine a game that tries to improves your reflexes: the callback will wait a random timeout before calling the callback where a mystery number will be display for you to enter. The method would look like:

function getMysteryNumber(callback) {
    const number = Math.floor(Math.random() * 10);
    // Get a delay between 1 and 6 seconds
    const delay = 1 + Math.random() * 5000;
    setTimeout(() => {
        callback(number);
    }, delay);
}

To be sure that the method is working, we can use vi.runPendingTimers() to execute the timeout no matter the delay:

import { describe, expect, test, vi, afterEach } from 'vitest';

afterEach(() => {
    vi.useRealTimers();
});

describe('Given the getMysteryNumber function', () => {
    describe('When we wait the delay to be completed', () => {
        test('Then the callback is called with the mystery number', () => {
            // Arrange
            vi.useFakeTimers();
            vi.spyOn(Math, 'random').mockImplementationOnce(() => 0.5);
            const callback = vi.fn();
            getMysteryNumber(callback);

            // Act
            vi.runOnlyPendingTimers();

            // Assert
            expect(callback).toHaveBeenNthCalledWith(1, 5);
        });
    });
});

Here, we use vi.spyOn() to stub the Math.random() function and mock its behavior to return a specific value (0.5) for the delay. This allows us to control the randomness and ensure a consistent delay of 5 seconds in the test.

Now, no matter how long the delay is supposed to be, the test will be executed quickly.

But what if you have an interval timer that stop after a specific amount of time? For example, you have a method that counts up to five seconds:

function startCounter(callback) {
    let count = 0;
    const intervalId = setInterval(() => {
        ++count;
        if (count === 5) {
            callback('Done!');
            clearInterval(intervalId);
        }
    }, 1000);
}

For interval timers that complete after a specific duration, you can use vi.advanceTimersByTime() to advance the virtual clock by the expected interval duration. This approach often provides more control over the test execution. However, vi.runAllTimers() is a viable alternative when you need to ensure all timers, including intervals, are run to completion. Here is an example:

import { describe, expect, test, vi, afterEach } from 'vitest';

afterEach(() => {
    vi.useRealTimers();
});

describe('Given the startCounter function', () => {
    describe('When we wait 0.999s', () => {
        test("Then the callback hasn't been called yet", () => {
            // Arrange
            vi.useFakeTimers();
            const callback = vi.fn();
            startCounter(callback);

            // Act
            vi.runAllTimers();

            // Assert
            expect(callback).toHaveBeenNthCalledWith(1, 'Done!');
        });
    });
});

Conclusion

Fake timers in Vitest provide a robust way to test time-dependent code : they allow you to write faster, more reliable, and more focused unit tests.

By simulating the passage of time, you can write tests that are both fast and deterministic. Whether you are dealing with simple timeouts or complex interval logic, Vitest’s fake timers have you covered.

With this guide, you should now have a solid understanding of how to use fake timers in your Jest tests. Experiment with these techniques in your own projects to achieve more effective and maintainable tests. Happy testing! For further details and advanced usage, refer to the Vitest documentation.

Improve Performances With Dynamic “Content-Visibility”

Bruno Sabot — Mon, 26 Jun 2023 19:05:42 +0000

Initial Considerations

This article presents a few technologies that are only available on some browsers. This should not be considered as the solution you can use to solve all your performance issues but as the solution to improve some of your users’ experience.

Also, you should consider using it more as an experiment than an ultimate performance saver that can help you understand how a browser's rendering works and what can be controlled.

Finally, the code could also be improved by doing several enhancements — performance or features — to make it production ready. I use it on some websites, but it hasn’t been tested at scale.

The Content-Visibility CSS Property

When we have a big page with a huge amount of data, the browser will struggle with one of its steps to display the page because it asks for a lot of work.

The browser will go through the following step:

Loading
Scripting
Rendering
Painting

The bigger the page is, the slower these operations will be. But in this game, the rendering step is an Achilles’ heel for everyone looking for speed. The browser makes a lot of calculations here to prepare the painting, and the more the page is complex, the more time it takes.

Unlike a house where you can do the painting once the construction is complete — and maybe once in a while for a deserved refreshing — a browser has many reasons to make a lot of renderings over time. JavaScript DOM modifications, scrolls, dynamic carousels, and so on.

To help developers take more control over this, Chromium has introduced a new CSS property call content-visibility that aims to solve this performance by skipping this rendering part when it is not necessary, mainly because the concerned block is out of the screen, which, in our single page applications, can happen a lot: have you ever seen an e-commerce website without a vertical scroll?

This newly introduced property takes three possible values, which are visible, hidden and auto. As you can imagine, the first one, visible exist to tell the browser that a block should always be rendered, no matter if it is on-screen or not, while the hidden value always hides the element from rendering. Since we want to improve our performances, the last one is the one that is the most interesting for us: it will make the browser look at the supposed position of a given block and decide by itself if the block should be rendered or not.

How Does It Work?

Setting this CSS property to auto will prevent the browser from executing the rendering part of the displaying, saving a lot of execution time (rendering + painting) on all the hidden elements of the page. Then, as soon as the elements appear on the screen, the rendering will be made, and you can see your content properly.

However, if it hides the rendering, you should not be concerned about SEO issues or having accessibility consequences: all the document model -and therefore the accessibility tree- is available: web crawlers will not suffer from any issues, and the screen readers will work as expected. You should also remember that this CSS property is experimental, so the old-fashioned system will ignore it until it is correctly implemented.

Finally, once the element quits the screen, it is removed from your page rendering. It will then save another list of potential heavy calculations, such as if you have @keyframes animations, for example.

Setting the Block Size

As the content is not always rendered on your page, one thing might look a bit strange: your window height will not be the full-rendered one, so scrollbars won’t be able to do its proper height. With content removed from rendering as it leaves the page, this issue is not only a problem at the bottom but also at the top: the upper part of the screen is removed from the page height as you scroll it out of the screen.

So, to make sure the space is reserved, you can use another CSS property there reserve this very space when using the content-visibility CSS property: it is contain-intrinsic-size that you can use to set the width and height of the elements. content-intrinsic-size: 400px 300px will tell the browser that the associated block is 400px width and 300px height.

But…

It is very easy to use if you want to display a card as you have fixed dimensions. Still, sometimes, you might not know the size of the element you are not rendering, such as in a blog post: paragraphs have various sizes, and code blocks can also have differences in dimensions. And blog posts will likely be long and complicated. Hello, syntax highlighting on code blocks.

It is a shame that our performances won’t have the amazing benefit of this powerful feature.

Hopefully, a few other amazing APIs in the browser can come to the rescue!

The `IntersectionObserver` JavaScript object

The IntersectionObserver is an API that detects when a block gets visible or leaves the screen viewport, which is pretty much the same, but using content-visibility this time, it is JavaScript, so it gets more interactive and customizable.

It has a lot of awesome usages, such as loading the next or previous pages in an infinite loading page as soon as the footer gets into the viewport, pausing a video if you scroll it out of the screen, or lazy loading images -even tho you should use loading="lazy" instead.

How Does It Work?

To use an IntersectionObserver you will need three things:

A callback function will be executed as the element enters or leaves the screen's visible part. This is where your magic will happen.
An observer object that will handle the observation configuration, such as the sensibility of the detection. It also means that you can use the same configuration object for every block of your code you want to observe, reducing the impact on the memory.
An attachment to a DOM object that we will observe. In our scenario, it will be the block with a dynamic height on which we can’t use the content-visibility property.

Enough with the words. Here is a very simple code example of how to get started:

Deep Dive Into the Callback Method

As you saw in the previous gist, the callback method takes two parameters.

The first one is the list of intersections that have just occurred. It is an object with many parameters that might be used in different use cases, but we can focus on the two most important for today:

isIntersecting which is a boolean set to true appears according to the configuration false, otherwise. That’s the only information useful in our use case, as we want to know if the element has reached the viewport and thus has been rendered and now has a real height.
target which is the element that is currently intersecting. It will be the same as the DOM object we listened to, but since a single IntersectionObserver can be used many times, this property is more reliable.

The second parameter is the observer instance. It allows us to start listening to another element if we make an infinite loading system. Still, in our case, we can stop the observation as soon as we collect the height.

Now, let’s see how we can link it to the content-visibilityfeature.

Handle Blocks With Dynamic Heights

Linking IntersectionObserver and content-visibilty is now very simple: we have every tool we need, and we have to add the smart behavior in the callback method to make an overall improvement on our webpage:

First, we create an IntersectionObserver to detect visibility changes in a given block. When the detection is done, we will get into the callback method.
Inside the callback method, we can collect the given element's actual size since the browser has rendered it. It is as simple as const { height } = entry.target.getBoundingClientRect();
We can now set the CSS properties on the object. It is a one-liner: entry.target.style.containIntrasicSize = `${height}px` . There is no need to set the content-visibility: it should have already been assigned in your CSS to make this work. If you haven’t already, you will lose the benefit of delaying the rendering part.
Finally, since the height is now assigned, we don’t need the observation anymore, so we can stop the observation on this block

Here is a code example merging these two features:

Handling Responsiveness

There is one final touch we can bring to our code to make it more production ready: if the window gets resized, some blocks might have a changed height, and thus, our assigned value is not relevant anymore. And that’s the beauty of responsive designs.

To ensure the height is always the right one, we can just observe the resize window event, remove the assigned height and bring the observer back to business. As soon as the element crosses the visual part of the page, its height will be recalculated.

Conclusion

We are now ready to make our pages a lot faster! These two light APIs allow the developer to be more in control of what the page needs to display at any time. We can benefit from the power of content-visibility event on blocks with a dynamic height!

If you are working with frameworks like me, you can find a React hook and a Vue composable you can reuse in your applications at the end of this blog post.

Feel free to give me feedback on your Core Web Vitals improvements with this snippet!

React Hook

Vue Composable

Want to Connect?

If you want to learn more about JavaScript and React, feel free to follow me on Twitter.

JavaScript Spread and Rest Operators: When To, Why To, and How to Use Them

Bruno Sabot — Fri, 01 Apr 2022 07:05:42 +0000

Ecmascript has introduced the rest and spread operators a few years ago. It is a powerful tool that helps a lot our code to be more concise and cleaner.

However, it is not that easy to understand how it works at first and what is the main reason they do not have the same name.

In this blog post, I will explain the naming, how it is working, and in which situation it is a time saver.

Assignment shortcuts

Before we talk about the rest operator, you need to understand a new variable assignment method to shorten the code declaration.

It consists of using an array or an object on the declaration part of an assignment.

The code looks like this:

As you can see, we are creating an array naming the indexes directly in the assignment part. This code is actually a shortcut and the same of the following code:

If this code is pretty simple, it might be a bit longer and therefore complex- when having a dozen of items in the array.

This is working the same with objects. Here is the code:

The only difference with the array is that the naming is very important since we are extracting the object from its keys.

If for any reason, you need to change the name (it could be a duplicate key), you can use the : operator to change the name. Here is an example:

As you can see, we have a duplicate red key that we had assigned to a frenchRed variable and a belgianRed variable.

If you acknowledge this, you can now start the next part about the rest operator, that uses this variable assignment method.

The rest operator

The name has been chosen wisely, the rest operator is a method to select the rest of the data that hasn't been already assigned.

This operator uses three dots ... as a symbol to tell the JavaScript parser that we are using the rest feature.

But one point is really important to understand: the rest operator is only used on the assignment part of a JavaScript code. We saw the new assignment method in the previous chapter, but the reason it is important to link rest and assignment will be discussed later.

The rest operator works on the array since the beginning of the feature introduction, and a bit later on objects. If you managed to make it work on other JavaScript types, you are using coercion which I recommend you not to use. But this might be the content of another blog post.

Now that the basics are ok, let's see some code on how it looks:

As you can see in the previous code, the assignment is the same than the first chapter, but we add a single variable name with three dots ... instead of the whole elements left.

This will tell the JavaScript parser to create an array with anything else in the first assignment, and an object with anything else in the second one.

Why do we need the rest operator?

We mainly need this operator to extract a part of the array for a specific behavior and use the rest for something else.

Imagine you have an array with every soccer player of a team and you want to separate the goalkeeper from the field players, so you can give them the instruction to go full attack. You can do it with the following code:

Of course, you can select two items if you want to keep a defender in the field:

You can add as many variable declarations in the assignment, but you can not skip some variables in the rest argument. For this, you will need the spread method we'll see later.

For objects, the rest operator is very useful when you want to remove an element from the object you want to forward.

Imagine you are developing a Node.js service to manage users, and you want to send to the client everything from the object except the password and the password's salt... In this case, the rest operator will help you.

Here is the code:

With this, you can simply return the right data for the client's request

The spread operator

Like the rest operator, the spread operator also uses the three dots ... as a syntax.

The way to make the difference is to understand that the spread operator will be on the operation part of the variable assignment.

The goal is pretty the same as the rest operator, but instead of recovering the rest of a variable, we are adding the rest of another variable to a declaration.

Code speaks better, here is an example of how it works:

On the previous example, we have combined two objects with the rest operator. If it's still not clear, here is an example that could help.

The syntax is not valid JavaScript, but it illustrates what is done under the hood.

As seen in that example, using the spread is kind of removing the brackets from our variable. Since it is something invalid in JavaScript, we need to put that in another array, making an array duplication in the meantime.

In arrays, the position of the rest operator is very important as it places the elements in the specified position.

Here is an illustration of that:

In the previous sample, I also have another item in my array which is non-spread operator data. It is a perfectly valid thing to do if you want to complete your object with a unitary value. It could be having an array with the last execution result, complete with the previous results.

For objects, the spread operator works the same. However, as objects are key value items, the order does not really matter but you need to make sure your keys are not duplicated or they will be erased.

Here is an exemple:

As you can see in the previous example, the position of the spread operator is very important in case of duplicated keys.

As it's the case for arrays, the spread operator removes the braces from the object, but since it's invalid syntax, we are putting it back in another object duplicating it at the same time.

When do we need the spread operator

As we have seen in one of the previous examples, the spread operator is mainly used to merge arrays from different sources or having defaults key/values when using objects.

You might find plenty of other usages while developing your JavaScript application.

Combining rest and spread and more

Since it rest and spread are not on the same part of the assignment, you can combine both their usage in the same line of code. You should however take care of not using this to make your code harder to read: it will be counterproductive.

You can also apply the spread operator on a function return, as long as the value returned matches an array or an object depending on your usage.

Here is an example:

Conclusion

Rest and spread operator are very powerful features you can bring to your web application starting today.

If it is a bit hard to understand at first, it will make your code cleaner and more robust.

Want to Connect?

If you want to learn more about JavaScript and React, feel free to follow me on Twitter.

Loading Gists in a NextJS Application

Bruno Sabot — Tue, 01 Mar 2022 17:05:42 +0000

Introduction

All my blog posts are available on my personal website. Under the hood, they are saved as markdown files.

It allows me to easily write the posts, but when I’m cross-posting on other platforms, I don’t have the luxury to get the syntax highlighting and the right colors for the code snippets.

To make it prettier on every platform, I’m using Github Gists. It renders well everywhere, but I don’t want to have Github’s code blocs styles on my blog but I prefer something that match my website design. To do so, I have to adapt the markdown parser I use to load and render the code from gists in the way I prefer.

In this post, we will see how to create a blog post using markdown files, how to create and integrate a remark plugin, highlight the recovered code it with react-syntax-highlighter and keep the performances as good as possible.

Initial Situation: Loading Markdown in a NextJS Page

Before getting into the code for loading gists, we first need to make the blog to load markdown files. To do so, it needs two different items:

A markdown file containing the blog post
A NextJS page containing the markdown loading, parsing and rendering

Let’s start with the markdown file

What Does The Markdown File Looks Like

The markdown file is separated in two different parts: the metadata and the content itself.

The metadata are here to give informations on the author, the date, the language used (I have posts both in french and english), the URL path, tags, etc.

These informations are isolated from the content by three dashes --- at the begin and three and the end.

Here is a light sample of what a blog post can look like:

The file is very simple. If you are not familiar with markdown, you can read this doc from Github to get started: you will learn how to create lists, links, add image and more.

In the reality of my bog, I have more metadata fields to handle canonical links, image, tags and more. I removed them from that post as it is unnecessary noise for its topic.

Loading The Markdown File

The first part to render a markdown file is to load it. We are using basic NodeJS code to:

Lookup all files in a folder
Filter the md/mdx files only
Load the file

It might be overkill, but on my blog, I need to get every posts to find the most similar posts of my current article, based on a calculation on every common tags they have. I will have to load every post to find out anyway.

Here is the code:

If you are creating a simpler blog, you might prefer to directly load the right file instead of all of them. To do so, you just need to use the fs.readFileSync function to get your file.

Now the posts are loaded, we need to search inside the file which one is the right one for our current page.

To do so, I’m looking for the post with same path as requested, but I first need to parse my markdown for metadata. I’m using a package called grey-matter to get them.

Here is the code:

The loadGreyMatterPost is a function returning a file representing our markdown at the grey-matter format. We still have to transform it into an HTML code to use it. As explained earlier, I am also returning all the posts to make matches based on the tags. It will however not explained in this post.

Since I’m using NextJS, I can now use the package next-mdx-remote which can make the transformation from the grey-matter format to a MDX one.

Here is the code:

Adding The Loaded Data Inside a NextJS Route

To avoid enormous and slow payload, the loading part is added inside the NextJS route’s getStaticProps method. It will only parse the files at the compile time, which is OK with markdown, and serve static pages the faster possible.

Here is the code:

Display the blog post in the page

Now we have all the required informations, we can include them in the NextJS page.

It will need two external components:

MDXProvider which is a component that can handle defaults informations for every children markdown document
MDXRemote which transform the MDX content to HTML React components

Here is the code:

And it is done! We are now able to write markdown blog post and get them rendered as HTML in our NextJS application!

Creating a Remark plugin

The AST transformation

A remark plugin is a function that return another function. That last one gets an AST -Abstract Syntax Tree- representing the markdown document.

The AST can get numerous fields, but here is a simple typescript interface of how it is structured:

When using markdown, the AST for code does not have children or attributes, while the paragraph AST does not have any value. To understand how it is built, imagine the following markdown:

The associated AST will be:

With this in mind, we can think about how we are going to include our gist.

Fetching a Gist From Github

I chose to include the gist in an inline block code, with a prefix gist: and then the username and ID. It will look like this:

`gist:brunosabot/00000000000000000000000000000000`

When rendering this content, the generated AST will be composed of a paragraph node with an inlineCode child. What we need to do is to replace the paragraph the loaded code from Github.

As we need code from Github, we will also need to fetch the gist. A gist can be made of one to several files: we will first need to iterate on the file list then load each one of them.

Here is the code:

The first fetch query gets a JSON containing metadata for the gist, especially the file list in the gist.

When the list is recovered, we iterate them to load as text the code associated to every file.

Visiting And Updating The AST

The gist plugin should alter the content of the original AST. We are going to visit the document nodes and update it as we want.

To visit the different nodes, we use the async-unist-util-visit package. it will apply a method on every AST child that match the requested type.

As explain before, we are going to look for inlineCode, starting with gist:, inside a paragraph node, then parse it and load the gist.

But let’s focus on the visiting code:

One important thing to notice is that the AST must be mutated and not returned. Since visit is a promise but does not wait for the callback to resolve, we need to use a hack consisting on adding the work in a promise list and wait them to resolve before the plugin method to end.

In the code snippet:

The node.children.some method is looking for a gist snippet in the code
The Object.assign method is the way to update the content of the object without loosing the reference
The delete is not mandatory, but I like to keep a clear object with only the required fields.

In the plugin, we are using a loadAndTransformGist method that is called when we detect a gist snippet in the code.

As it written in the function name, this method will load the gist and make the proper transformation to be included in the AST.

Here its code:

In this snippet, the first part is to check it the snippet is valid, which is basically checking if the AST value is empty or not.

I could make few more checks, including one to validate that the gist value is correct. I choose not to since I’m often checking the rendering of my post: I can see very quick when the ID is wrong since the app will either crash or don’t show anything.

I’m then extracting the gist ID, load it with the previously created loadGist method.

Then, I have two possibilities:

First, there is only one file in the gist. I will just replace the current paragraph with a bock sample. The getGistAST will give me the code AST that I will return for the calling method.

Second, there is multiple files in the gist. I will iterate on them and add them as children of the paragraph node.

The getGistAST is basically a mapping method with the following code:

Translated to english, this AST node is a <Gist> component, with:

A file attribute representing the file name
A code attribute which is the actual code
A lang attribute containing the file language, calculated from a mapping method

And here is the mapping method:

And everything is done, we just need to update our transformGreyMatterToMDX method, adding the plugin:

Using a Custom Rendering Component

Now the markdown is able to read gist snippets, there is a last step to make the actual code rendering: we need to create a Gist component to make the proper display.

To do so, I will use the React Syntax Highlighter package.

Here what the component looks like:

We first have a single div, if the file name is available to display it.

Then, we use Prism from react-syntax-highlighter with the following attributes:

language: the programming language the snippet is on. If not available, we set text which a a default and non highlighted language
showLineNumbers: this display line numbers on the side. If text, it is better not to have them
wrapLines and wrapLongLines: activate, when the code is text wrapping the lines. I found it not easy to read on highlighted code.

To be recognized, this Gist component needs to be included in the components given to the MDXProvider

Here the code:

In bonus, you can see I’m rewriting the img component to add the loading="lazy" attribute. I will help my blog post to have better performances.

Keep The Performances As Good As Possible

One problem with React Syntax Highlighter is that it will load a lot of language you might never need.

Hopefully, there is a way to use a lighter version of the library, but it require us to load the languages manually.

Here is the <Gist> component code with the loading system:

Conclusion

Creating a Gist plugin for a NextJS blog requires us to know about and manipulate the AST format which might not be trivia.

I hope this post can help you understand how it works and how you can also add your gists files right into your blog.

If you want to learn more about JavaScript and React, feel free to follow me on Twitter.

Fetching Data With React

Bruno Sabot — Tue, 01 Feb 2022 19:01:08 +0000

Photo by Sander Weeteling on Unsplash.

Introduction

When we create a React application, there are a lot of chances you will have to fetch data from a remote server.

Depending on your project, you will probably have to make simple calls or use advanced techniques to get your data cached or up to date.

In this blog post, we will discuss custom-made data fetching but also have a quick preview of React Query and SWR. Let's take a tour of these common techniques so you can pick the right ones for your use cases.

Basic Data Fetch

To explain how to make a custom data fetching, we will pass through a few steps to understand how to make the code robust enough, based on what it can be to think about the perfect loading system.

If you are not confident enough to manage it on your own, I recommend you go directly to the last sections on SWR and React Query.

Using the JavaScript Fetch Method

To get a basic data fetching working, we only need a place that will contain the recovered data and a method to make the actual fetching.

Speaking of the code, it consists of the useEffect hook to make the data fetching and a useState hook that will store the data as soon as the request end.

As you can see, you can get your data from your remote server in just a few lines of code. Gathering data is as simple as that with React.

Separating Concerns

The previous code was very simple, but one common principle in web development is the separation of concerns which we didn't really respect in the previous section with the two hooks.

There are plenty of ways to make it done. For example, I will use a Provider component and the React contexts to handle this. You can find out more in my previous article How I dropped Redux for the Context API.

To follow this way to separate concerns, I will now wrap the displaying component into another one that will manage the data fetching. Here's the code:

Our rendering code is now a bit cleaner since the logic has been extracted to another component in charge of the logic.

You can see that I choose to use a loadData callback along with the useEffect hook this time. This is because I consider improving the method with additional parameters - not in this tutorial though - to manage pagination, revalidation, and more.

In the same way, I have encapsulated the data inside a subobject values, to be prepared to support another sub-object actions for manual reload and more.

Adding Loading and Error States

In many applications, we want to show the user that we are currently loading the data or if we encounter an error.

To do so, we just have to add two boolean states corresponding to the loading and the error.

These states are meant to work this way:

By default, the loading state should be false since there is no operation made
As soon as we launch the data loading, the loading state should switch to true
The loading state should get back to false as the request end
By default, the error state should be false since there are no errors yet (and hopefully, ever)
As soon as we launch the data loading, the error state should be reset to false to remove an older error
The error state should switch to true if the loading goes wrong

Here's a code sample:

Now, our application reports the loading and error states with a custom message to the user.

This solution stays pretty basic, but you are free to add additional data, such as a specific message for the error, better loading, or a skeleton of the page to make an even better interface.

A common mistake made on a lot of websites is to give no intel on what happened on a website. You can lose users because they think your app has crashed if there is no loading indicator, or they may think your service is simply not working if the error is not explicit enough.

My personal recommendations are:

Add a skeleton of your page while loading the data
If possible, show a loading progress indicator
If the first point is too complicated, add a spinner or a text indicating the data is loading
Cache the request to avoid unnecessary waiting from the server or propose a "Stale While Revalidate" behavior
If you encounter an error, give your user precise information on what is going on., e.g., "Your data hasn't been saved because it is not valid" or "We encountered a problem loading this product… Please try again later."

Factorize to Hooks

When developing an app, you will probably not have only one place where you will need to load data. Each one of your pages are candidates to fetch remote servers.

With the previous code, we can clearly see a lot of code that will be copied if we want to keep the same code structure, even if the only update we want to make is an URL change.

A good candidate to resolve this is to create a custom hook to contain the error, loading, and data state hook along with the data loading method. This hook will get an URL as a parameter, as shown below:

Now, all the data fetching will be managed by the hook, and the provider code will be simpler to read.

Once again, this is a pretty simple use case, you might need to handle:

Making POST request
Adding, on a POST request, a body content
Handle HTTP headers
Manage authentication

Do We Really Need the Separation Concern in a Component?

Our provider became a simple pass-through from the hook to the component and we can ask ourselves if it is still a relevant component to include in our code or if it is unnecessary.

I believe that the less component you have, the easier your code will be read by anyone else (validating the KISS principle). I choose then to remove the Provider part and only keep the view component and the hook. Here's the code:

Why have all these steps to get there? It is a pretty common mistake I saw in many projects to keep legacy code layers. I'm hoping that you will avoid these mistakes by seeing a complete rewrite of the code the more features you are adding to your data fetching.

Depending on my needs, I can also remove the useEffect part that could have been done here since we obviously always want to load the data straightaway.

Using a Data Fetching Library

Writing data fetching is very simple, but there are many reasons where coding all by yourself could become a huge pain. The preview code we just wrote could be easy to imagine in your mind, but what if you need to:

Add a query caching system
Handle an always up to date data
Debug your requests
Handle pagination and infinite loading
Keep data available offline

Could you picture all the code required in your head right now? I personally can't, so I'm going to leave this to the greatest geniuses.

So our requirements give us a lot of work, not even including the code maintenance, and the security patches that will be required. Hopefully, there are a few open source libraries that already manage this for you, such as React Query and SWR.

These libraries might be a (very little) bit more complicated to implement inside your apps than the hook we have previously coded, but they are also way more powerful.

Let's see how we can start using them.

SWR

SWR is a lightweight library developed by Vercel.

SWR will however not handle the request itself. You will need to create a fetcher method, but the code stays pretty straightforward, as you can see below:

Almost all the logic we previously wrote ourselves is managed by the useSWR hook. Don't think that the code magically disappeared!

You might ask yourselves why should we use SWR if we still have to handle the fetcher method? Because SWR has a lot of useful features including the following:

It automatically caches your requests
It handles React suspense
It automatically revalidates data when focusing the window and/or on regular intervals
It can manage pagination, SSR

React Query

React Query is a little bit complicated to get started with: It will need a Provider component on the top of your application, combined with a query client.

Also, like SWR, the actual fetching is yours to make.

With that done, it will be as simple to use as everything we have covered so far, with only a different labelling system.

React query also have a lot of awesome features you can check in comparison to other systems, available on the React Query website, including:

A powerful cache system
Dedicated dev tools
React Suspense support
Auto-refreshing
Pagination, SRR

Conclusion

There are plenty of ways to load data in React - from managing our own code to using powerful libraries.

Personally, I would change the method I use depending on the size and nature of the project in the following conditions:

When making a very small website with few requests, I will make my own fetching code (SWR and React Query came at a size cost)
When the project gets bigger, I will go for SWR (Best size/features ratio)
On big projects, I prefer to use React Query since it will cut me the work on many useful features (advanced features needed)

Thanks for reading. Please join me on Twitter if you want to learn other things about React and more.

Core Web Vitals Dashboard On Google Analytics

Bruno Sabot — Sun, 19 Dec 2021 09:04:18 +0000

Photo by Myriam Jessier on Unsplash.

Core Web Vitals are a set of well-known metrics used to measure your website performance. It’s often the entry point to investigating what is wrong with someone’s website and measure the progress made optimizing the overall speed and stability.

Some of you (or your clients or employers) might not have the budget to invest into the various existing performance monitoring tools, or maybe no time to test and integrate them to the website, but they have a Google Analytics tracker set. With a few lines of code added, it is the perfect tool to start monitoring the performance experienced by the users when browsing the various pages of your web site.

Including the tracking code

In my example, I will be using Next.js which is a React SSR (server-side rendering) framework with a lot of internal optimizations, plus wonderful components such as <Image> and <Script> to improve the scripts and images loading and delaying/scheduling.

To extract the tracking part, I first have a reusable <Analytics> component which is responsible for including the two tags required by Google Analytics, and I’m using Next.js environment variables for the customization part.

With the hypothesis I have in the first paragraph, you may not need this to be included since your client is likely to already use Google Analytics tracking, but you can use it on new projects or existing ones without tracking system.

Reporting Core Web Vitals with Next.js also needs to add/update the _app.tsx file to add the metrics tracked and the page views tracked.

Once again, here is the code if you do not already have Google Analytics on the project.

There are two parts in the file to consider here:

a reportWebVitals method that is automatically used by Next.js when it gets a Core Web Vital metric. If you are not using Next.js, you should look at the NPM web-vitals package to see the right method in your case. a MyApp component that includes the <Analytics> component presented earlier and a (bonus) hook to track the page change in Analytics. This one is to be used only if your client does not already have Google Analytics installed or you might duplicate the page change events sent to the server. You now just need to add your UA value to the .env file or as an environment variable NEXT_PUBLIC_GOOGLE_ANALYTICS and you are ready!

Viewing data directly in Google Analytics

After few days collecting, you will see the events (in green on the screenshot) appearing in Google Analytics in the Behavior (in blue) > Events (in purple) > Top Events (in red) > Event action (in orange) menu.

And voilà, now you can report the real performance usage to your client directly in Google Analytics.

Going further by creating custom dashboards
If the previous screen give us the metrics, it is still a combined view where the chart shows all the metrics combined.

To have a very specific view for LCP, FID and CLS, we can create custom dashboard by clicking on the Edit button on the top right od the screen.

Once in the creation page, we need to update three block on the page:

The Dashboard title (in blue)
The Tab name (in purple)
The filters (in red), to Include / Event Action / LCP
Then press the Save button and you are done for the first metric!

You now just need to reproduce the previous steps for FID and CLS and you will have 3 custom reports with the Realtime User Monitoring (RUM) for your users!

Conclusion

Adding dashboard for Core Web Vitals in Google Analytics is an easy way to get a Realtime User Monitoring of your website performance.

If the created dashboard are too simple, you can go further thanks to Google Analytics power by adding second dimensions such as pages, device type, and even with conversion custom metrics.

Happy monitoring!

Build an Easy Popup System With React

Bruno Sabot — Fri, 12 Nov 2021 17:16:47 +0000

Photo by Windows on Unsplash.

Concerns About Existing Systems

There are plenty of popup systems out there, but they usually don’t meet the high-quality requirement I have on user interfaces and development simplicity.

When I’m adding a popup into a website, it is important to me that the system is:

Simple to use: as a developer, I don’t want to spend time creating tons of components and states just to activate a popup. A developer better spend their time on the domain specificities rather than brainless tasks
Customisable: this is usually my main point of complexity since popup systems are almost always shipped with styled components, making it - harder to make them look as close as your UI Designer has imagined them.
Accessible: Accessibility is usually created aside from the systems because it asks for more work, even if it doesn’t need that much work on it.

With these requirements, I always find it difficult to find a library with what I need and the blocking points are often too painful to be worked around.

Even if it might not be intuitive, the last standing option is to create our own system so that will ensure a perfect match with your needs

Enough speaking, let’s dive into a popup component system creation.

What Are We Building

There are a few things we want in this popup system:

A custom modal component that will be in charge of the popup style, including background, position, and a closing button
An easy-to-use modal component with a simple toggle system that will be in charge of the functional part of the popup.
A changeable state to make the CSS modal softly appear
Support for people who need a browser with reduced motion
Handling accessibility on the modal to tell people with disabilities the popup has appeared and where to click so the popup will be closed
A clickable background overlay to close the popup as we click out
Handle the escape key to close the popup

That’s a lot to do so we better get started.

Requirements

The first thing to have a modal system is to have a modal root, where the system will take place. To do so, we just need to have a new div#modal-root element in our root document.

This part is important so the modal can be easily styled. With a separate root element, we are sure that the parent elements of the modal does not have styles that will make it harder for us to reach the perfect style.

To be sure that the modal will always be on top of the document, we just need to add the right z-index on the application root and the modal-root.

Also, since the modal behavior is to be opened and directly occupy the whole browser’s page, we add an ARIA live region to the modal system so it can be announced to the user.

The aria live region is set to assertive because we want the readers to have the same behavior as the browser, which places the popup on top of everything else.

The modal components

The modal component is split into three different components:

A ModalPortal component that will link our modal to the div#modal-root element
A ModalView component that aims to handle the visible part of the component
A ModalAnimated component that will handle the popup domain and the CSS appearance effects of the popup system

The ModalPortal component

The ModalPortal component exists to link our popup to the div#modal-root element that we have created. Here’s the code:

It is made of four sections:

A ref corresponding to a simple div element, with the goal of holding the popup content. We do not use directly the root element so we are able to create two or more different popups if we want to stack them.
A first useEffect hook to create the div element. This is a security to make the system work also on SSR systems such as NextJs or Gatsby.
Another useEffect hook, to add the previously created div in the portal when active, and remove it when inactive. It will prevent the div#modal-root element to contain plenty of empty divs.
The render part, which is null if neither the div element created does not exist or the popup is not currently active.

The ModalView component

This one is basically a layout component so we can style the popup the way we want.

Even if I’m presenting only one template, you are able to use it for as many needs you may have such as:

A popup system
A designed replacement of the native alert and confirm modal
A notification system
Whatever else you can imagine

The present component is just a bunch of native elements with some styles separated into two sections:

An overlay button, so the popup can be closed when clicking out
The popup content itself, including a close button

The two blocks are siblings because we don’t want the click event to propagate from one to the other.

For accessibility reasons, both the overlay and the close buttons are native button elements with an aria-label attribute.

In the CSS part, I use various positioning techniques that you are free to adapt depending on your needs.

The ModalAnimated component

For the last part of the system, we need a component that will control the modal. Here’s the code:

This component has several tasks to handle:

It has to load the ModalView component. By default, I chose to use the ModalView component, but I also give the component a prop to be able to change it
It also has to manage the Modal portal component to include our content in the div#modal-root DOM element
It gives us access to an escape key support to close the modal.
Finally, it handles a nice but optional transition effect.

The CSS has a weird CSS Modules syntax to handle global classes, but it also uses the prefers-reduced-motion media query to shutdown the animation for people asking for it.

If the last part could be set globally for all elements, it is better illustrated in the component.

The useEscape hook

To improve usability, we can add another great feature to our popup system by adding an escape listener that can close the popup.

To do so, there is a useEscape(active, onClose); code in the ModalAnimated component, but this is yet to be implemented. Here’s the code:

The hook is quite simple, and it is made of two blocks:

an onEscape callback that memoize the keyboard event by listening to the keyCode for the escape key — 27
an useEffect method to bind it to the window document and unbind it as soon as the modal is unmounted

The usage

The usage is pretty straightforward: we need the ModalAnimated component with two props if we want a custom ModalView component.

The content of the popup itself is just the children elements passed to ModalAnimated. I usually put the content inside another component to keep the page as light as possible. Here’s the code:

Conclusion

By creating three light components and a simple custom hook, we are able to get a very modulable and customizable popup system.

While it can still be improved, we have implemented a system that will make your UI designer happy, and it implements the accessibility basics.

Did we check all the initial requirements?

Simple to use: yes
Customisable: we can customise the view very easily
Accessible: We do have a11y included in the code

Mission accomplished! Now it is your turn to use it and improve it in your projects.

Happy coding!

A Discord bot for Home Assistant

Bruno Sabot — Fri, 05 Nov 2021 21:28:54 +0000

Photo by Linus Rogge on Unsplash.

A bit of context

I’ve been using Home Assistant for a while to manage my connected home. Home Assistant or Hass is a Python based application I have installed on a Raspberry Pi and which is able to connect. to many services from Google Assistant, Philips Hue, The Zigbee Protocol, and many others -1857 at the time I’m writing this post-.

The software gaves us a perfect way to organise our homes, but I needed a powerful system that can allow me to get notified and request the instance from outside my home. Basically, the usages are :

Getting notified I left my home without setting my alarm up, then being able to activated the alarm
Asking a room temperature to activate or deactivate the heater
Turning on and off lights
Knowing when it is time to get the trash out for the morning collect

There are many ways to do this with Home Assistant, but I needed something that gets my attention quickly: when working on my laptop, I barely look at my phone. When I’m out, I generally don’t have access to my laptop. Moreover, I need something that is capable to notify all my family when something has to be done, especially when it is as important as setting the home security alarm.

I made many tests of many Home Assistant integrations, and finally the one that checked all my requirements was Discord -which I’m using for many other things-. Since some points where not trivia, here is a step by step guide to set and get data between a Discord instance and a Home Assistant instance.

The Software and requirements

First of all, I need a Home Assistant instance, which in my case is installed on a Raspberry Pi. I will not explain in details how to install it right here since the tutorial on the website are good enough. Also, I think you should play around with your instance before considering connecting it with Discord. To make an installation on your own, you can head to the documentation.

Creation of a Discord Bot

To create a bot, you need to go to the Discord developer dashboard and click on the New Application button to create your bot. Choose a name, Home Assistant for example, and click Create .

Use the purple “New Application” button

Add the application name and click Create

In the application screen that follows next, feel free to change the name, the application icon or to fill the application description, then head to the OAuth2 menu on the left.

In this menu, you need to get and save for later your App’s client ID . This ID will be needed later to activate the bot on your server.

Gather your client ID for later usage

Now you have your Client ID, we can head to the Bot menu to make the final configuration step of our application.

Once you are on the page, just click on the Add bot button and confirm the bot creation after having carefully read the consequences on the confirmation popup.

Click the left “Bot” menu, then click the “Add bot” button

In the newly created bot, you will be able to customise its name and its picture, but the most important part is to gather the bot token and keep it somewhere. You should so far have saved two things : the application Client ID and this Token.

Keep in mind that this token needs to be absolutely secret.
Anyone that get yours will be able to collect and send messages on behalf of your bot.

Click on “Copy” to get your bot token that will be used later, in Node Red

The final step is to activate your bot on your server. You only need to head to the following URL. Don’t forget to change the placeholder value with your previously recovered Client ID :

https://discord.com/oauth2/authorize?scope=bot&permissions=0&client_id=REPLACE_WITH_YOUR_CLIENT_ID

Once the validation window checked the pop will jump on your server, and you will officially be done with this part.

Select a server then Authorize it and your bot will jump in.

The flow creation

The next part of the configuration will take place in the Node Red module on Home Assistant. Once again, I will consider now that you know the software enough to understand the specific notions I might use.

Now that I’m considering you are correctly set up, we are going to install a required module: [Node-Red](https://nodered.org/. To do so, go to the Supervisor menu, choose the Add-ons tab, search node-red and install it. I will take few minutes before you can head up to the add-on configuration tab.

The Node RED add-on on Home Assistant

In the configuration tab, set at least a credential_secret to protec your data, then get back to info and start the add-on. I personally choose to activate the menu UI, so I can access it directly from the left menu, and the watchdog but it is a choice up to you.

After few seconds, the add-on is ready and so we are! Click on the UI link, in the menu or in the info tab from the add-on to get to Node-RED.

Node RED come with a lot of integrated plugins. However, the Discord plugin is not installed by default. You need to use the Settings menu to activate it.

Plugins are located in the Palette tab. Search for node-red-contrib-discord and install it. Some other plugins might work, but it will be up to you to test them.

The Setting menu

The node-red-contrib-discord plugin

The base workflow

The base workflow is made with four blocks :

discordMessage: listen to messages coming from Discord. You should use wisely in which channels your Bot is, since it will listen for everything. This block is configurable with a Discord token, the one you saved earlier in the Discord configuration. I recommend you add a specific role for your bot, and add him in very specific channels.
switch: controls the user rights. I basically use it to check if the sending user have the proper role. To do so, I make sure the msg.memberRoleNames contains my Discord role. This is very useful because I have a lot of people on my server, and I of course don’t want any of them to be able to interact with my home or get sensitive data.
change: update and parse my data to be handled somewhere else. I chose to make my commands on a 3 words basis (namespace, command, value). To do so, the change allows me to change the payload with a parsed value. It is pretty basic, but if you need something smarter, you can use the function block where you can write plain JavaScript. switch: get the namespace from the payload and head to the requested flow. It might contains a lot of different outputs. I only got four for now (light, temperature, humidity and help)

You can check the config I set in every of these blocks below

The discordMessage block configuration. Use the pencil button to add another token

The switch block configuration. Stewjon -Star Wars fan will understand- is the role name from Discord

Lowercase, trim and split the playload for my use cases

Switch to the right flow depending on the requested namespace

First flow: Calling a service

The first scheme I have made is something that allows me to turn on and off lights directly from Discord. It is made of three basic steps.

The light management on Discord

change: This first block is aimed to make a translation between a word and Home Assistant entity. I need to transform a sentence lik lumière bureau on _ into a call to the proper service. Basically, it means converting _lumière to light (namespace), bureau to light.lumieres_du_bureau (entity) and on into turn_on (some words are in french to be easier to understand for my family). Like I suggest on the base workflow, you might want to switch this block to a function block to write plain JavaScript, which I will do someday.
template: This second block convert a Node Red data into a proper Home Assistant Data, which is an object composed with three keys: domain, service and data
call service: This is the block that link our Node Red workflow with Home Assistant and make the proper call.

First scheme first block: changing Discord data into a Node Red payload

Second block: Formating the Node Red workflow for a Discord service call

Last block: Calling the Home Assistant service

Second scheme: Getting a sensor data

I also want to be able to recover informations from a sensor. I have currently implemented two of them, temperature and humidity.

I will only present the temperature since the behaviour will be exactly
the same for humidity, just the “Get entity value” content will slightly
differ.

Temperature recovery from Discord

change: Same as the previous scheme, allow to convert a word to the proper entity name.
current state: This allow Node Red to recover data directly from Home Assistant then continue the flow with the value provided
template: Template is this time used to format the data to be sent in Discord.
discordSendMessage: Making the actual call to Discord. A new message from the bot will appear in the proper channel.

First scheme first block: changing Discord data into a Node Red payload

Recovering data from Home Assistant

Simple message formatting

Sending the message in the same channel we got the incoming message

Result shown in Discord

Third scheme: A CLI-like help

Finally, I want to be able to show an help message to whoever can use Home Assistant.

The system is just one big switch we are going to see together.

CLI-like help workflow

To do so, we are going to need only three types of nodes:

switch: This node will make the choice of the right template depending on the help type : light, humidity, temperate, and, if there is no type given, the default help.
template: There are a bunch of templates. Each one is just plain text corresponding to the help I want to show on screen
**discordSendMessage: Sending the message to the Discord server so it may looks like the bot is answering me.

Switching to a default help or a specific one

An help template example

Finally sending the message to Discord

Conclusion

Home assistant is a very powerful tool and combined with Node Red, it can be absolutely amazing.

The examples I have presented here are very simple on purpose, but it can be enhanced to take your Home Assistant to an higher level. I might share other posts later to explain some other workflow I had implemented.

I hope you’ll get closer to the perfect home automation thanks to this tutorial

My Journey From React to React Native

Bruno Sabot — Mon, 21 Sep 2020 14:32:03 +0000

Photo by Mukuko Studio on Unsplash.

I’ve recently started working on an Android application, and as a React developer, I made the easy choice to use and test React Native to do so because it helped me stay in my comfort zone and also gives me the opportunity to explore iOS someday.

Even if it is the same framework, using React for native applications is a little bit different than React on the web.

I’m writing this article to share the main differences I have found between the two platforms along with a few tips I had to figure out to obtain the desired final behavior.

View or Text — There Is No div

When working on a web application, we mostly use div and span tags for many usages. Since we are not on the web, this is no longer a possibility.

Instead, the content is made with View and Text that we could associate with the two tags above, but they have some additional constraints.

The View element

With the View element, you can’t add anything else inside other than components. That means it cannot contain text, which the Text component is for. As an unfortunate consequence, it has a larger tree in your application, but it helps to separate concerns between layout and text.

Hello world component in React Native

Based on the previous point, you can easily figure out that you can’t apply text-related styles to a View component. The text styles like color or fontSize need to be applied to the Text component.

Layout styles on View, text styles on Text

View is also a flexbox container that can only support two display values: none or flex. It can change numerous things if you are not confident with the model, but it is much more powerful than the classic block model used by default on the DOM.

You can learn more about this layout system on CSS-Tricks. Every flex property is supported in React Native, from align-items to flex-grow.

There is, however, one major difference between the web version and the native version: the default value of flex-direction. If we have row on the web, it is set to column in React Native. Basically, this means that elements are placed by default from top to bottom instead of left to right.

Flexbox usage on React Native

Finally, View is not clickable. If you need a click behavior on it, you’ll have to wrap it into a Touchable* component:

TouchableHighlight to add a background color on click.
TouchableOpacity to reduce opacity on click.
TouchableWithoutFeedback to have no feedback on click, which I don’t recommend for user experience reasons.
TouchableNativeFeedback (only on Android) to have the ripple effect on the button.

Example usage of TouchableHighlight

The Text element

If we can easily compare the Text element to a span tag on the web, the difference is as noticeable as with views.

The Text element — as it is aptly named — exists only to make the rendering of text contents. We cannot use it for any layout-related stuff we might need. Therefore, display: "flex" will have no effect. Neither will position.

However, the Text inherits styles from the parent Text component like it does on the web.

Text component style inheritance

Like View, the Text component is not clickable. If that’s a behavior you need, you will have to wrap into one of the Touchable* components.

Finally, Text is only meant to contain text and other Text components. You should not include layout-related components like View, ScrollView, or FlatList.

Replace Input With TextInput

Since the Native API is not DOM, we do not have input elements either, but React provides a component for the times when we need a form.

The InputField component works the same as input but also has a onChangeText attribute that accepts a callback with the value as an argument. No more need for event.target.value!

TextInput and the onChangeText callback

The CSS Usage

If I’m using CSS Modules when I’m working on a web application, it is a bit different on native, where the CSS usage is more the CSS-in-JS way. The stylesheets are created with the StyleSheet.create method that is provided by React Native and is a key/value object of class/styles for the component.

Styling with StyleSheet.create()

If there are units in CSS, there are not in React Native — or more precisely, units are always set in dp, so the render will be right even if the phones do not all have the same pixel ratio. It makes the CSS usage a bit different, but if you want to make things simpler, just consider them pixels.

If we used to have shortcuts in CSS, it is not the same in React Native: padding must be a number and not a list of values in a string, backgroundColor is used for the color, and so on.

To illustrate that rule, assume that the CSS padding: "8 16" is not valid, and so background: "#333333".

Even if these are a bit longer to type in, I find it way more explicit than the shortcuts we are used to. Plus, they are always complicated to understand for a beginner.

After a couple of hours, I had definitely adopted this new way of writing CSS.

dp units and shortcuts

Scalable Vector Graphics

If SVG is used a lot on the web, it is not natively supported in React Native. We need to use it with an external package: react-native-svg.

However, the package is made to be used exactly like on the web with just a little difference: the first uppercase character.

Simple SVG in React Native

Overflow

If you want a scrollable View, you need to switch to the ScrollView component. It acts the same but has a scrollbar built in.

Since the component has a vertical scroll by default, you can use the horizontal attribute to make it scroll on the x-axis.

For performance reasons, you can also use theFlatList component, which is a bit more complicated to use, but it will make your long lists scroll fast. If it is something you need, I encourage you to look at the official documentation.

Tips and Tricks

Touchable components are applied to a single element

If you get the error Error: React.Children.only expected to receive a single React element child, then you just need to wrap your elements in a new View component.

It seems pretty obvious what to do, but it can be a bit disturbing when coming from the web: When using Touchable* components, you need to have a single layout item.

Line breaks in `Text`

On the web, new lines are made with <br />, but since native is not DOM, you can simply use {"\n"} in your Text components or directly in a string (e.g. <Text>{"Hello\nworld!"}</Text>).

Views in Text

You cannot have View elements in Text elements. This throws the following error: Cannot add a child that doesn't have a YogaNode to a parent without a measure function!.

It might make your tree a bit more complex with some code duplication, but you should always find a way to avoid this message.

Conclusion

Even though React Native is based on React, there are plenty of differences. On one hand, we use React on the web and use the DOM API. On the other hand, we use the native layouts for Android, iOS, and others. But it is still very easy to get into. Do not hesitate to give it a try!

An Opinionated Way to Structure React Apps

Bruno Sabot — Tue, 05 May 2020 02:34:22 +0000

Photo by Dayne Topkin on Unsplash.

When we first develop a React app, we can just put every component in a folder and it works. But when it comes to larger projects, it might be difficult to find our way between files if we keep using React this way.

So how can we handle a bigger project? Dan Abramov has a way. You don’t think this is very helpful? Actually, it is. It’s the best way to find the perfect architecture that will fit your needs, but at a cost of many iterations in folder creation and removal.

Today, I’m introducing the result of my many moves, making a base structure for people seeking a way to improve their own.

Initial Considerations

Before we start, I’d like to point out that I’m presenting an opinionated way to structure an app. In some projects, I had to do things differently because the app’s core concept was too different. It might also be the case for you.

Also, there are several ideas I’d like to introduce so you will better understand the why.

First of all, I use atomic design. Some components are only visual. Basically, it concerns every component that will end up in my Storybook. I call them ui components. Atomic design also brings template components.

Some other components are given a specific behavior to a form field, like an enhanced form field that gives a validation pattern to a browser default form field. They are the organisms within atomic design.

Finally, I’m using the React Context API instead of redux, as I explained in one of my previous posts. I create top-level components that I call providers.

Getting Started With the Root Folder

Working with create-react-app, the root folder of my application is the src folder in which I place several folders:

App — The folder where the main component is placed containing global providers and main routing.
components — Where every React component of the application belongs.
gql — In which I can find every piece of a GraphQL request I can make in my application.
libs — This is a bit of a mess, but it contains everything else. It is generally composed of fewer than ten files, so I never had to split them better.

This is the better ratio I found between simplicity and code splitting for the base structure. Since React is a component framework, you can easily imagine that the components folder will be a bit more complex.

I will not explain in detail the three other folders. You can have a look at the sample tree at the bottom of this post to find out more about the kind of files placed in there.

The Components Folder

Here we are: the main part of the application. This one is composed of many more subfolders. Keep in mind that if you copy this structure, you do not need to absolutely use them all if it doesn’t make sense in your project. For example, the ui folder doesn’t make sense in a Material-UI application.

hooks— Where I place a good amount of the hooks I use in my app. I have a lot of them to embrace the power of reusability, so I also create subfolders to illustrate the job they belong to. For example, I often have a useInterval hook to handle cyclic jobs. I also place in there a useUser hook that gives me the current connected user information.
modals — This regroups every modal in my project. I used to place them elsewhere, but I actually found that I often use them many times in the application, and they are quite numerous. By having their own folder, it became simpler for me to work on them.
organisms — The folder where I place the functional components I spoke about earlier. It can be split into subfolders if there are too many of them, which happens a lot.
providers — Components that contain global data or feature logic. To find out more about what a provider looks like, I invite you to take a look at a previous post where I replace redux with them.
svg — The home of every icon used in the application since create-react-app can include them natively. You might have a designer, but in case you don’t, I really love the Material Design Iconset, where I can always find the perfect icon for my apps.
templates — In which I have the page layouts of my atomic design application. It’s not the richest folder of the app, but taking into consideration what the layouts are for, they are better isolated.
ui — Where the atoms and molecules of my application are. This is one of the heaviest folders in the application, so it is split up by domain subfolders.
pages — This corresponds to the pages defined in my application. This is the most complex folder because it is recursive. We’ll talk about it in a specific chapter right after this one.

This is a lot of folders, right? The most difficult part of my perfect folder structure was to keep it simple (KISS!), but without mixing apples and oranges. This is why I placed atoms and molecules of atomic design in the same folder, but I also often have domain subfolders.

The Pages Subfolder

Before coming to the folder structure, let’s talk about URLs. I found that cutting every URL in my app in two sections of the path (the domain and the page) is the simpler and more robust way to build the page path.

I might also have additional parameters to show a specific detail page. These ones are not limited in amount.

For example, I have these pages:

/user/login
/user/account
/todo/list
/todo/details/123
…

But I do not have these ones:

/user will redirect to /user/dashboard, for example.
/ will probably also redirect to /user/dashboard.

These URLs give you a hint on how structured the folders will be. Without surprise, we have a first folder that is the domain and a second one that is the page.

As I mentioned earlier, the page folder is also recursive. Why? Simply because sometimes the content is not global to the app. A useTodoList hook is only used in the /todo/list page and the TodoItem component also.

So inside a page folder, you can also find a components folder with every folder defined earlier but pages.

Putting It All Together

That was a lot of words to define the overall structure. But an example is often better than words, so here it is:

src  
 |- App  
 | |- App.jsx  
 |- components  
 | |- hooks  
 | | |- useInterval.jsx  
 | |- modals  
 | | |- AddTodoModal.jsx  
 | |- organisms  
 | | |- PrivateRoute.jsx  
 | | |- forms  
 | | | |- TextInput.jsx  
 | |- pages  
 | | |- todo  
 | | | |- list  
 | | | | |- TodoList.jsx  
 | | | | |- components  
 | | | | | |- hooks  
 | | | | | | |- useTodoList.jsx  
 | | | | | |- organisms  
 | | | | | | |- TodoItem.jsx  
 | | |- user  
 | | | |- login  
 | | | | |- UserLogin.jsx  
 | |- providers  
 | | |- UserProvider.jsx  
 | | |- TodoProvider.jsx  
 | |- svg  
 | | |- check.svg  
 | |- templates  
 | | |- LoggedPage.jsx  
 | | |- LoginPage.jsx  
 | |- ui  
 | | |- alert  
 | | | |- Alert.jsx  
 | | | |- Alert.module.css  
 | | | |- Alert.stories.jsx  
 | | | |- Alert.test.js  
 | | |- button  
 | | | |- Button.jsx  
 | | | |- Button.module.css  
 | | | |- Button.stories.jsx  
 | | | |- Button.test.jsx  
 |- gql  
 | |- todo  
 | | |- TodoCreate.gql  
 | | |- TodoDelete.gql  
 |- libs  
 |- preload.js

Even if the example is pretty simple, it contains everything to illustrate the previous explanations.

Conclusion

Even if this folder structure for React is a work of many years on how to organize a project, it might not suit every need. However, as of today, it fits all my projects’ needs and makes me particularly efficient during my work.

If you encounter some issues of your own, I would be glad to hear from you about how this proposal is bringing you trouble. But remember, the right folder structure is not necessarily mine but the one that fits your project. After all:

“Move files around until it feels right.” — Dan Abramov

How to Debug a React Context API App

Bruno Sabot — Tue, 17 Mar 2020 17:45:56 +0000

Photo by Barn Images on Unsplash.

Some time ago, I shared how I dropped Redux for the Context API when I’m creating a React application. The post got some great feedback, but I also had some people saying that it’s pretty hard to debug compared to the Redux DevTools and asking me if there is an easy method to do it.

The answer is yes. Actually, if there is something awesome about Redux, it’s the DevTools. The great part is we can link them easily with our Redux-free app — and with everything we like, really.

Let’s now see how it works!

Redux DevTools API

When we have Redux DevTools installed, the extension automatically injects a special object (__REDUX_DEVTOOLS_EXTENSION__) in the window. A weird name for sure, but it prevents any conflicts with your existing code.

And that’s where everything starts: This object gives us everything we need — connect and disconnect methods that link our code with the Redux DevTools.

However, if you just try to run these functions, you will still see nothing in the DevTools because we first need to initiate the session.

To do so, we take advantage of the object that returns the connect method. It possesses an init method that launches the DevTools session.

Basically, it looks like this:

Simple Redux DevTools connection.

Even if this works, you will still see nothing in the DevTools because the session is closed as soon as we create it.

A DevTools Provider

To make the session permanent when you are developing your app, you will need a Provider, which looks like this:

A basic Redux DevTools Provider.

If you add this piece of code at the very top of your application, you will see the startup session in the Redux DevTools that you can identify with the @@INIT event that pops in.

The INIT event that pops in.

Sending Events to the DevTools

Now that we are able to start a session, the next step is to send an event to the DevTools, which is as simple as we can imagine: The devTools object that we have created also provides a send method, which takes a name and some data to illustrate the change.

Basically, it looks like this:

Simple Redux DevTools connection with a sent event.

Putting Everything Together

We now have everything to make it work. We will just add a few things in our Provider to make it truly usable:

A hook to allow simple event sending to the DevTools session.
A Context API so the DevTools can be available in the whole project.
A simple sending method with default name values.

The usage is now pretty simple in the application. We need to call the useReduxDevtools hook we created in the Provider file to wrap the initial method into a high-order function that handles the debug session:

Look how useReduxDevtools is called on line 10.

And voilà, our Context API inside Redux DevTools!

Now when we are calling the setTheme method, it pops in the DevTools so you can inspect what is going on!

Conclusion

It is very easy to connect any app to the Redux DevTools, and you can start debugging any app without Redux right now.

Also, let’s revisit something I said in my previous post about the Context API: It’s an easy API to use and can replace Redux in many cases, but keep in mind that Redux is much larger than the Context API. Choose wisely if you need to make the switch.

DEV Community: Bruno Sabot

Crafting My Perfect Home Assistant Dashboard

Introducing the Plugin Powerhouse

Bubble Card

Card Mod

Decluttering Card

Config Template Card

Lovelace Layout Card

Bringing it to Life: My Customization Journey

Alarm

AQI

Covers

Separator

Thermostat

Weather

Weather forecast

Is that it?

Mastering Time: Using Fake Timers with Vitest

Why Fake Timers?

Getting Started with Fake Timers

Basic Usage

Advanced Usage

Conclusion

Improve Performances With Dynamic “Content-Visibility”

Initial Considerations

The Content-Visibility CSS Property

How Does It Work?

Setting the Block Size

But…

The IntersectionObserver JavaScript object

How Does It Work?

Deep Dive Into the Callback Method

Handle Blocks With Dynamic Heights

Handling Responsiveness

Conclusion

React Hook

Vue Composable

JavaScript Spread and Rest Operators: When To, Why To, and How to Use Them

Assignment shortcuts

The rest operator

Why do we need the rest operator?

The spread operator

When do we need the spread operator

Combining rest and spread and more

Conclusion

Loading Gists in a NextJS Application

Introduction

Initial Situation: Loading Markdown in a NextJS Page

What Does The Markdown File Looks Like

Loading The Markdown File

Adding The Loaded Data Inside a NextJS Route

Display the blog post in the page

Creating a Remark plugin

The AST transformation

Fetching a Gist From Github

Visiting And Updating The AST

Using a Custom Rendering Component

Keep The Performances As Good As Possible

Conclusion

Fetching Data With React

Introduction

Basic Data Fetch

Using the JavaScript Fetch Method

Separating Concerns

Adding Loading and Error States

Factorize to Hooks

Do We Really Need the Separation Concern in a Component?

Using a Data Fetching Library

SWR

React Query

Conclusion

Core Web Vitals Dashboard On Google Analytics

Including the tracking code

Viewing data directly in Google Analytics

Conclusion

Build an Easy Popup System With React

Concerns About Existing Systems

What Are We Building

Requirements

The modal components

The `IntersectionObserver` JavaScript object

Line breaks in `Text`