Tomas Pustelnik

What every JavaScript developer should know about HTML and CSS

Mon, 10 Feb 2020 00:00:00 +0000

Writing web apps in React or other JS frameworks doesn’t mean you don’t need to have a solid foundation of HTML and CSS. While you may be fine most of the time with basic knowledge, having more in-depth knowledge will help you create a much more accessible, robust and maintainable code. And in the end, deliver better products to your users.

I have put together several concepts and practices I believe every front-end developer should know (not just JavaScript developers, but I often see the biggest lack of knowledge there).

To avoid the article to be too long, I introduce only the necessary basics in each area and provide links to more resources on the web if you wish to learn more. There are many great articles about each of the topics mentioned here, but I found it useful to have it in one place like this.

So let’s get started.

Use HTML elements with correct semantics

One of the best (and probably easiest) things you can do for accessibility of your web is to use semantic markup. Yet often developers just tend to use divs and spans. But HTML is more than just that. It stands for Hyper Text Markup Language and the markup word is important. HTML is used to give a structure and meaning to the document. That can hardly be achieved with the bunch of divs.

I don’t say you should stop using divs and spans. I use them a lot myself. But they have no semantical meaning. They are just containers to help you style your web page and section the content inside other HTML tags which do have meaning. You have probably heard and used heading elements (h1, h2 and so on), nav, header, footer and main. Those are probably the most common semantic elements (added in HTML5). Using these is a good start. But there is much more. Do you know there are elements for abbreviations or keyboard input? Just check element reference on MDN to get the full list with explanations (I strongly suggest to read it).

And why exactly is it important to use semantic markup? As I mentioned at the beginning of this section, accessibility is the main reason. People using screen readers can easily navigate using headings or so-called landmarks (you can think of a landmark as an important part of the web page). Landmark is created by using semantic HTML like <header>, <main>, <article> or <nav>. The second reason is that screen readers also announces what landmark is a user on (like main content or navigation).

Another way how to create a landmark is to use role attribute on HTML element eg. <ul role="navigation">. This is useful when creating some more advanced UI components (like menu button with dropdown etc.). But I strongly recommend using existing HTML tags whenever possible.

Semantic markup provides us with the context of what we are looking at. But it can also help machines (search engines or some reading devices) understand the structure of the document and display it accordingly. I recommend reading this great article from Bruce Lawson about the value of semantic markup.

Here is some advice on how to start with semantic markup:

Use h tags of proper level (don’t skip heading levels) to create a correct outline of the document.
Start using nav, header, footer, main and article.
Check other HTML tags to see what else you can use and try to slowly incorporate them into your toolbelt.
Read more about this topic, for example article on Smashing Magazine about section vs article or article on CSS-tricks about structuring document (be sure to read the comments in this one as well, there is a lot of good info).

Learn how to use form elements

Forms are often one of the most complex parts of the web app – a lot of states and moving parts. For a great UX, it is essential that all these parts work smoothly and as a user expects. Nothing kills a good impression from your web like a form you can’t submit with Enter.

Wrap forms in `<form>` element

It seems obvious, right? But I have seen forms without it. Especially in today’s world of JS frameworks, it’s easy to create a form-like component without it. But unless it’s something simple as a standalone button with some specific functionality (like a toggle for menu) you should always use <form> element. Your users will thank you. First, it tells screen readers that this is a form (we already talk about semantic markup). Second, it gives you standard UX behavior out of the box – submitting the form on pressing Enter, ability to submit or reset form via a button and listen on form submit event to process submission.

Always use inputs with labels

Inputs have to have a label, it tells the users what the input is for. Not a placeholder or some <span> but a <label> element. Placeholder is only a visual hint, it disappears once we enter something into the input field and some screen readers can ignore them (for a more detailed explanation why you should use labels instead of placeholder attribute see this great summary from Joshua Winn). So use <label> instead and connect it to the input field with for attribute like this:

<label for="username">Name</label>
<input type="text" id="username" />

<!--
 or nest the input into the label,
 that way id is not required, if you nest only one input :-)
-->
<label>
  <span>Name</span>
  <input type="text" id="surname" />
</label>

<!-- or -->
<label for="address">
  <span>Address</span>
  <input type="text" id="address" />
</label>

This way when you click on a label a connected input field will get focus. This is extremely important for radio buttons and checkboxes since <label> will increase the touch area of the radio/checkbox and make them easier to select on mobile devices.

If you can’t use <label> for some reasons you may use aria-label or aria-labelledby attributes as an alternative. But native <label> element should be always your first candidate.

Use type attribute on a button element

Since you are using <form> element for your forms you want to always set type attribute on your buttons. There are three possible values - submit, reset and button. Submit and reset values are useful only nested in <form> element (first submits the form, the second one will clear the input fields in the form). Type button is a generic type for all other buttons (menu toggles, showing/closing modals, etc.).

And why should you always specify it? Because button elements without type attribute specified get the type set to submit by default. And it can lead to bugs when in the <form> element since you can submit a form unintentionally.

Make things accessible

Accessibility (a11y for short) is hard, especially in single-page applications it can be a daunting task. I struggle with it sometimes as well. But we should still try to make our products as much accessible as possible. While there is a lot to cover in terms of a11y (enough for a separate blog post or more likely a book). Most common issues I encounter often are:

sites aren’t using correct semantic markup (we already covered that)
and they are hard to use without a mouse

There are a few things you can do to mitigate those issues.

Always provide styles for focused interactive elements

All interactive elements have default browser styles for focus state (usually in the form of outline). Users browsing the web using a keyboard use it to see where they are on the page. Remove it and the user does not see any feedback on his position (what element he can click on). It’s like driving in the dark night without lights turned on. You have no idea where you are and what will happen if you turn the wheel.

Removing focus ring and failing to provide an alternative to the users is the same as driving a car in the dark night without lights turned on. You have no idea where you are and what will happen if you turn the wheel.

If you absolutely have to remove the default one, replace it with another visual hint (based on your design system) when an element is focused. But never remove it entirely.

Use correct elements for interactions in the app

We are back to semantic HTML. Native interactive elements like buttons and inputs can be controlled by a keyboard and focused out of the box. No JS or special attributes required. If you need a link, use <a> not a <div> with some javascript dark magic.

Of course, you can make <div> to behave and look like a button (even for screen readers). In all my career, I have to do it only once due to some conflicts with drag and drop in React (library did not like a button to be draggable). It was ugly, and it took some time to make it accessible. I would prefer to use the native <button> instead.

And one last thing. Use <a> tag when navigating to a different page, use <button> for everything else. That means no <a> tag with JS opening a side menu or <button> using JS to navigate to a different page.

Don’t nest buttons and links

How would you like to have an Esc key placed on top of your Enter? Your press one and both of them are pressed. That would be super annoying, right? That’s exactly what you do when you nest buttons and anchor links into each other. It’s not semantically correct and it’s confusing for screen reader users. Not to mentioned it can create some weird behavior in the app.

How to do some more complex UI components like a clickable card with additional buttons inside of it? You will have to use a little bit of CSS and absolute positioning or wrap only some part of the component (like heading) into <a> tag, not the entire card. For more tips check this article on CSS-tricks.

Box model and sizes

Every element on the web page is a box. You can skew it, make it round, but for a browser, it will always be a box. I have met a few developers who didn’t know how exactly is the size and position of these boxes determined. That caused them some issues when they tried to style those elements. I won’t go into too much detail there. Plenty of resources about this topic already exist. You may check the article about the box-model on MDN or dive into the spec.

I want to go through a few basic things to keep in mind.

Box-sizing CSS property

Box-sizing property controls how the final size of the HTML element will be calculated. By default it values is content-box which means that width and height attributes (and their min and max variants) affect only a content area of the element (blue part in the picture below).

If you add padding or border to the element, it will increase its size. That may result in the element overflowing from its container and can be a cause of some confusion for people who do not know about this (especially if they use some CSS reset without knowing what it does exactly). To see the difference between box-sizing set to content-box and border-box have a look at the codepen below.

See the Pen Box sizing comparison by Tomas Pustelnik (@Pustelto) on CodePen.

To make width and height properties affect the padding and border of the element as well set value of box-sizing to border-box. Here is a suggested way of doing this.

/* :root stands for html, but it has higher specificity (same as class) */
:root {
  box-sizing: border-box;
}

/*
 This way it's easier to override the box-sizing if needed
 (children will inherit it from parent)
*/
*,
*:before,
*:after {
  box-sizing: inherit;
}

Inline elements have extra space in between them

Again not very well known feature of CSS - if you have several inline or inline-block elements next to each other, you get small space between them. If you dig deeper you will found out that CSS is not the culprit.

It’s because space between inline elements in the code is treated as space (space between words is a good thing most of the time). However, in some cases, it’s not what you want. The easiest way of getting rid of it these days is to set display: flex on the container. For more detailed info I suggest this article on CSS tricks.

Margin collapsing

If you already have experience building websites, you have probably encountered this. You work on the page styles, adding margin-bottom to your article heading and then some margin-top to the main image just below it. But the white space between them is not the sum of both margins. It is only the size of the bigger one. That’s margin collapsing.

When two vertical margins meet, they will collapse. This happens between sibling elements and sometimes between parent and child (if they aren’t separated by border, padding, or if there is no formating context on parent element).

You may play with the codepen below to see how margin collapsing changes with different CSS properties.

See the Pen Margin collapsing by Tomas Pustelnik (@Pustelto) on CodePen.

For a more detailed explanation, do check the MDN page about margin collapsing.

Use appropriate sizing units

TLDR: Don’t use pixels.

CSS offers a variety of different length units. Probably the most well-known unit is a pixel (px). My advice is – don’t use it. The main reason is accessibility. You can change the default font size in the browser settings, but if you define font sizes on your web in pixels this will not work. The text will have the same size.

Instead of pixels, it’s best practice to use rem (rem stand for root em). More precisely, use relative units as much as possible (viewport units, percentage or size elements using flexbox and grid properties) and for fixed sizes (margins, font-size, icons…), use rem.

rem works similarly to em unit except its size is calculated from the font-size of the root element (<html>). Unlike with em, there isn’t a problem with the multiplication of the sizes – if you nest elements inside each other, font-sizes with em units will infer it’s size from the parent. See the codepen below for an example (I have shamelessly copied the code from Codedrops CSS reference)

See the Pen Em units cascade by Tomas Pustelnik (@Pustelto) on CodePen.

If we are talking about font sizes, we have to mention line-height property as well. Always define it as a unitless number (eg. 1.5). This way browser will calculate line-height as a multiple of the font-size. Again this is important for accessibility to ensure enlarged texts are readable. For a detailed explanation of this (and with examples) check Kathleen McMahon’s article.

Stacking context

The stacking context controls how elements on the page are layered on the z-axis. From the user’s perspective – how are they layered and how they overlay each other. Think of modal dialog with semi-transparent overlay covering your entire page.

Sometimes you may encounter an issue where the element with high z-index is covered by another element with smaller z-index (even though it should be above everything else). This may be confusing for people without the idea of what and how stacking context works.

There isn’t usually one but several stacking contexts at the same time. And element with stacking context works like a container for its children with the z-index property. z-index has an effect only inside of this stacking context, but not outside. Which in practice means that element with z-index value of 999 can be cover with another element with z-index value 1. Check the codepen below for a concrete example.

See the Pen Stacking context example by Tomas Pustelnik (@Pustelto) on CodePen.

What you usually want to do in such a case is to add or update z-index on the element which creates stacking context (header and main in the example codepen). Check this article on MDN if you want to see when exactly is stacking context created.

CSS specificity

Let’s have a look at the code bellow.

<style>
  .red.blue {
    color: magenta;
  }
  p.blue {
    color: blue;
  }
</style>
<p class="red blue">What color do I have?</p>

What color will the text have? If you answered magenta, you are correct, and probably know what CSS specificity is. If you guess it incorrectly, or perhaps you are not sure why does it have magenta color and not blue, read on.

Browsers apply styles in the order they appear in the source code. So later styles overwrite styles that appeared early in the document. That’s how web browsers decide which styles to use in case of conflicts. This works for duplicate properties in declaration block (this way we can provide fallbacks for older browsers) and for the declaration blocks as well if we have more selectors targeting the same element.

However, with multiple selectors targeting one element, there is another factor in the game and that is CSS specificity. Which brings us back to the example at the beginning of this section. The paragraph will have magenta color because the first selector (.red.blue) is more specific than the second selector (p.blue). You can think of specificity as the importance of given CSS rule. Bigger specificity means bigger importance and thus such rule overwrite other rules which are less specific.

You can see in the image below how is the specificity calculated.

When you compare the specificity of two selectors, the higher one wins and its rules will be applied. In our case .red.blue has specificity 0-2-0 (we have two classes there) and the p.blue has 0-1-1 (one class and one element selector).

You can also see that id selector beats all other selectors (classes, elements, etc.) and it can be overwritten only by another id selector, inline styles or !important flag. To keep your stylesheets maintainable, try to keep specificity as low as possible. Preferably use only classes to style elements and avoid id selectors at all costs. Beating rules with high specificity with even higher specificity will lead to a circle of specificity wars that is hard to broke from without some major refactoring.

Last info you need to know is how inline styles and !important work with specificity. Inline styles beat any selector (even id), but they are hard to override because of that. !important beats everything and only another property with a !important flag can override it. So be extra careful when using it. A good use case for it is in utility classes which do only one single thing and they should take effect no matter what or when overriding some third-party styles.

Again if you want to learn more about it, I suggest articles on MDN or CSS tricks.

Conclusion

And that’s it. Congratulations on reading this far, I hope you like it and find it useful. HTML and CSS may seem trivial at first and not worthy of your time. But as you have seen there are few concepts that can help you write better code, be more efficient in it and have the potential to save you or your colleagues a ton of time trying to fix poorly written front-end.

Don't ignore Fieldset and Legend HTML elements

Mon, 23 Mar 2020 00:00:00 +0000

Creating accessible forms (especially more complex ones) may be difficult. There are many moving parts and different kinds of inputs. And we often have to use JavaScript to make the form accessible for all (check this great summary from Dave Rupert to see what native HTML inputs are not accessible). But on the other hand, there are HTML tags which can help us a lot with structuring our form and make a great deal of work to make it more accessible. There is for example a <datalist> element which got some spotlight recently. Other useful elements are <fieldset> and <legend>. Today I want to talk about those two.

Maybe you have heard about them, but a quick introduction won’t hurt. This is what specification says:

The <fieldset> element represents a set of form controls optionally grouped under a common name.

The name of the group is given by the first <legend> element that is a child of the <fieldset> element, if any. The remainder of the descendants form the group.

A typical example could be a billing and delivery addresses or a bunch of checkboxes to select your interests. Those inputs create a logical group and for better accessibility, you should enclose the in the fieldset. Legend serves as heading for the fieldset and to make fieldset useful, you have to use it.

What are they good for?

Now let’s have a look at why using <fieldset> and <legend> is a good idea. Nothing will change for normal users using their sight and mouse to navigate on the screen. But it’s a big help for users with a screen reader. The screen reader will announce the fieldset as a group of elements together with its name defined in <legend>. This is great as it gives users additional context about the upcoming fields (is it delivery or billing address). Some screen readers (like JAWS) will even read the legend before each input in the group.

You may argue that you can simply add some text before the inputs (like heading) and give the user the same information. That’s not entirely true. First, it may confuse the user as there is no clear connection between the group of form elements and the text you provided. Second, some screen readers have a special mode to work with the forms and in this mode, non-form elements may be ignored (so your heading will not work).

Fieldset has one more great benefit. You can simply put the disabled attribute on it and it will disable all the input fields in it. So no extra delivery address? Sure just put one disabled there and you are done. Isn’t that great? ~~And by the way, you can use this trick on the <form> element itself to disable the entire form~~ (EDIT: This is not a true as I checked based on some comments. disabled does not work on form like this. I’m sorry for confusion.).

Some downsides

As with most things in life, nothing is always perfect.

Not all screen readers will announce the fieldset. Some will ignore it and read only a text contained in a <legend> as a normal text. This also depends on the browser as I have found. For example, VoiceOver (native macOS screen reader) will announce the fieldset correctly in Chrome, but not in Firefox.

Styling of <fieldset> and <legend> also takes a little bit more effort, than using headings or some text element. But that shouldn’t be an excuse for not using them.

Conclusion

Don’t be afraid of fieldset and legend tags. For very little effort, they help you structure your form and give users extra context about the purpose of the form fields. And as front-end developers, we should always aim for a more accessible solution.

Tools & resources I use for front-end development

Mon, 13 Apr 2020 00:00:00 +0000

Front-end development is quite a complex discipline and you will hardly ever need only a browser and code editor (at least for bigger projects). I have decided to post a list of the tools I use for development. I hope this will help others to find some great tools they can use in their workflow.

Basic stuff

Those are the tools I use daily and I couldn’t literary produce much of my work without them.

VS Code - You need to write your code somewhere. My editor of choice is VS Code from Microsoft. It’s free, lightweight (compared to IDEs like WebStorm), has a ton of functionality out of the box and extensions which can give it even more powers.
Browsers - I use Firefox as my default browser, sometimes switching to Chrome for development. But I have installed other browsers for testing as well.
DevDocs - Web app which aggregates documentation from different projects. It can also work in offline mode. This my go-to page when I need to look for some documentation.
Using it mainly for JS and DOM/Browser related stuff. As I really couldn’t find anything similar (easy to search and detailed). You should check it out.
Google - Yes, I google things very often. Bugs, how to do stuff (sometimes pretty basic) or examples and documentations for packages and libraries (if they aren’t on DevDocs).
MDN - Greate resource for any web developer. Part of this site can be accessed via DevDocs mentioned earlier, but some pages are only on MDN.
I use it mainly when I need to check some a11y related stuff as they have there some good articles about the topic.
StackOverflow - Usually get there from Google. If you have some problem, you can probably find a solution there.
Github - When I have some issues with a package or just need to know more about it I dig into the source code or issues. You can find here answers to your problems almost as often as on StackOverflow. I’m personally more successful with Github issues if I have problems related to one package (unless it’s React or something similar hugely popular). And of course, I use it for version control as well.

CSS

CSS-Tricks - You can find a ton of interesting articles and tips on their blog. There is also a Guides section with in-depth articles about certain HTML/CSS and JS concepts. I usually go there if I need to refresh my Grid knowledge. But other guides are great as well, so definitely worth checking it out.
CSS Reference - If I need to refresh some of my CSS knowledge or use some property I do not know/use very often, this is my go-to resource. It contains an in-depth explanation of every CSS property with clear examples so it’s easy to understand and use in your project. Written by excellent Sara Soudain.
Can I Use - A must-have tool if you care about browser support and using cutting edge features responsibly (aka progressive enhancement).

Performance and optimizations tools

SVGOMG - You will rarely get SVG from designer optimized for the web. In such cases, I will use SVGOMG to optimize and minify the SVG. You would be surprised how much of useless stuff you can get rid of. It’s web GUI for SVGO, so if you can get the same results from CLI if you want to.
Shrinkme.app - Web app when I need to quickly optimize images. It supports batch uploads and provides very good results out of the box.
Sqoosh - When I need to squeeze every last drop of performance from images or need to create images in webp format. A lot of options to play with to get the results you need.
You can also resize images and convert them to different formats. It’s fairly cutting edge (it was done as a demo of what modern browsers can do by Google Chrome team) so you have to use Chrome or another Chromium-based browser (Opera, Brave, etc.). It didn’t work properly in Firefox last time I test it.
Icomoon app - My go-to tool when I need to create a custom icon set. You can choose from existing icons (free or paid) or upload your own. Then you can either use that to generate icon font or SVG icon set (which is a better solution these days).
Google Fonts - When I want some custom web fonts, this is usually my first stop. I usually download the files I need and self-host it myself (for better performance). What is great is that you can select only encoding you need and avoid downloading unnecessary characters.
NOTE: You could select encoding on the old Google Fonts page, but I can’t fount it anywhere on their new site. If you know where it is (or if it is there at all), let me know, please.
Glyphhanger - Decreasing file size is one of the best ways how to improve the performance of the website. Web fonts often use many glyphs we do not need so I use Glyphhanger for font subsetting.
You can specify Unicode ranges or characters you want in the font and Glyphanger will create a new font file for you with only specified characters. It can also convert .ttf files to other formats much more suitable for the web. like .woff and .woff2. Take a bit of effort to use it right, but I think it’s an option worth considering when font performance is an issue.
Lighthouse - I test the webpages before releasing them and one of the tools I use most often is Lighthouse audit in Chrome browser. It checks for the most common issues in several areas and gives you score for each area as well as hints on how to improve. It’s great as a first check to see if there are any problems I forgot to address during development.
Font style matcher - If you want to make font swap less noticeable after your custom fonts are loaded you can use this great tool to match the styles of your default and custom fonts.

Accessibility

VoiceOver - default screen reader on macOS. It takes little practice to use it (I found this article about it very useful), but I try to regularly use it in the development process. Thanks to that my usage of aria attributes and screen-reader only text has increased significantly. You would be surprised how very little context and information some ordinary webpage components have for the user depending on a screen reader.
a11y guidelines - I usually try to find some existing solution with good a11y but that is not always possible. In that case, if I need to create some interactive component with accessibility in mind, I will go to this page. You can find a detailed explanation of what, why and how. Together with example codes, you can often copy and reuse with a little effort.
WAI-ARIA specification - I don’t ready specifications very often. But when I do, it’s usually this one. It contains a lot of valuable information about aria roles and attributes and how to use them. I would say this is mandatory reading for anyone who takes a11y seriously

Honorable mentions

And last but not least there is a list of other tools I found useful, but not using them that often.

Responsive breakpoints generator - Manually creating responsive images with a lot of variants is a pain. This is a great tool to lessen that pain.
HTML Arrows - List of special characters together with Unicode code (in different contexts like CSS, JS, plain Unicode) and HTML entity to use them safely on a web. I use it now and then when I want to have good typography.
Char reference - Similar to the tool above, but contains less information. It shows mainly HTML entities, so if that is what you need this may be a better option.
Typography cheatsheet - Explains common typography rules and issues. If you want to improve your typesetting on the web, this is a good starting point.
Modular scale - When I work on a design I usually pick some modular scale using this tool. It helps you create a harmonical vertical rhythm. To learn more about it I recommend reading this article on A List Appart or this recording of Tim Brown talk from Build Conf 2010.
CSS gradient generetor
Smooth shadow generator - When you want to have great looking shadows on your web.
Bezier curve generator - Custom timing function for your animation
Easing functions - Library of different easing functions ready to use in your CSS animations and transitions.
ngrok - I use it when I need to show some of my work running on localhost to someone else or if I need to test on different devices. Sometimes using it with Browserstack when their localhost extension refuses to work.
sharing buttons - This is a jewell if you need simple sharing buttons without all the JS and tracking mess around them.
Unix timestamp converter
CSS to JS converter - This may be handy when you work with CSS-in-JS library and need to convert from CSS to JS or vice versa.
Browser default styles - List of default styles for common browsers.

The end

That’s it. Those are the tools I used for my work and which help me to be productive and provide high-quality work. I hope you will find some of them useful. If yes please let me know on Twitter. Or if you have some other great suggestions I would love to hear about them as well.

What have I learned when releasing Qjub

Fri, 05 Jun 2020 00:00:00 +0000

About two weeks ago, I have finally released Qjub in private beta. It was a great feeling to finally kick it off the door. And a big relief as well. However, getting to that moment was not an easy task. This week I had a little time to reflect on that journey. And I would like to share my experience and the lessons I learned with you.

TLDR - Lessons I have learned

For those who do not have time or do not want to read the entire article:

Steady small progress > occasional big chunks of work - it keeps momentum and eventually may give you more time.
Set fixed deadlines and stick with them as much as you can.
Cut unnecessary things and do not be afraid to release unpolished features or apps.
Releasing is hard - you had to check and prepare so many little things which are often important, that it will take you a huge chunk of your time. Take it into account when planning the initial launch of your project.

Full story

Let’s start with a little background. When I start my current job I had to learn a lot of new stuff and I wanted to get better. So I start building Qjub. To learn in-depth all the new stuff I used in my work and to build something to help myself.

You see, I tend to collect a lot of resources across the web. Web development tips, books I want to read, cooking recipes, and design inspiration. But I had always had those things at different locations. Finding that one thing I was looking for was difficult. None of the products I tried worked for me, so I decided to build my own solution. Building Qjub was like to kill to birds with one stone.

Consistent work on stuff that matters

While Qjub was slowly taking shape, it was still mainly a learning project without any pressure to release it. Somewhere along the way, I decided to go all-in and make Qjub available to everyone as an app. With the eventual prospect of getting some income from it (and ideally building it full time).

At that time I had like a million features I wanted to be there, some more reasonable than the others. But still too much to ever get close to release. I start by splitting the development into several milestones and assigning then a reasonable amount of tasks. Of course, I had to prioritize and make some sort of minimum viable product (aka MVP) to be able to release.

I also mostly work on Qjub during free weekends. But because of children and other activities, those times were rare (sometimes I did not touch code for several months). Inspired by some podcasts and books I was reading I decide to make a change. I have started to work on Qjub each morning before I go to work for 1 hour every day. It may seem like very little time but it gave me an incredible boost in productivity and Qjub started to move forward like never before. I can confirm what many other awesome people say - working in small chunks regularly adds up, builds momentum, and eventually allow you to build much more.

I decide to work on Qjub each morning before I go to work for 1 hour. It may seem like very little time but it gave me an incredible boost in productivity and Qjub started to move forward like never before.

A few months later Qjub was looking good but I still couldn’t see the end of it. I sit down and think really hard about the Qjub. What do I want it to do? What is needed for release and what can wait? This has lead to two thinks. First I drastically cut down the scope of the project for initial release. Second I set a fixed release date.

Because of the fixed date, I had to keep asking what is important and what is not. I cut the scope a few more times during the remaining time to meet the deadline. This forced me to make some hard decisions and compromises. For example, I decided to postpone search functionality and board sharing. Or keep some stuff unpolished, intentionally limiting its scope and capabilities (eg. you can’t insert images to text notes at the moment). I can always make those things later if needed.

There is always some feature you can cut down or limit its scope to meet the deadline and focus on stuff that matters.

Let’s take a closer look at the search feature and my reasoning behind not implementing it at the beginning. My reasoning behind it was that no one will need search functionality at the beginning because there will most likely be very little content. So I can build a search later before anyone needs it.

This is the approach I try to use for everything in Qjub since then. Do I need this feature now? How much value does it give me? How much effort does it cost me? Building the Qjub myself, I have to think hard about my time and how to use it efficiently.

Releasing it

Finally, my release day approach, and I found out I’m still not ready for release. Yeah, I missed my fixed deadline, even when I tried my best and have huge support from my wife, who took care of our home and children herself so I could focus on Qjub. That was disappointing for me. But I pushed hard and finally make release two weeks later. Turns our releasing an app is more difficult than building it (at least for me). There are tons of small things to check that you can easily spend another week with just that.

So when you decide to release your next big thing, take into account that the release takes some time as well.

Moving forward

The release of the Qjub is just a start. I plan to work on it to better suit my needs and keep my information organized and easily reachable. I have already thought about my next steps and release the public roadmap. I also plan to write more about my journey on this blog.

So stay tuned and if you found Qjub interesting give it a shot. Go to Qjub homepage and request access to the private beta. I will appreciate any feedback and suggestions.

Optimizing CSS for faster page loads

Sun, 02 Aug 2020 00:00:00 +0000

Not long ago I decided to improve the loading times of my website. It already loads pretty fast, but I knew there was still room for improvement and one of them was CSS loading. I will walk you through the process and show you how you can improve your load times as well.

Why loading time matters?

Because Time is money. That proverb is especially true for webpage load times. Your page load time has a direct impact on your profit. People are more likely to buy something on a fast e-shop than on the slow one. According to study Milliseconds make millions improvement by 0.1s on mobile site increased conversions by 10.1% and order value by 1.9% on Travel sites. That can be a lot of money.

So if you want to build a profitable business, you shouldn’t underestimate your page load times.

How does CSS affect load times

To see how CSS affects the load time of a webpage we first have to know how the browser converts an HTML document into a functional webpage.

First, it has to download an HTML document and parse it to create DOM (Document Object Model). Any time it encounters any external resource (CSS, JS, images, etc.) it will assign it a download priority and initiate its download. Priorities are important because some resources are critical to render a page (eg. main stylesheet and JS files) while others may be less important (like images or stylesheets for other media types).

In the case of CSS, this priority is usually high because stylesheets are necessary to create CSSOM (CSS Object Model). To render a webpage browser has to construct both DOM and CSSOM. Without those browser will not render any pixels on the screen. The reason for this is that styles define the look of the page and rendering page first without them would be a waste of processing powers and bad user experience. Only when the browser has both DOM and CSSOM available it can create render tree by combining them and start rendering the screen. In short no CSS downloaded, no page rendered.

As you can see CSS has a huge impact on the load time of your webpage. There are two basic areas affecting webpage load time when we talk about CSS:

CSS file size and the total amount of CSS on the page (number of files). Too large CSS files will take a longer time to download and thus the entire page will take much more time to render (it has to wait for that big CSS to download first).
When and how we initiate and download our CSS. You want to download your styles as soon as possible.

Let’s see in detail how we can improve those.

Limit size of your stylesheet

TLDR: Configure your tools correctly to use modern code whenever possible.

If you want to faster load times, making your CSS files smaller is a good idea. These days it’s pretty common to use some tool to modify the CSS on build time (either post processor or PostCSS) to provide fallbacks for older browsers or some other enhancements.

I would suggest checking the result code for unnecessary bloat. Especially if you are using PostCSS with multiple plugins. In my case, I had CSS with generated fallbacks for CSS variables and with prefixes for older flexbox syntax. That may seem like a trivial issue with very little effect, but resulting savings were around 3 kB for small stylesheet like mine. I think that is a great improvement for very little work. And for large CSS it has the potential to have an even bigger impact.

old index.css:  12.5kB (without GZip)
new index.css:   9.2kB (without GZip, ~26.4% smaller)

All I had to do was to update a browserslist config which is used by Autoprefixer and other similar tools to target generated code for specific browser versions. I have updated my PostCSS config a bit as well. (I also added the plugin to concatenate media queries together to save some extra space). See the PostCSS config in the source code and my browserslist definition if you want to see my exact setup.

Use critical CSS

So we shrank our CSS file, but we still need to download it. We can speed up the webpage load time by reducing network requests. And best network requests are no requests at all. We can inline our styles directly into the HTML to avoid the need for downloading any external stylesheets and thus saving some time.

Of course, including an entire 9kb stylesheet (or large for bigger projects) on every page is not very effective. So we will include only the styles necessary to render the part of the page above the fold and lazy-load the rest of the styles. That way we can still leverage browser caching for other pages and make our webpage load faster. Since we include styles that are critical for page rendering this technique is called Critical CSS.

Luckily you don’t have to decide what styles should be included in the HTML. Some tools will do it for you, like Critical from Addy Osmani. Please keep in mind this technique is about compromises. You need to find the right balance between what to include and the size of the CSS since this technique will save you one request when loading page but it also makes each page bigger (and thus makes it longer to download). So you want to experiment with this and measure the results to find the best setup for your site.

Lazy-load stylesheets

Since we use Critical CSS we want to lazy-load our stylesheets to avoid blocking the render of the page. Unless you need to support some old browsers, modern solution these days is using normal link tag you use for stylesheets but with different media type and a little bit of JS. This clever little trick is fully described in the Filament Group blog post. Below you can see the snippet for lazy-loading CSS from the post, but I suggest reading the entire thing.

<link rel="stylesheet" href="/path/to/my.css" media="print" onload="this.media='all'">

You may want to include fallback when JS is disabled. That way your styles will load normally and you will avoid unstyled content which would badly affect user experience.

<link rel="stylesheet" href="/path/to/my.css" media="print" onload="this.media='all'">
<noscript>
  <link rel="stylesheet" href="/path/to/my.css" media="screen">
</noscript>

In the waterfall diagrams below you can see that page with critical CSS starts rendering right away (violet portion of the graph in Browser main thread row) and is interactive much sooner compared to the old version where CSS file has to be downloaded first.

Waterfall chart for projects page without critical CSS.

Waterfall chart for projects page with critical CSS.

Use code-splitting for your stylesheets

We have CSS with properties we need for modern browsers and we use critical CSS and lazy-load the rest. But we can probably decrease our file size a bit more. In Chrome dev tools there is a tool called Coverage. It can show you what portion of CSS and JS files is used on the current page. Open dev tools and press Ctrl+Shift+p to open a command pallet and type Coverage. Select Show coverage option to show the panel. Now reload the page.

I had almost 50% of my CSS code unused on the page. When we check another page we get even more – almost 54% of unused CSS. That’s a lot of unnecessary code. And this number can be even bigger on large legacy apps.

When using JS we often use code-splitting to create multiple smaller files (bundles). We download those bundles when needed them instead of fetching one large JS bundle on page load. We can use a similar approach for CSS as well. We can split our CSS in three different ways.

Split CSS based on media queries

In this approach, you split your big CSS into smaller stylesheets based on your media queries (PostCSS have plugin for that) and reference those stylesheets in your HTML.

<link rel="stylesheet" href="index.css" media="all" />
<link rel="stylesheet" href="mobile.css" media="(max-width:44.9375rem)" />
<link rel="stylesheet" href="table.css" media="(min-width: 45rem)" />

Be aware that this approach doesn’t make much sense when using Critical CSS and lazy-loading of the stylesheet. The browser will download all stylesheets no matter what media query is used. It will only use media attribute to prioritize the downloads. So basically it will download CSS with a high priority for active media query and lazy-load the rest of the stylesheets.

Page based code-splitting

Another approach is to use separate CSS for each page. As we have seen above there is a lot of unused styles for different pages. It would be great if we could remove those unused styles and keep only what is necessary for a given page. This is what I choose to do. Sadly I couldn’t find any tool to do this — take one large CSS file and generate a smaller bundle for each page based on its content.

Sounds fairly simple so I decided to give it a shot and build a node script which can do this kind of thing. It’s called CSS Split and it works great for sites built using static site generator (like Eleventy which I use for my site). It uses PurgeCSS to remove unused styles so it should work on other non-HTML files as well (based on their documentation). I didn’t test it for anything else than HTML so when using it this way, be sure to double-check the results.

Using this technique I was able to reduce the file size of requested CSS by almost 50%. Below are some stats after implementing Critical CSS and page based code-splitting:

single index.css for all pages:      9.2kB (without GZip)
CSS file for homepage:               5.4kB (without GZip)
CSS file for projects:               4.4kB (without GZip)

You can see that there are still some unused bytes. That’s ok as Coverage doesn’t include hover or focus states or queries. It is unlikely that you will ever get unused bytes to 0.

Component based code-splitting

I’ve got this tip from Harry Roberts. We can also split CSS on the component basis and only load progressively CSS for components we use on the page (footer, header, article, etc.). You can read more about this neat trick in Harry’s article. This technique I’m talking about is described in the last section of the article. But read the entire article, it’s full of great info about improving CSS network performance I don’t cover here (couldn’t write it better anyway).

I still didn’t test this technique to see how well it will work compared to my current setup, but it’s on my To-do list. So stay tuned for some future article.

Summary

Even though my site is fairly simple and doesn’t have too much room for improvements, by using the techniques mentioned there I was able to speed up the initial load of my webpage and lower the total size of assets. You can use the same process for any webpage to improve it’s loading performance (probably with better results for larger projects).

Below you can see some final results after the updates. Graphs show what percentage of the page was rendered at what time. Those tests were run on a slow 3G connection, that’s why it takes so long to load the page.

Homepage – final comparison

Projects page – final comparison

Single article – final comparison

What I read to stay up-to-date

Thu, 17 Sep 2020 00:00:00 +0000

Some time ago I have published a post about tools I use in front-end development, and it had a bigger response than I expected (in a positive manner 😊). And quite a few people ask me how do I stay up-to-date with modern web dev. So I decided to share another list. This time it’s about blogs and other resources I watch and read to keep myself up-to-date with ever-evolving web development.

What is my workflow

I use Feedly to aggregate RSS feeds from the blogs listed below. Many people seem surprised by the fact I use RSS, but honestly, it’s a great way how to keep an eye on many resources without losing time and valuable stuff. Of course, I don’t read every article published on the sites listed below. If I did, I would be reading 24/7, not exactly what I want. So I’m quite picky what to read (but still have a huge buffer).

I usually keep interesting articles unread and dismiss the articles I don’t found relevant to me. Then from time to time, I open a bunch of articles and either read them if I have the time or save them to Pocket and read them later. I usually read them offline when I’m commuting to work. Feedly and Pocket are a great combo and work very well for me and save me a lot of time.

So without any more talking, here is the list of web sites and other resources I keep an eye on (in no particular order):

Blogs

CSS-Tricks - great resource for a front-end related stuff. Often with links to other interesting resources. I would say the main focus is on CSS/HTML related stuff (no surprises), animations, SVGs, etc. But you can found articles on static-site generators, React, Vue, and much more.
Smashing Magazine - a great site full of in-depth articles on design, UX/UI, front-end, and accessibility. I found especially the mix of design and development articles very valuable since I think front-end developers should have some knowledge of design principles as well.
Scotch.io - tutorial site focusing on all web dev (frontend and backend). I think it’s great for junior developers. I don’t personally read their articles too often these days, but I still found it valuable to keep it in my RSS.
SitePoint - another tutorial site, similar to Scotch.io. Covers backend as well. It has a wide range of topics covered and some interesting authors. You can often found articles focusing on best practices. Introductions to new technologies etc.
Codrops - I keep an eye on this site mainly for their Collective section. It is a basically web-based newsletter with the newest and coolest development and design stuff from around the internet. Aside from the Collective, they also post a lot of cool demos. Mainly focusing on high-quality animations and transitions. So if you looking for something fancy on your new page, this is the place to go.

Personal sites

CSS Wizardry - personal website of Harry Roberts. He publishes irregularly about web performance and CSS. His posts are always high quality and go really deep. So if you are into the WebPerf this is one of the resources I suggest to follow.
Addy Osmani - Addy is Engineering Manager at Google working on Chrome. As such he mostly writes about WebPerf, often with relation to Chrome Browser.
Adrian Roselli - Adrian writes about accessibility (a11y) and has plenty of great articles about this topic. Definitely worth following if you are interested in this topic (and you should as a front-end dev).
Amelia Wattenberger - Amelia writes mostly about D3 and data visualization, but you can found articles about SVG, CSS, and React. What makes Amelia’s blog stand out is the high quality and interactivity of her articles. Each of them is like an interactive microsite with a lot of examples to help you understand the given topic.
Sara Soueidan - Sara has a large collection of articels about SVG, CSS and a11y.
Tim Kadlec - Tim is well known for is focus on WebPerf, so you can found lots of articles about this topic on his blog.
Josh Comeau - Josh writes about various subjects related to front-end development, like React, Gatsby, CSS and animations, JavaScript.
Philip Walton - Phil is an engineer at Google, and his articles focus a lot on web performance (mainly fast loading of the website) and JavaScript, but you can found articles about other topics as well.
Phil Hawksworth - Phil works at Netlify in the Developer experience team, so expect his articles to focus mainly on JAMstack.
Bits of Code - Ire Aderinokun’s blog about front-end development. Some topics covered on the blog: CSS, JS, HTML and DOM, Puppeteer, etc.

Other

Recently I started to follow the blogs of W3C (World Wide Web Consortium) and WHATWG (The Web Hypertext Application Technology Working Group) to keep an overview of specification updates for HTML and CSS.

Newsletters

Aside from following many websites and blogs, I have also signup for plenty of newsletters (more than I like actually 😅). I have already unsubscribed from some I don’t read and I send the rest to a special folder in Gmail which I check from time to time. Below you can found a list of newsletters I still receive and check regularly. Again I do not read all the articles listed inside, but only a few which seem relevant or interested to me. My flow for newsletters is similar to the one I use for blog articles.

Kent C. Dodds - Kent writes blog mostly about React and testing. I have subscribed to his newsletter to get the blog post updates sooner and to get info about his new projects or courses.
JavaScript Weekly - news from JS world, upcoming additions to JS, cool projects and tools. Tutorials and community articles.
StackShare Weekly - since I’m a bit a tooling geek, I have an account on StackShare and get their newsletter. It contains a list of new interesting tools and case studies about scaling infrastructure. Not extra relevant for a front-end dev, but if you are into DevOps, this may be an interesting option for you.
Jason Lengstorf newsletter - Jason mostly writes about motivation and productivity. Apart from articles on his blog, he also sent extra stuff in the newsletter. Since I’m running my own blog and working on Qjub in my free time, these topics are quite relevant to me (combining day job with two little kids, blog/side-project and to have some free time for me and my wife is pretty difficult).
Tiny React - 3 links about React each week. Short and simple (I like those).
ES.next news - latest news from JS world, what is coming to spec. New tools etc. Similar to JavaScript Weekly mentioned above. Some info is the same in both (like new spec and releases), but not all.
Calibre’s performance newsletter - a newsletter about web performance and how to improve it.

Twitter

I also follow a bunch of smart and amazing people on Twitter, so I get some gems and new ideas from here as well. But because of Twitter’s nature and my attempt to limit my time there, it’s not an extra reliable source to keep up to date with front-end dev. Never the less if you want to who I follow, check my Twitter profile (I mostly follow people whos blog I read).

What you might not know about sizing in CSS

Tue, 08 Dec 2020 00:00:00 +0000

A project I currently work on has a lot of different and sometimes non-trivial layouts. And it can be a struggle to get all the different elements sized correctly to avoid overflows and extra scrollbars. So I have deep dive into the CSS specification to learn about sizing and layout models as much as possible. And how to handle issues like this better in the future. I will share my findings with you.

We will cover those topics:

How percentage works for the height property
Two ways how to handle stretching in Flexbox
What 1fr really means to the browser

How does `height: 100%;` work

Sometimes you need to set the fixed height of some element. You can use absolute units like px, or relative units like em or rem. Those work much better in the responsive design. There is not much to talk about. You set the height to some exact number and it just works. But, when you want to use a percentage, that’s when you can encounter some trouble.

A common mistake is that people set height to 100% and think it will stretch the entire height of the parent element. But that is not always the case. Here is what the specification says about this:

The percentage is calculated with respect to the height of the generated box’s containing block. If the height of the containing block is not specified explicitly (i.e., it depends on content height), and this element is not absolutely positioned, the value computes to ‘auto’.

To translate it into simple English. If the browser doesn’t know the height of a parent it can’t calculate the height of the element (you can’t calculate percentage from unknown value). In such a case it will let the content control the height instead. This often means that you have to set height across many parent nodes (eventually up to the html element itself). That can lead to fragile layouts, where one change in the markup will break the whole damn thing.

One cool trick to avoid this problem is the usage of CSS Grid. When you set the height of the grid item’s child using percentage it will work. For the purpose of calculating height, a grid item is considered to have explicit height. This works even for grid sizing keywords like auto, max-content, and min-content. You can see it working in the codepen below.

See the Pen Set column height with percentage in grid items by Tomas Pustelnik (@Pustelto) on CodePen.

In the codepen below, you can explore how is the height with the percentage units affected by different properties.

See the Pen How height in percentage works by Tomas Pustelnik (@Pustelto) on CodePen.

If you want to know how exactly percentage units work in different properties, definitely check the amazing article from Amelia Wattenberger.

How sizing in Flexbox works

Flexbox is a powerful layout module, solving a lot of common layout and alignment issues easily. But, if you have been using Flexbox for some time, you have probably encountered a situation where the flex items didn’t size exactly as you expect. Flexbox works great when you don’t care so much about the size of the items. But it can get a little tricky when you need exact sizes.

To explain how Flexbox really works we will use a simple example. We have a flex container with 3 items of different widths. If we set only display: flex on parent it will look like on the image below.

In Flexbox, flex-grow and flex-shrink properties control the shrinking and the expansion of the flex items. Those properties can be also set by shorthand flex property. The default value for the browsers is flex: 0 1 auto. This means that items can shrink if there is not enough space, but they will not expand to fill the container.

When you add flex-grow: 1 to flex items, they will stretch to fill the entire width of the container. But the items don’t have the same size. Even though they can easily fit into the container and all of them have the same value of flex-grow property. Also, the right part is a bit smaller than the left part.

How is that possible? Shouldn’t all items have the same width? No, because Flexbox by default distributes the remaining empty space (hatched area in the image below). Not the entire container width, as some developers often think. Even if you set the same flex-grow value to all flex items, they will not have equal widths. Unless their basic width is the same as well (set via width or flex-basis properties).

To avoid this way of space distribution you can set the flex-basis value to 0. When the flex-basis is set to any value other than auto, the width property of the items is ignored and browses will consider that all items have basic width equal to the given flex-basis. So when you set flex-basis: 0 you are telling the browser that all flex items have zero width. Thus the entire flex container width will be used as a free space to distribute based on values of flex-grow.

You can see on the schema below how flex-basis 0 and auto work exactly (image is taken from the specification).

Beware of the extra padding and border

One more thing to be aware of is that borders and padding on child items will increase the item’s width. And the flex items will not honor the flex-grow ratio precisely (even with flex-basis: 0). Here is a related part of the specification:

The hypothetical main size is the item’s flex base size clamped according to its used min and max main sizes (and flooring the content box size at zero).

Add padding or border to the child of flex item to fix this. As seen in the codepen below.

See the Pen Flexbox sizing by Tomas Pustelnik (@Pustelto) on CodePen.

Large grid items breaking from the grid layout

Imagine you have two columns layout. Sidebar with header and footer and a large list of items we want to scroll. And then the main area where we display the detail of the selected item. This layout can be usually seen in an email client. We have set the fixed height of the grid. After all, we don’t want to scroll the page itself, but the items in the sidebar or the detail in the content area. grid-template-rows is set to 1fr to fill all available space.

You can see the layout in codepen below.

See the Pen how the sizing of fr units works by Tomas Pustelnik (@Pustelto) on CodePen.

But for some reason items in the sidebar are overflowing out of the grid area and the entire page is scrollable. Not exactly what we want or expect.

The problem is in the grid-template-rows property. When we set its size using the fr unit, grid items min-size is set to auto by default (according to specification). With value auto grid item will resize to fit in all the content, even it is bigger than the defined grid cell.

So grid-template-rows: 1fr; is equal to grid-template-rows: minmax(auto, 1fr);.

To fix this problem let’s change out the definition of grid rows to grid-template-rows: minmax(0, 1fr);. With this, our extra-large ul list will shrink to fit the grid defined area as we would expect. You can test it in the codepen mentioned above.

Summary

And that’s it. We have covered a few cases where the sizing doesn’t behave as we could expect at first. Hopefully, this article will help you to build layouts in CSS more easily and with less frustration.

Freezing development of Qjub

Sun, 10 Jan 2021 00:00:00 +0000

TLDR: I don’t have enough time to focus on all my side-projects and activities. So I have decided to focus more on my blog than on the Qjub. For more detailed reasons, continue reading.

Why I’ve decided that way?

A little bit of context first. I have a full-time job (last couple of months I worked only 4 days/week actually), two little kids, a few small open-source projects, and I wrote my own blog. That is a lot of going on and while one extra day to focus on these things helped. It still doesn’t allow me to focus on all those things equally.

When I start writing my blog last year, my goal was to publish at least one article a month. I didn’t meet that goal (yet), but I want to continue to focus on writing more. To do that, I decided to freeze the development of the Qjub. Here are some reasons why I choose to do so:

1. Writing a blog makes more sense to me

When I start my blog, I haven’t had a feeling I have too much to offer (hello imposter syndrome). But I gave it a shot and tried to regularly post new articles and republish them 14 days later to Dev.to community. I still have a small audience, but two articles get some serious notice and more than 12k page views (on my blog or on Dev.to). Given these are some of my first articles, I consider that amazing success. And it’s a great motivation to continue with writing. Don’t get me wrong. Even if my article helps a single person I consider it a success. But seeing so many people read your blog feels amazing.

While working with other developers and checking some existing apps, I realized many front-end developers lack deeper knowledge of web performance, semantic HTML, advanced CSS, and accessibility. So I decide to continue with my blog and focus on those things to teach other developers. And in general, help make the Web better for the users as well.

2. The unclear focus of Qjub

I start Qjub as a learning project, but it was designed right from the start to solve one of my problems – how to effectively store and organize different notes and resources. Mainly from the web. I believe Qjub does a good job in this case. Or at least it works great for my needs. But I really didn’t figure out how to sold this to others. Currently, I have around 20 users, but very few of them are using Qjub regularly. A great example of this is traffic from my blog. One of my popular blog posts brought to Qjub about 300 visitors in two weeks (a huge spike in visits for me). But none of them become regular users.

That leads me to the hypothesis that:

My idea is not so great and aside from me, no one needs it.
Qjub’s homepage is really bad at its job to explain Qjub to others and convince them to sign up.

I believe that both points are valid. I plan to do something with point number 2 before really putting Qjub aside. As with number 1. I’m not sure I can do much with that.

What it means for Qjub and its users

Freezing Qjub’s development doesn’t mean I’m going to shut down the project. Qjub will be still there, and it is free to use for anyone. I use it quite a lot, so it’s not going anywhere. It would be a huge pain for me to migrate all my notes and other stuff somewhere else. And domain aside, I run it almost for free. So I have no reason to shut it down completely.

I will simply stop developing new features and instead use available time for my other activities. You may say that I have already done it if you check Qjub’s changelog. But declaring it to the public like this will help me get rid of the mental overhead I currently have with it. And it’s aligned with my value of transparency to the users.

I still may update it from time to time, since there are plenty of features I would like to add. But that will be an occasional activity.

Next steps

Before completely putting Qjub aside, I plan to update the homepage as a final effort to better explain its value to the users. After that don’t expect any large updates.

Real-world CSS vs. CSS-in-JS performance comparison

Fri, 09 Apr 2021 00:00:00 +0000

CSS-in-JS has taken a solid place in front-end tooling, and it seems this trend will continue in the near future. Especially in the React world. For example, out of 11492 people who participate in State of CSS survey in 2020 only 14.3% didn’t hear of Styled Components (a dominant CSS-in-JS library). And more than 40% of participants have used the library.

I wanted to see an in-depth performance comparison of CSS-in-JS libraries like Styled Components and a good old CSS for a long time. Sadly I was unable to found a comparison on a real-world project and not some simple test scenario. So I decided to do it myself. I have migrated the real-world app from Styled Components to Linaria, which will extract CSS on build time. No runtime generation of the styles on the user’s machine.

A short notice, before we begin. I’m not a hater of CSS-in-JS. I admit they have great DX, and the composition model inherited from React is great. It can provide developers with some nice advantages like Josh W. Comeau highlights in his article The styled-components Happy Path. I also use Styled Components on several of my projects or projects I have worked on. But I wondered, what is the price for this great DX from the user’s point of view.

Let’s see what I have found.

TLDR:

Don’t use runtime CSS-in-JS if you care about the load performance of your site. Simply less JS = Faster Site. There isn’t much we can do about it. But if you want to see some numbers, continue reading.

What I measured and how

The app I have used for the test is a pretty standard React app. Bootstrapped using Create React App project, with Redux and styled using Styled components (v5). It is a fairly large app with many screens, customizable dashboards, customer theming, and more. Since it was built with CRA, it doesn’t have server-side rendering, so everything is rendered on the client (since it’s a B2B app, this wasn’t a requirement).

I took this app and replaced the Styled Components with Linaria, which seems to have a similar API. I thought the conversion would be easy. It turned out it wasn’t that easy. It took me over two months to migrate it, and even then, I have migrated only a few pages and not the entire app. I guess that’s why there is no comparison like this 😅. Replacing the styling library was the only change. Everything else remained intact.

I have used Chrome dev tools to run several tests on the two most used pages. I have always run the tests three times, and the presented numbers are an average of those 3 runs. For all the tests, I have set CPU throttling to 4x and network throttling to Slow 3G. I used a separate Chrome profile for performance testing without any extensions.

Run test:

Network (size of the JS and CSS assets, coverage, number of requests)
Lighthouse audits (performance audit with mobile preset).
Performance profiling (tests for page load, one for drag and drop interaction)

Network comparison

We will start with a network. One of the advantages of CSS-in-JS is that there are no unused styles, right? Well, not exactly. While you have active only the styles used on the page, you may still download unnecessary styles. But instead of having them in a separate CSS file, you have them in your JS bundle.

Here is a data comparison of the same home page build with Styled Components and Linaria. Size before the slash is gzipped size, uncompressed size is after it.

Home page network stats comparison
	Styled Component	Linaria
Total number of requests	11	13
Total size	361kB/1.8MB	356kB/1.8MB
CSS size	2.3kB/7.2kB	14.7kB/71.5kB
No. of CSS requests	1	3
JS size	322kB/1.8MB	305kB/1.7MB
No. of JS requests	6	6

Search page network stats comparison
	Styled Component	Linaria
Total number of requests	10	12
Total size	395kB/1.9MB	391kB/1.9MB
CSS size	2.3kB/7.2kB	16.0kB/70.0kB
No. of CSS requests	1	3
JS size	363kB/1.9MB	345kB/1.8MB
No. of JS requests	6	6

Even though our CSS payload increased quite a lot, we are still downloading fewer data in total in both test cases (yet the difference is almost neglectable in this case). But what is more important, the sum of CSS and JS for Linaria is still smaller than the size of the JS itself in Styled Component.

Coverage

If we compare coverage, we get a lot of unused CSS for Linaria (around 55kB) compared with 6kB for Styled Component (this CSS is from npm package, not from the Styled Components itself). The size of the unused JS is 20kB smaller for Linaria compared to Styled Component. But the overall size of the unused assets is larger in Linaria. This is one of the trade-offs of external CSS.

Coverage comparison – Home page
	Styled Component	Linaria
Size of unused CSS	6.5kB	55.6kB
Size of unused JS	932kB	915kB
Total size	938.5k	970.6kB

Coverage comparison – Search page
	Styled Component	Linaria
Size of unused CSS	6.3kB	52.9kB
Size of unused JS	937kB	912kB
Total size	938.5k	970.6kB

Lighthouse performance audit

If we are talking about performance, it would be a shame not to use Lighthouse. You can see the comparisons in the charts below (average from 3 LI runs.). Aside from Web Vitals, I have also include Main thread work (time to parse, compile and execute assets, the biggest part of this is JS, but it covers layout and styles calculation, painting, etc.) and JS Execution time. I have omitted Cumulative Layout Shift since it was close to zero, and there was almost no difference between Linaria and Styled Component.

As you can see, Linaria is better in most of the Web Vitals (lost once in CLS). And sometimes by a large margin. For example, LCP is faster by 870ms on the home page and by 1.2s on the Search page. Not only does the page render with normal CSS much faster, but it requires fewer resources as well. Blocking time and time necessary to execute all the JS are smaller by 300ms and roughly 1.3 seconds respectively.

Performance profiling

Lighthouse can give you many insights on the performance. But to get into the details, the performance tab in the dev tools is the best bet. In this case, the performance tab confirms the Lighthouse results. You can see the details on the charts below.

Screens build with Styled Component had more long-running tasks. Those tasks also took longer to complete, compared to the Linaria variant.

To give you another look at the data, here is the visual comparison of the performance charts for loading the home page with Styled Component (top) and Linaria (bottom).

Comparing user interaction

To compare user interaction as well, not only the page load. I have measured the performance of the drag and drop activity used to assign items into groups. The result summary is below. Even in this case, Linaria beat the runtime CSS-in-JS in several categories.

Drag and drop comparison
	Styled Component	Linaria	Diff
Scripting	2955	2392	-563ms
Rendering	3002	2525	-477ms
Painting	329	313	-16ms
Total Blocking Time	1862.66	994.07	-868ms

Conclusion

That’s it. As you can see runtime CSS-in-JS can have a noticeable impact on your webpage. Mainly for low-end devices and regions with a slower internet connection or more expensive data. So maybe we should think better about what and how we use our tooling. Great developer experience shouldn’t come at the expense of the user experience.

I believe we (developers) should think more about the impact of the tools we choose for our projects. The next time I will start a new project, I will not use runtime CSS-in-JS anymore. I will either use good old CSS or use some build-time CSS-in-JS alternative to get my styles out of JS bundles.

I think build-time CSS-in-JS libs will be the next big thing in the CSS ecosystem as more and more libs are coming out (the last one being vanilla-extract from Seek). And big companies are heading this way as well, like Facebook with their styling lib).

*[CRA]: Create React App

How and why I've migrated from Netlify to Cloudflare

Wed, 12 May 2021 00:00:00 +0000

Up until recently, I have hosted my site on Netlify. They offer free hosting with great Github integration and a smooth developer experience. All this is supported by plenty of other great services. I was super happy with them. But then Cloudflare announced their new service Pages. So far, Cloudflare was known for its fast CDN and networking services. Given their reputation, I have decided to give it a shot. I was wondering if changing my hosting could have some noticeable impact on my page load times.

And oh boy, it did.

In this article, I will briefly guide you through the entire process of moving my site from Netlify to Cloudflare Pages with all the little bumps I had along the road. Then I will show you how it impacted the performance of the site.

Migration steps

At first look, Cloudflare Pages is pretty similar to Netlify or Vercel. You connect your repo, set your build command, hit save and that’s it. You have automatic deployments with preview links for your PRs. Cloudflare has great documentation, including specific guides for different frameworks and static site generators.

Adding a new web page to Cloudflare Pages is easy. Just select a branch and your project's build command.

Ok. Now I have my site on Cloudflare.

Well, not really…

I have moved my hosting. Unfortunately, I’m using more tools from the Netlify ecosystem (build plugins, inject code snippets, etc.). So the migration of my setup 1 to 1 is not that straightforward.

Here is the list of the stuff I need to solve to move entirely to Cloudflare Pages:

Migrate Netlify build plugins
Include code snippets (analytics) only during production build
Transfer my domain to Cloudflare
How to set up custom HTTP headers for my page
URL redirects

Build plugins

I use Netlify’s build plugin to extract Critical CSS for my blog. So I need to get this on Cloudflare as well. HTML won’t start rendering until it has downloaded CSS, but if you inline your critical CSS into your HTML and lazy-load the rest. HTML can start to render right away after the first network request. This may improve your page load time quite a lot.

I picked probably the easiest possible way. Since the Netlify plugins are open source, I simply found the source code of the Critical CSS plugin on Github and extract the code into the Node.js script. I run this script during the build process. I have migrated the build plugins, and it took only a couple of minutes of work. Open source FTW 🎉.

To the next step, which is…

Include code snippets during build time

I use Plausible as my analytics. It’s paid, but privacy-focused analytics tool which gives me all the information I really need. It’s super lightweight, and I’m more than happy to support independent developers and their great products 🙂.

On Netlify, I used the build setting to include the Plausible code snippet during build time. It was an easy way, how to avoid firing analytics events during development. Since Cloudflare doesn’t have this option, I had to use some other method. Luckily there is Eleventy high performance blog template which utilize Eleventy data cascade in a clever way to add isDevelopment flag into templates. Another quick copy-paste action and another finished item from my to-do list.

Domain transition

The next step was to move the domain to Cloudflare. I had to change my nameservers to point to Cloudflare. I buy my domains via Vercel (I use it for few projects and love how easy and smooth is the process of buying domain there). But since Vercel isn’t a domain registrar, I had to contact Vercel’s support in order to change the nameservers. Based on their info, Vercel support process requests for free accounts within 3-5 days. But I had got my nameservers changed the next day 👍.

Once Cloudflare noticed correct nameservers, I could add a custom domain to my webpage, assign the worker to modify the headers, and handle the URL rewrites.

Adding custom HTTP headers to Cloudflare Pages

If you want to set custom headers for your web page hosted on Cloudflare Pages, you simply have to add _headers file to the root of the build folder (pretty easy in Eleventy, just add config.addPassthroughCopy("src/_headers"); into your eleventy.js file).

Syntax of the _headers file is simple as well. You just need to specify the URL pattern and then custom headers below it.

/*.avif
  Content-Type: image/avif
  Content-Disposition: inline

https://:project.pages.dev/*
  X-Robots-Tag: noindex

Setting custom via _headers file.

Check out the official documentation for headers or my own _headers file.

This should probably satisfy most of your needs when customizing headers. But if you need something more advanced, then you have to use Cloudflare Workers. Continue reading, if you are interested in that, otherwise feel free to skip to the next section.

Headers customization using Cloudflare Workers

Custom headers for Cloudflare Pages were probably the most complicated part of the entire migration. Compared to Netlify, Cloudflare doesn’t have any direct tool to customize your headers. If you need this functionality, you have to use another service – Cloudflare Workers. You have to create a custom worker script to modify the headers. Luckily basic version of workers is free, and Workers documentation even include example showing how to modify the headers. Just exactly what we need.

You can either copy-paste the code and modify it in the web interface. Or you can download Cloudflare CLI, create the script locally and publish it when ready. Below is the example of my worker script:

addEventListener('fetch', event => {
  event.respondWith(handleRequest(event.request))
})

async function handleRequest(request) {
  const reqUrl = new URL(request.url)

  let response = await fetch(request)
  // Make the headers mutable by re-constructing the Response.
  response = new Response(response.body, response)

  if (reqUrl.pathname.endsWith('.avif')) {
    response.headers.set('Content-Type', 'image/avif')
    response.headers.set('Content-Disposition', 'inline')
  }

  response.headers.set('Permissions-Policy', 'interest-cohort=()')
  response.headers.set('X-Frame-Options', 'sameorigin')
  response.headers.set('strict-transport-security', 'max-age=31536000')
  response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin')

  return response
}

Another downside is that you can’t connect workers to the default URL provided by Cloudflare for your pages. You have to set up a custom domain for your page and add the worker script to the domain by specifying its route. If you need to change headers on your webpage, but you don’t have a custom domain for some reason, you are at a dead end.

This sure isn’t as easy as using Netlify’s config file, but it is still relatively simple to set up. Still, it may be one thing to consider when deciding whether to choose Cloudflare as your hosting.

Custom redirects

On Netlify, I had custom redirects to route all my traffic from the www subdomain to the root domain. And then from my original domain *.pustelto.cz to https://pustelto.com. The first redirect is handled on Netlify automatically when setting up DNS records. The second one can be done fairly easily as well.

On Cloudflare, I didn’t have much trouble with this. I have moved my second domain to Cloudflare too, and then used rules config to handle the redirects. You can set up the redirects in few clicks. In a free Cloudflare plan, you have 3 Page rules for free. That is more than enough to handle my use case. But if you have more advanced redirect logic, it may not be enough (you can buy additional rules if necessary).

Performance comparison

I compared the page load times of my website on Cloudflare and Netlify using WebPageTest.org. The test setup was mobile emulation of Mogo G (gen 4) on a fast 3G connection. FCP and LCP on Cloudflare were almost 400ms faster! And the page was visually complete in 1.1s compared to 2s on Netlify. That is a really huge improvement I’ve got basically for free. Just by changing hosting, I have got over 300ms better page load across the pages. Another benefit is a slightly smaller payload from Cloudflare, thanks to the support of Brotli compression.

Check out the pictures below for more details. Notice the waterfall chart for Netlify where the image is downloaded from another domain and so it requires another SSL connection which will add to the total time necessary to download the file.

Visual comparison of loading home page on Cloudflare and Netlify

Visual comparison of loading article page on Cloudflare and Netlify

Waterfall chart when loading the home page from Cloudflare

Waterfall chart when loading the home page from Netlify

So should I migrate to Cloudflare?

It depends 😅.

You should consider what you have to migrate and what would be the cost of it. If you are already heavily invested in another hosting platform (be it Netlify, Vercel, or something else), it might add extra effort to convert your entire setup. Netlify, for example, offers a bunch of other great tools, and leaving the entire ecosystem may be problematic. But the performance gains can outweigh the cons of the migration. As always, when working on performance-related stuff, measure it.

Another thing to consider is the price. As mentioned above, you can get the basic stuff for free on Cloudflare as well. But for more complex sites, this may add an additional cost. Especially with workers and page routes, you can go from free Netlify to paid Cloudflare quickly in more advanced cases.

But for simple static sites, I think it is worth it.

Conclusion

I hope this article will help you in case you decide to give Cloudflare Pages a chance. And eventually help you with migration, since there were few little things I had to figure out myself (eg. custom headers and redirects) since documentation didn’t mention this. But overall switching to Cloudflare wasn’t too difficult and I manage to finish it in few hours of work.

That’s it, folks. Let me know on Twitter if you tested the Cloudflare Pages and what do you think? Or if you decided to stick with a different platform, let me know which one and why. I would love to see what are you using.

Updates

6 November 2021 - add info about new way how to set custom headers for Cloudflare Pages.

5 easy steps to improve accessibility.

Sat, 16 Apr 2022 00:00:00 +0000

Want to get better at the accessibility, but you don’t know where to start?

You can do a lot for the accessibility of your websites with only a few basic techniques. Below you will find a list of items, which are easy to use, but I see many websites doing mistakes in them.

TLDR:

Use semantic HTML
Add meaningful labels to interactive elements and page sections on the page
Make focused elements clearly visible
Test with keyboard
Learn how to use screen readers

Please not that tips mentioned in this article will help you kickstart your accessibility efforts, but they won’t be most likely sufficient to make your website fully compliant with WCAG specification.

Why should we care?

The Interner has become an integral part of our lives. We spend a large amount of our time on the internet. This has become especially true during Covid pandemia. Unfortunately, not all people can use the Internet with ease. Some can’t use a mouse, others may need a screen reader or even use voice to control their computer. It’s our responsibility as developers to build a web that is accessible and useable by all.

With that said, let’s get to the business. Here is what you can do to improve accessibility on your websites:

1. Use semantic HTML

One of the easiest things to do when you want to get better with accessibility is to start using semantic HTML. Yes, you can build an entire site with div and CSS, but that would mean a terrible user experience for users relying on screen readers.

Using semantic HTML has a few benefits:

Properly implemented semantic markup (and labeling, see next section) allows users with a screen reader to easily navigate and find what they need. It helps them understand what kind of content they are consuming. I highly recommend checking this video how semantic HTML helps screen reader users with navigation or how people with disabilities use screen readers
Native HTML elements (like buttons) have a lot of functionality baked in. If you use for example div to create interactive elements you will lose all those accessible features already available.

Here is what you can do to boost the semantics of your HTML:

Build the structure of the page

Use HTML tags to mark important regions like main,nav, header, footer.
Add correct heading structure - aka don’t skip the headings level. h2 should always follow h1, h3 after h2 etc. No h4 after h2 and similar, pretty please.

I suggest reading HTML elements reference on MDN to learn about all the elements available in HTML. You might be surprised what elements you discover.

Use correct interactive elements

Web apps these days are more capable than ever, to make the interactive experience we often have many interactive elements on the page. Buttons, links, inputs, date pickers, select, and so on.

It is important to use those elements for their real purpose. Otherwise, you may confuse users relying on screen readers. For example, don’t mix buttons and links. A link should take the user to the new page and change the URL. Use a button for the rest.

If possible, prefer native HTML elements as they usually provide accessibility and other functionalities out-of-the-box (there are certain native HTML elements for poor accessibility though).

I have also covered this topic in more detail in my older article What every JavaScript developer should know about HTML and CSS. So please check it here.

2. Label the stuff properly

Good labels are important to all users. They help them navigate the user interface and finish the task successfully. But they are essential for screen reader users.

Without proper labels, the screen reader has nothing to announce to the users, except for the role of the element. Imagine this scenario: You need to press Add to cart button on the e-commerce site, but how can you pick the correct button if all you hear is: “button”. And you hear that 24 times.

To avoid this, keep these simple rules in mind:

Every interactive element must have a proper accessible name

So the screen reader users can understand what the element does. Eg. use a <label> element for the form inputs, add a text label to all buttons and links (yes, even button with only an icon can have a text label).

When you don’t have a native HTML element to label something (eg. naming several <nav> elements on the page so screen readers can easily jump between them), you can use aria-labelledby or aria-label attributes.

Adrian Roselli has a great summary of how to prioritize different labeling techniques.

Labels should be clear and short but have enough information to understand the context.

For example, visually it is ok to have Add button next to an item to add it into a cart. But screen reader users may need more information, so it is often a good idea to add extra information to the button visible only for screen readers. When a screen reader move focus to our Add button, it may announce something like this: Add to cart, A-Wing Lego Star Wars

Want to learn how to create good labels for link and button checkout these articles: The perfect link and Accessible Text Labels For All.

3. Make focused elements visible

Hidding focus outline from users seems like a design fetish. It doesn’t help anyone, and I doubt it will improve a design. Rather design a nice and visible focus outline.

Not sure what more to write to this one. Just make the focusable interactive elements visible, please. If you don’t like the default outline, design a better one, but don’t disable it.

I use keyboard navigation quite often as well. Especially when filling some forms and sometimes I really struggle to see where the hell is my focus.

If you want to learn how to do a great focus outline, I suggest an article about designing WCAG-compliant focus indicators from Sara Soueidan. And be careful when using box-shadow property for outline. It doesn’t play nice with Windows high-contrast mode.

4. Test with keyboard

When you are building a new webpage, always try to navigate it using only a keyboard. It is an extremely easy way of testing, but it can show you a lot of potential issues early on. This is also good practice when selecting some UI package for your new web project 😉.

When testing with a keyboard I usually try to check for those use-cases:

Can I focus and control all interactive elements with a keyboard?
Is the focused element always visible so the users know where are they?
Does the focus move correctly for more complex patterns (eg. when I open a modal window, is the focus in the modal or still on the trigger button)?
Is the tab order logical? Modern layouts built with a grid and a flexbox can change the visual order of the elements in CSS. But tab order is determined by the position in the HTML, not by CSS layout. This may confuse users, so be careful.

5. Learn how to use screen readers

So you already test with a keyboard. Great. Now it’s time to move to next level in accessibility testing. Learn how to use at least one screen reader and use it to test your pages (and other pages as well).

Learning how to use a screen reader helped me to be more emphatic with screen reader users. It’s shocking how very little information they often have available and how hard it is to use the web.

Using a screen reader opened my eyes. I started to think differently about the labels, alt texts, and accessible names in general. And instead of plain save or delete I have started to provide much more info into the labels. Or put the labels at places where I wouldn’t add them in the past.

Don’t know how to use a screen reader?

Check out these guides from Deque about various screen readers and start practicing. It takes some time to be effective with them, but if you are serious about a11y, then this is a must.

Conclusion

That was quite a lot to digest. Congratulations for getting all the way here. I hope this article will help you to make the Web a little bit better for everyone.

And if you still think there is too much to deal with, don’t worry. Start slow and add new stuff when you feel comfortable. Learning accessibility is a never-ending process and we have just barely scratched the surface. We didn’t even talk about ARIA attributes and roles, or how JS fits in, and so on.

How to (not) make a button

Fri, 16 Sep 2022 00:00:00 +0000

Today’s web is a very interactive experience, yet we often fail to provide the same experience to everyone.

Complex form widgets, interactive configurators, tables, shop listings, and the list goes on. We should use buttons and links to interact with those components. But often, we just put an onClick handler on a div and call it a day.

That leads to a poor experience for some users.

I want to show you how to properly turn a div into a button, in case you ever need it. So the result will be accessible and useable by everyone.

Why would you want to create a custom button?

There may be various reasons for this.

We may have limited control over the markup (eg. when we use 3rd party library). Or there is some specific use case that doesn’t seem to be a good fit for a button or a link (and I have seen a lot of them in my career). For example:

Interactive clickable card with the product info and other controls (add to cart, compare, etc.)
Nested controls (a button with another button inside)
Clickable table rows.

While having limited control over markup may be hard to overcome. We can often solve these specific cases with a little bit of effort.

Changing the design may be a valid option in some cases. But often we just need to rethink the markup a little bit. Here are some links for common patterns and how to do them correctly:

But if you think you still have to build a custom button, then read on:

Building a button from a div

Your first step will most likely be adding an onClick handler. So let’s start with this:

<div onClick={doSomething}>Click me. I'm a fake button</div>

Often this is also where it ends.

But as soon as you try to use a keyboard to interact with your new button, you will find that you can’t select it using the Tab key.

So let’s fix that and add a few more properties.

<div tabindex={0} onClick={onClickButtonHandler} onKeyDown={onKeyDownHandler}>
  Click me. I'm a fake button
</div>

We have to add a tabindex attribute with the value 0. This will make the button focusable when using a keyboard (an important part of any accessible interface).

Next, we have to assign a keydown event listener to our custom button. HTML button can be pressed using Enter and Space keys. So we need to add that behavior as well. The listener callback will look something like this:

function onKeyDownHandler(event) {
  if (event.key === "Enter" || event.key === " " /* space */) {
    // We have to disable default space behavior which is scrolling page down.
    event.preventDefault();
    onClickButtonHandler();
  }
}

But in reality, this is not exactly correct behavior. The native button works slightly differently, as Adrian Roselli pointed out in his article Brief Note on Buttons, Enter, and Space.

Enter triggers the native button on the keydown event, but Space triggers the button on the keyup event (the press with Space can be canceled). If we want to mimic this behavior we have to update our handlers again:

<div
  tabindex={0}
  onClick={onClickButtonHandler}
  onKeyDown={onKeyDownHandler}
  onKeyUp={onKeyUpHandler}
>
  Click me. I'm a fake button
</div>

function onKeyDownHandler(event) {
  if (event.key === " ") {
    // We have to disable default space behavior which is scrolling page down.
    event.preventDefault();
  }
  if (event.key === "Enter") {
    onClickButtonHandler();
  }
}

function onKeyUpHandler(event) {
  if (event.key === " " /* space */) {
    onClickButtonHandler();
  }
}

Accessibility improvements

Right now, we have a fake div button that users can click on. And they can control it with a keyboard as well. But we still have to do a few more things to make this button accessible. First, we need to tell screen readers that this is really a button, not a div. We will add the role="button" attribute. Without it, screen readers won’t announce this as a button to the users.

<div
  tabindex={0}
  onClick={onClickButtonHandler}
  onKeyDown={onKeyDownHandler}
  onKeyUp={onKeyUpHandler}
  role="button"
>
  Click me. I'm a fake button
</div>

Are we done?

For the basic functionality, yes. But what if you need to disable that button?

For an HTML button, you would just use the disabled attribute and the browser would take care of everything (default styles, turn off the interactivity, etc.). But that is not going to work for our fake button.

We have to use the aria-disabled attribute. But we also have to handle the styling and also disabling of the event handlers. You might also want to prevent the button to be unfocusable via tab. All this means just more work for us.

Final result

This is our final code for a button with support for the disabled state:

<div
  tabindex={0}
  onClick={onClickButtonHandler}
  onKeyDown={onKeyDownHandler}
  onKeyUp={onKeyUpHandler}
  role="button"
>
  Click me. I'm a fake button
</div>

function isDisabled(eventTarget) {
  const ariaDisabled = eventTarget.getAttribute("aria-disabled");
  const isDisabled = ariaDisabled === "" || ariaDisabled === "true";

  return isDisabled;
}

function onKeyDownHandler(event) {
  if (event.key === " ") {
    // We have to disable default space behavior which is scrolling page down.
    event.preventDefault();
  }
  if (event.key === "Enter" && !isDisabled(event.target)) {
    onClickButtonHandler();
  }
}

function onKeyUpHandler(event) {
  if (event.key === " " && !isDisabled(event.target)) {
    onClickButtonHandler();
  }
}

Quite a lot of code for a simple component, right? And even if you write all this code you still don’t get the full button feature set^[1].

I hope by this time that you realize that instead of writing all this code yourself, it is much easier to write this code and get all the goodies for free:

<button type="button" onClick={onClickButtonHandler}>
  Click me! I'm a real button.
</button>

Isn’t that much easier?

Conclusion

While the button seems to be a simple component, which we can easily hack together with the div and onClick handler, the opposite is true.

I hope you have learned how complex it is to create a good button component and how much time and effort you can save using a native button.

And your users will probably thank you as well.

Additional resources

Want to learn more? Check out these amazing resources:

Brief Note on Buttons, Enter, and Space
A three-part series about implementing a button in the React-Aria library:

Updates

10 October 2022 - Added e.preventDefault() to event handlers. Aaron corretly pointed out, that I forgot to disable native space behavior to scroll the page down.

We created a generic button, but the HTML button has more types. It can submit or reset a HTML form, when nested inside <form> tag without any extra JS (aside from handling the submitted data).

And when we add a form attribute on the button to connect it to a form. We can do that even if the button is outside of the <form> element. ↩︎

I have switched from VS Code to VIM and I will never go back

Mon, 16 Jan 2023 00:00:00 +0000

Some time ago, I posted a tweet announcing I had switched from VS Code to VIM (Neovim to be precise).

Given that most of my colleagues looked at me in disbelief when I told them. I have decided to summarize my reasons behind this and outline the process for those brave enough to follow 😁.

Why I ditched VS Code

I would say my two main reasons are performance and navigation in the code. VIM is just great at those.

And while you can easily add navigation to VS Code with VIM plugin. You can’t do
much about performance.

Performance

VS Code has become unbearable slow for me, especially on large projects. And I’m using a mac, so I can’t blame the slow machine. Main issues I had:

There was a noticeable delay in the response when I triggered suggestions and before I got a response from Intellisense.
Opening large files.
Changing a project. When I wanted to check other projects, it took some time until the editor was fully responsive.

I tend to learn a lot of shortcuts (and prefer to use a keyboard most of the time). I could work like this in VS Code for most of the stuff, even though some keyboard shortcuts I used were quite complicated and required a combination of three keys most of the time.

But for the detailed movements in the code, I had to use mouse or arrow keys. Getting my hand aways from letters to reach for arrows just become annoying for me. In the end I add custom keybinding which simulated VIM’s hjkl basic navigation.

That was a point where I realized I should probably use at least VIM plugin instead of reinventing wheel.

How do I feel about Neovim

I love it.

Seriously.

I don’t think I will ever switch back to VS Code (or a similar IDE). Here is a quick summary of the good, ugly and bad from VIM (please note I’m still a beginner and know like 1% of VIM capabilities):

The good parts

It does everything I need, but faster (a lot faster in many cases).
It starts almost instantly. Getting into a file and quickly editing a few lines is a breeze. I am using a tmux and I have a running session for other projects. So this process is usually a matter of a few strokes. The ergonomics of this flow are genuinely nice.
Sleek minimalistic look.
Navigation and motions in the code (once you learn it, it is hard to go back).
I don’t have to use a mouse.
I like to mingle with my configs, so I enjoy this part as well (it is a good opportunity to learn something new).
It gives me that nerdy feeling of terminal superiority 🤓.
Editor in the terminal.
- I can easily edit any file from everywhere. This seems like a minor thing, but it actually is a great boost for productivity. Yes, I know I could open files in VS Code from terminal, but it took some time as well. Now I just type vim docker-compose.yml, and I can start editing. And I have all my keyboard shortcuts and plugins ready.

Ugly parts

I miss multi-cursor sometimes, but less often than I would expect. I expect this will get less relevant over time as I learn how to properly use VIM for this kind o stuff (macros, search and replace, global command, etc.).
I still haven’t finished my setup. Less used things do not have a proper config or do not have a keybinding.
Hard to debug sometimes, why something is not working. But most of the time everything just works as intended.
You must be willing to invest time to learn VIM (but you should invest your time to learn any other editor of your choice anyway).

Bad parts

Initial setup takes quite a lot of time. You could use one of the ready-to-use distros like LunarVim or AstroVim, but I haven’t check those too much.
Given the large ecosystem and nature of VIM, some plugins might conflict with each other. That may be hard to debug. So far I’ve had this issue only once, but it was still a pain to solve.

How did I do it

So you get interested in Vim and would like to give it a shot as well? Then you will need quite a lot of patience. But in the end, I think it is not so difficult as many people (and Boromir) believe. You can learn a few basic commands to be reasonably productive in a fairly short time.

Here is what I did:

I installed the VIM plugin for VS Code. It is a great for learning VIM. When you don’t know some commands, you still have a mouse and command palette at your disposal.
Then I spent a month or two playing with it, learning more keybinding and gettings used to it (there are some nice VIM cheatsheets that can help)
When I have decided to switch I wrote down a list of features I wanted and needed in my editor.
I jump on Google and YouTube to see what is possible and how to configure the stuff. I found YouTube series Neovim from scratch. The setup covered in the series have almost everything I need. So I mostly copy-paste and tweak a the config a little bit (there is a GitHub repo so you can just clone it).
Once I had a feeling I have the most critical features I make the move and add more stuff as needed.

Conclusion

That was my story with VIM in short.

This is not meant to convince anyone to move to VIM. Use what you feel is the best tool for the job. In the end, you can be incredibly productive in any editor if you invest your time in learning it properly.

As for me, I will stay with VIM. I don’t have a reason to go back to VS Code or any other “standard” editor. I’m really enjoying the experience and feel more productive.

Rust through the eyes of FE developer

Thu, 30 Mar 2023 00:00:00 +0000

Rust is a programming language that has gained a lot of popularity recently. As someone who has been interested in Rust for a while, I finally decided to play with it for a month.

In this article, I’ll share my experience building a command-line tool with Rust and highlight what I loved about the language, as well as what I struggled with.

What did I do

I decided to build a command-line tool because it was a perfect fit for my study project.

First, I went through the exercise projects in the official Rust documentation, including Command line apps in Rust and chapters 12 and 20 in the Rust book on building a command-line program and a multithreaded web server, respectively.

Once I finished those tutorials, I started building my own project.

Introducing Rx

I work a lot with Nx in the terminal, but I don’t always remember all the available commands and projects. So my goal was to build a utility that could show me all the projects in the monorepo and list the available tasks for each selected project. I chose this project for a few reasons:

It solved my own problem (I couldn’t find something similar).
There were a lot of interesting concepts in Rust that I could use to improve my skills, such as JSON parsing, file manipulation (read and write), and handling user input.
It allowed me to get my hands dirty and learn as much as possible.

You can check out the Rx code on my Github, but be warned that it is not production-ready code.

What I love

1. Very Clear and Informative Warnings and Errors

One thing I really appreciated about Rust was its clear and informative error messages. Whenever there was a problem with my code, Rust would usually tell me exactly what the problem was and how to fix it. This was a refreshing change from the sometimes cryptic error messages I’m used to seeing in TypeScript.

2. Iterators

Rust’s iterators are much more powerful than those in JavaScript. They are lazy evaluated by default and developers have much more utility functions available. It’s like having Lodash or Ramda as part of the standard library.

In the simple example below, we take first 10 elements from infinit sequence of numbers, use filter function to keep only multiples of 3, multiply them by 3 and sum the resulting numbers into one.

fn main() {
  let sequence = 1..;

  let res: u8 = sequence
                  .take(10)
                  .filter(|x| x % 3 == 0 )
                  .map(|x| x * 3)
                  .sum();

  assert_eq!(res, 54);
}

Another nice example of iterators can be seen in Rust by example book where it is used to implement the Fibonacci sequence.

A complete list of available methods can be found in the documentation for Iterator.

3. Pattern Matching

For JavaScript developers, pattern matching in Rust is like a switch statements on steroids. You’ll find yourself using it a lot to return and transform values based on conditions. Rust will also force you to handle all the branches, which is great for making sure your code is robust and handles all possible scenarios.

let file_result: Result<File> = File::open("nx.json");

match file_result {
    Ok(file) => file,
    Err(error) => match error.kind() {
        ErrorKind::NotFound => panic!("The file you are looking for does not exists."),
        ErrorKind::PermissionDenied => panic!("You shall not pass into this file."),
        ErrorKind::InvalidInput => panic!("Bad arguments for the command, doc."),
        _ => panic!("Something else went wrong, but I was too lazy to deal with it.")
    }
};

There is even JS proposal to add pattern matching into the specification.

4. Option and Result Types

Most of the time, Rust will return Option or Result types instead of throwing an error. This is inspired by monads from functional programming and allows you to handle errors in a more controlled and elegant way.

It plays nicely with pattern matching, allowing you to handle various errors separately. This leads you to handle errors by default (but you can bypass this). It also allows you to compose the flow of your program more effectively. As you can see in the previous code example.

5. Structs and traits

Rust’s variant of objects is a struct. A struct can have properties and methods (both static and instance methods) just like JavaScript objects. And if you want to create some generic behavior that can be reused across different structs, you can create a trait.

For example, in my case, I reused a trait for parsing and deserializing JSON from 3rd party library. I simply added a trait to the struct describing my JSON shape (one line of code), and it parsed the JSON file into a strictly-typed struct that I could easily work with. Which is a awesome compared to JS/TS world.

#[derive(Serialize, Deserialize, Debug)]
struct NxProjectFile {
    name: String,
    tags: Vec<String>,
    targets: HashMap<String, Target>,
}

// later in the code
let project_json: NxProjectFile = serde_json::from_reader(project_file_reader).unwrap();

6. Superb documentation

The Rust documentation is excellent and was a huge help as I learned the language. I was able to find most of what I needed in the docs, and most of the time, I read it in my editor as a tooltip when I needed to check how a method works.

I also found the documentation to be really good for the crates I worked with (Rust’s version of NPM packages).

7. Support in Neovim is great 😅

As someone who uses Neovim as their primary text editor, I was happy to find that Rust has great tooling support in Neovim.

I was able to set up my environment quickly and start working with Rust in just a few minutes thanks to this video Rust setup for Neovim

What I need to get used to

1. Ownership

I still feel a little confused about the ownership logic. When you are passing a variable to a lower scope and when you only reference it (function in lower scope will borrow it).

Luckily, Rust will often tell you what to do to fix the errors.

2.Mandatory semicolons.

In Rust, every statement must end with a semicolon. Otherwise, the expression is considered a return statement (if it is the last expression in the block scope). As a JavaScript developer, I’m not used to typing semicolons anymore, and Prettier handles this for me. So I often forget to type it which is annoying.

3. Low-level nature of the language

When working with Rust you have to sometimes deal with the low-level nature of the language, which is something I’m not used to as a front-end developer.

For example, I wanted to write to a file and overwrite its content. But instead, Rust did always append the content. After a little googling I found out that when you read from a file first, you have to rewind a pointer back to the beginning of the file. Otherwise write operation will append to content to the file.

Conclusion

I enjoyed the short time with Rust. It was a nice experience, and I had fun learning it. I think it takes the good parts from both object-oriented programming and functional programming.

I will probably return to it in the future to play with it a little bit more. Most likely, to polish the Rx utility or maybe when I need to build another CLI utility or when playing with WebAssembly.

How to implement Supabase auth in a browser extension

Fri, 17 May 2024 00:00:00 +0000

Supabase promise an easy authentication without a hasle.

Turns out there was a lot to figure out.

While building Clipio, I had to implement authentication in a browser extension without a regular website. I decide to use Supabase and Supabase UI to setup everthing quickly. And while Supabase does a lot of heavy lifting, there was still a lot of work. And resources for this topic are rare.

In this article, I’ll show you how I handle authentication in browser extension running in Chrome and Firefox.

Quick tip: Upload your extension into the Chrome and Mozilla stores (a signed self-hosted extension will do as well) as soon as possible to obtain stable extension IDs. You will need those for the OAuth setup. So doing this early will save you trouble changing the IDs and redirect URLs later.

Since this article is longer than usually here is the outline for a quick navigation:

Initial attempt

When looking for resources I really couldn’t find any complete guide. The best I could find is the article Supabase login with OAuth for Chrome extensions from Dragos Sebestin.

I managed to set up the basic authentication flow based on the amazing guide mentioned above. However, there was still a lot of work that was not covered.

What I was missing

Email login & Password Reset: handling email-based authentication requires additional changes and updates (mostly for password reset flow).
Session Management: How to handle refreshing the session.
Logout Functionality: Auth flow in the browser extension is spread across several origins. When the user logout we have to ensure all data is cleared.
Cross-Browser Support: When building an extension that can run in multiple browsers (eg. Chrome and Firefox) requires a few more tweaks.
Supabase UI: I decided to use Supabase UI to have the auth flow build quickly, but that requires some tweaking since some flow has to be handled manually from the parent component (eg. password reset).

Basic setup

Following the guide mentioned above, we will open the auth flow in a new tab. In the case of the Clipio, that means checking if the user is logged in before the extension opens. If not the auth flow is initiated.

This code lives in the background script and will look like this:

browser.action.onClicked.addListener(async tab => {
  await openClipio(tab);
});

const openLoginPage = async (type) => {
  await browser.tabs.create({
    url: browser.runtime.getURL('./src/pages/auth.html'),
    active: true,
  });
};

async function openClipio(tab) {
  const storageContent = await browser.storage.local.get(null);

  const { refresh_token } = storageContent;

  const session = await supabase.auth.refreshSession({ refresh_token });

  if (session.error) {
    await Promise.all([browser.storage.local.clear(), supabase.auth.signOut()]);
    await openLoginPage();
    return;
  }

  browser.tabs.sendMessage(tab.id, {
    action: 'open',
  });
}

Now let’s build the auth screen that we will redirect the user to.

The initial version of our auth page will look like this. Please note I have removed the styles and unnecessary markup for the sake of brevity.

const queryParams = {
  access_type: 'offline',
  prompt: 'consent',
}

export function Auth() {
  const [session, setSession] = useState(null);

  useEffect(() => {
    supabase.auth.getSession().then(({ data: { session } }) => {
      setSession(session);
    });

    const {
      data: { subscription },
    } = supabase.auth.onAuthStateChange((event, session) => {
      setSession(session);

      if (session) {
        browser.runtime.sendMessage({ type: 'SET_AUTH', auth: session });
      }
    });

    return () => subscription.unsubscribe();
  }, []);

  if (!session) {
    return (
      <div>
        <h1>Login</h1>
        <SupabaseAuth
          supabaseClient={supabase}
          providers={['google']}
          queryParams={queryParams}
          redirectTo={browser.identity.getRedirectURL()}
        />
      </div>
    );
  } else {
    return (
      <div>
        <h1>Successfully logged in</h1>
        <p>You can now close this tab.</p>
      </div>
    );
  }
}

This example is taken from the official Supabase guide for React and tweaked for the browser extension context.

Now we need to add a handler in the extension’s background script watch for tabs change and finish the auth flow when the extension’s redirect URL is open (code below is taken from Dragos guide).

browser.tabs.onUpdated.addListener((tabId, changeInfo) => {
  if (changeInfo.url?.startsWith(browser.identity.getRedirectURL())) {
    finishOAuthSignIn(changeInfo.url);
  }
});

async function finishUserOAuth(url: string) {
  try {
    console.log(`handling user OAuth callback ...`);
    const supabase = createClient(secrets.supabase.url, secrets.supabase.key);

    // extract tokens from hash
    const hashMap = parseUrlHash(url);
    const access_token = hashMap.get('access_token');
    const refresh_token = hashMap.get('refresh_token');
    if (!access_token || !refresh_token) {
      throw new Error(`no supabase tokens found in URL hash`);
    }

    // check if they work
    const { data, error } = await supabase.auth.setSession({
      access_token,
      refresh_token,
    });
    if (error) throw error;

    // Persist session to storage - background script can become inactive and the session will be lost,
    // we need to be able to recover it by storing the tokens in extension's storage.
    await browser.storage.local.set({ session: data.session });

    // finally redirect to a post-oauth page
    browser.tabs.update({ url: 'https://myapp.com/user-login-success/' });

    console.log(`finished handling user OAuth callback`);
  } catch (error) {
    console.error(error);
  }
}

export function parseUrlHash(url: string) {
  const hashParts = new URL(url).hash.slice(1).split('&');
  const hashMap = new Map(
    hashParts.map(part => {
      const [name, value] = part.split('=');
      return [name, value];
    }),
  );

  return hashMap;
}

Extension permissions

To make this all work, we have to add these permissions to the extension manifest:

"permissions": [
  "identity",
  "tabs",
  "storage"
]

Identity permission is necessary to have access to redirect URL
Tabs permission is required to be able to observe changes in tabs URLs (so we can detect navigation to redirect URLs).
Storage will be used to store the user session in the extension context

With all the code setup, all we have to do now is to enable Google auth in our Supabase project.

Google Chrome:

For Google auth in Chrome I suggest taking a look at this guide in Supabase docs. Since we are using Supabase UI we can skip the code part and skip down to the Configuration section:

Configure the OAuth consent screen in Google Cloud Console (GCC).
Add new credentials of type Chrome extension at the credentials screen.

Mozilla Firefox

To support Google auth in Firefox we have to create a new credentials on GCC.

Visit the Credentials screen again and create a new credential.
As a type select Web application.
Add your extension’s redirect URL (from Firefox build) into the Authorized origins input. You can get the correct redirect URL by calling browser.identity.getRedirectURL(). It will look like this: https://a1b3223966f841b1a78844dc3ac27f75.extensions.allizom.org
Add a callback URL from Supabase (Auth → Providers → Google) into the redirect URI field.

Note for configuring OAuth: If you request only name and email and no sensitive scopes you don’t go through Google verification for your app.

However, if you upload the app logo you will be forced to go through the verification. This came by surprise and I didn’t initially know this was due to the app logo.

Connect Google auth to Supabase

Add the OAuth ID and Client secret to Supabase in the Providers section (use those from Firefox Credentials).
In the Authorized Client IDs field, you have to insert a comma-separated list of all of your client credentials IDs - one for the Chrome extension and one for the Firefox.
You also have to add redirect URLs to your Supabase project. Go to Authentication → URL Configuration and add both redirect URLs (for Chrome and Firefox). Please note that unbundled extensions during dev will have different redirect URLs than the production build.

When using Supabase UI, email signup and login will work out of the box. You only have to configure redirect URLs in your project as we did for Google auth. So if you have finished the previous section you are good to go.

The problem will arise when a users need to reset a forgotten password. We have to make a few changes to our Auth.tsx component and background script to handle the click on the reset link.

The reset link will use redirect URLs, but it will contain one more parameter: type=recovery to help us recognize this is a password reset (Supabase adds this parameter automatically).

We will update our tabs.onUpdated listener in the background script to check for the presence of this param.

browser.tabs.onUpdated.addListener((tabId, changeInfo) => {
  if (changeInfo.url?.startsWith(browser.identity.getRedirectURL())) {
+   const hashMap = parseUrlHash(changeInfo.url);
+
+   const redirectType = hashMap.get('type');
+   if (redirectType === 'recovery') {
+     browser.tabs.update({ url: getLoginPageUrl(hashMap) });
+     return;
+   }
    finishOAuthSignIn(changeInfo.url);
  }
});

If the param is present we will append it together with other params to the auth page URL and open it to finishe the password reset flow.

On the auth page we have to check if we have those params in the URL. If yes, there are a couple of things we have to do:

Take access and refresh tokens from the URL and create a new session
Change the view prop to update_password value in <SupabaseAuth/> component.
Once the USER_UPDATED event is detected in onAuthStateChanged listener we will change the URL to remove the params. This will show a success confirmation message.

export function Auth() {
+  // Get tab URL from the window object
+  const tabUrl = new URL(window.location.href);
+  const type = tabUrl.searchParams.get('type');
+  const access_token = tabUrl.searchParams.get('access_token');
+  const refresh_token = tabUrl.searchParams.get('refresh_token');

  const [session, setSession] = useState(null);

  useEffect(() => {
+    if (access_token && refresh_token) {
+      supabase.auth.setSession({ access_token, refresh_token });
+    } else {
+      supabase.auth.getSession().then(({ data: { session } }) => {
+        setSession(session);
+      });
+    }
-    supabase.auth.getSession().then(({ data: { session } }) => {
-      setSession(session);
-    });

    const {
      data: { subscription },
    } = supabase.auth.onAuthStateChange((event, session) => {
      setSession(session);

      if (session) {
        browser.runtime.sendMessage({ type: 'SET_AUTH', auth: session });
+
+        // Redirect to the auth page without the params to show the success message
+        if (event === 'USER_UPDATED') {
+          window.location.assign(`${tabUrl.origin}${tabUrl.pathname}`);
+        }
      }
    });

    return () => subscription.unsubscribe();
  }, []);

  if (!session) {
    return (
      <div>
        <h1>Login</h1>
        <SupabaseAuth 
 +         view={type === 'recovery' ? 'update_password' : undefined}
          supabaseClient={supabase}
          providers={['google']}
          queryParams={queryParams}
          redirectTo={browser.identity.getRedirectURL()}
        />
      </div>
    );
  } else {
    return (
      <div>
        <h1>Successfully logged in</h1>
        <p>You can now close this tab.</p>
      </div>
    );
  }
}

With this we have finished the Google/email password flows and our extension is ready to accept the users.

Logout

Logout needs a few adjustments as well. We call supabase.auth.signOut() from the background script and clear all user data here. But if we try to login now our Auth page will look like the user is still logged in. The problem is that our Auth page, while part of the extension, is actually treated as different webpage - it has a different context and storage namespace in the browser.

So if we clear the session in the background script we still have access and refresh tokens available in the local storage on the Auth page. This is not good, as it prevents the user to login and can be a potential security issue.

I have decided to solve this by adding one more extra page, this time for logout. It just shows the message to the users that they have been logged out successfully. Once this page is opened we simply call localStorage.clear() to remove the user’s data from here as well.

const LogoutConfirmation = () => {
  useEffect(() => {
    localStorage.clear();
  }, []);

  return (
    <div>
      <h1>You have been logout from Clipio</h1>
      <p>You can now close this tab.</p>
    </div>
  );
};

Session refreshing

The last thing we have to solve is session persistence and token refreshing. Background scripts can become inactive and any global or in memory variables will be lost. We have to persist the session in the extension’s storage and refresh the token when needed.

For Clipio I refresh the token every time users open the extension and logout the user if the refresh method returns any error.

However, during development, I have encountered the issue that the refresh token has become invalid after some time. After a little digging, I have found out that the Supabase is refreshing the token after some time in the background script automatically as well, thus making my persisted refresh token invalid.

I have solved this issue by adding onAuthStateChanged listener to the background script and moved most of the persistence logic here:

supabase.auth.onAuthStateChange((event, session) => {
  if (event === 'SIGNED_IN' || event === 'TOKEN_REFRESHED') {
     browser.storage.local.set((session);
  }

  if (event === 'SIGNED_OUT') {
    browser.storage.local.clear();
  }
});

This will correctly handle all cases when refreshing of token and persist the tokens for the future.

Conclusion

Implementing authentication in a browser extension without a traditional website took me more time than I thought. That’s why I have summarize all the issues in this guide and I hope it will help others.

If you have any questions or run into issues, feel free to reach out. And if you like this article, please share it on social media. Happy coding!

How to add Shadcn UI into an existing React app in Nx Monorepo

Sat, 21 Sep 2024 00:00:00 +0000

When integrating Shadcn UI into an Nx monorepo you can stumble upon few issues.

At least I did when I decided to add Shadcn UI into Clipio. Due to Nx structure, running shadcn init will not work. So I have decided to write this article to help others have a smooth setup journey for Shadcn UI and Nx monorepo using pure React.

Let’s get into it.

Most of the time, you can follow the steps in the Shadcn UI documentation for manual installation. I will briefly describe the steps below for easy follow-up and highlight extra steps relevant for Nx monorepo.

1. Bootstrap the React UI Library

In my setup, I want to have Nx library which will contain Shadcn UI components, I will call it ui. Later I can easily import it to other libs or apps in my monorepo.

Add Nx Library

You can easily add your new library for Shadcn UI using the Nx generator. It will do most of the heavy lifting for you; just double-check the correct imports after the process is complete.

Run this command in your terminal:

pnpm nx g @nx/react:library ui --directory libs/ui --compiler swc --bundler vite

Next, delete the content of the src folder in the UI lib we just generated, and create two new folders:

ui where the Shadcn UI components will live
styles where we will put the global styles for the UI lib

Add a global.css file to the styles folder. We will update it later.

Update TypeScript Config Paths

Now, go to the tsconfig.base.json file in the root of your monorepo. You should see the new path for the UI lib:

"paths": {
    "@shadcn-in-nx/ui": ["libs/ui/src/index.ts"],
    "...": "other paths"
}

Change it to this format:

"paths": {
    "@shadcn-in-nx/ui": [ "libs/ui/src/ui" ],
    "...": "other paths"
}

Using an import path in this format will allow you to import individual components into your codebase like this:

import { Button } from '@shadcn-in-nx/ui/button';

2. Set Up Tailwind CSS

Install the additional dependencies as described in the Shadcn UI documentation:

pnpm add tailwindcss-animate class-variance-authority clsx tailwind-merge

Add icons to your project based on your preferred style of Shadcn UI components. I chose the New York style, so I’m using Radix UI icons:

pnpm add @radix-ui/react-icons

Now, set up Tailwind CSS in your monorepo. Nx provides a handy generator for this task. Run this command for both the UI lib where Shadcn UI will live and the main app:

pnpm nx g @nx/react:setup-tailwind

When initializing Tailwind in the UI lib, the Nx generator might complain it can’t find a stylesheet to update. Don’t worry about it. Copy the Tailwind styles from Step 6 in the Shadcn UI documentation into the global.css file you created earlier.

Also, update the Tailwind config in your UI lib based on instructions from Step 5 in the docs.

Next, update the Tailwind config in your app. Import the Tailwind config from the UI lib and merge it with the app’s config. Here’s how you can do it:

const { createGlobPatternsForDependencies } = require('@nx/react/tailwind');
+ const TailwindConfig = require('../../libs/ui/tailwind.config');
const { join } = require('path');

/** @type {import('tailwindcss').Config} */
module.exports = {
+  ...TailwindConfig,
  content: [
+    ...TailwindConfig.content,
    join(__dirname, '{src,pages,components,app}/**/*!(*.stories|*.spec).{ts,tsx,html}'),
    ...createGlobPatternsForDependencies(__dirname),
  ],
-  theme: {
-    extend: {},
-  },
-  plugins: [],
};

You have to inject styles from global.css into your app, otherwise Shadcn UI components will have broken styles. I have decided to use path alias for this as well. I inserted this line into paths property in tsconfig.base.json:

"@shadcn-test/styles/*": [ "libs/ui/src/styles/*" ],

Then in your app you will inject it like this:

import '@shadcn-test/styles/global.css';

3. Create utils lib with `cn`

Next step is to create a cn utility to merge styles in components. For that I have created a new lib in my monorepo called utils and placed the function here (I have other general purpose utility functions here, so this makes sense for me). In this case I have left the TS path in the tsconfig.base.json as is: "@shadcn-in-nx/utils": ["libs/utils/src/index.ts"].

If you want to generate new lib, run this Nx command: pnpm nx g @nx/js:lib utils and follow setup instructions. Once generated copy cn from Shadcn UI docs inside.

4. Initialize Shadcn UI

Last step before we can add components is to create components.json file into the root of monorepo. Below is example components.json file for a reference:

{
  "$schema": "https://ui.shadcn.com/schema.json",
  "style": "new-york",
  "rsc": false,
  "tsx": true,
  "tailwind": {
    "config": "libs/ui/tailwind.config.js",
    "css": "libs/ui/src/styles/global.css",
    "baseColor": "slate",
    "cssVariables": true
  },
  "aliases": {
    "components": "@shadcn-in-nx/ui",
    "ui": "@shadcn-in-nx/ui",
    "utils": "@shadcn-in-nx/utils"
  }
}

Notice the ui alias. This one is important to ensure generated components are placed in correct folder.

5. Add Components

Now you’re all set to generate Shadcn UI components from the command line. Use this command:

TS_NODE_PROJECT=tsconfig.base.json pnpx shadcn@latest add <"optional component name">

NOTE: Since we're in a monorepo, we have to specify TS_NODE_PROJECT to point to the tsconfig.base.json file. Shadcn UI will look for tsconfig.json by default, but that is not available in the monorepo root.

Your components will be generated in the UI lib and you can easily import them to the main app as well. Import across the components will use path alias as well, which is not optimal in Nx, but I haven’t found any way how to change this. Nevertheless, even if Nx eslint might complain (if you install it) everything will work.

Conclusion

I hope this guide helps you smoothly integrate Shadcn UI into your Nx monorepo. While adding it isn’t overly difficult, there are some Nx-specific steps that can trip you up. By following these instructions, you should be able to get everything working as expected in no time.

How to do an efficient and valuable code review

Mon, 02 Dec 2024 00:00:00 +0000

Do you like code reviews? Or do you hate them?

Have you ever received a code review that left you scratching your head? Have you been wondering if the reviewer even looked at your code? Or worse, have you been on the other side, struggling to provide valuable feedback?

Well, you’re not alone.

Code reviews are often a pain in the ass. They are a form of asynchronous dialog, which makes them really difficult to nail. Lost information, misunderstandings, and unclear intent. All these things can slow down the review and lead to a ping-pong of messages.

In this article, I will share some tips that help me provide code reviews.

TLDR: Be specific. Always say What, Why, and How. Try to help, not show your ego.

Purpose of the code reviews

If code reviews are so challenging, why bother with them at all? The truth is, that code reviews bring several key benefits to a team:

A fresh perspective on the code: When you’re deeply immersed in your work, it’s easy to overlook mistakes or miss important details. A second set of eyes can help catch those issues.
Knowledge sharing: Code reviews allow teammates to learn from each other’s domain expertise and coding patterns. Reviewers can also share their insights and suggest improvements.
Adding context: Senior developers, in particular, may have additional context about the change that can be valuable. The code review process is a great opportunity to share that knowledge.

Some might say that code reviews are meant to catch bugs or bad practices. However, I believe these tasks are better handled by tools like linters, formatters, and automated tests — not humans.

How to prepare code for a smooth review

As an author, you play a crucial role in facilitating an effective review process. By following the tips below, you can help reviewers provide valuable feedback, save a lot of time, and streamline the entire process.

1. Create smaller, focused PRs

Breaking down your changes into smaller pull requests can significantly improve the review process. Smaller PRs are easier to read and understand, increasing the likelihood of a quicker review. Use feature flags to merge changes more frequently while keeping new functionality hidden until it’s ready for release.

2. Provide good descriptions

Before you open a book, you always read the summary on the back cover.

A well-crafted PR description is just like that. It’s essential for context. You should include the what, how, and why of your changes. The description should be the first guide for reviewers, showing them what has changed and what they should focus on.

Of course, a great PR description depends on the context of the changes. Are you changing the color of a button? Then a one-liner is probably enough. Have you spent 2 days hunting down a nasty bug? Then you should probably write an in-depth description of the bug, your process, and why that one line fixed it.

3. Highlight Specific Areas for Feedback

You, as an author, can add comments to the code as well. Use this power.

Otherwise, reviewers might end up nitpicking unimportant things and missing the important parts of the code. Guide your reviewers by pointing out areas where you’d particularly appreciate their input.

Example:
I’ve implemented a new caching mechanism in the UserService class. However, I’m not entirely sure if this is the best way to do it in our codebase, and I don’t like it. But I couldn’t figure out a better way. Any suggestions for improvement would be greatly appreciated.

How to provide a good code review

As a reviewer, your role is to provide constructive feedback that improves code quality and fosters a positive team environment. Here are some guidelines to help you give more effective reviews:

1. Does my comment bring value?

Before you submit a comment, ask yourself this question: “Does my comment bring any value?”.

If it doesn’t, consider whether it’s worth mentioning at all. Avoid nitpicking on trivial issues that don’t impact the code’s functionality or readability but are solely your personal preference. I ask this question before each comment and trust me, there is a huge number of comments I have never sent. Just because you would solve the problem differently doesn’t mean the other solution is wrong.

2. Ask Questions for Clarity

If something isn’t clear, don’t hesitate to ask for clarification. This can lead to valuable discussions and improvements in the code or documentation.

Example:
Why are you binding DOM events to the element using its reference, instead of using React’s native handling? Is there any particular reason?

3. Provide Context and Explanations

When suggesting a change, explain the reasoning behind your recommendations. This helps the author understand the “why” and not just the “what.” And don’t forget to suggest “how” as well. What I really hate is when someone says “I don’t like this” without any explanation or suggestion on how to improve it. And I guess I’m not the only one.

Example:
This reduce method is too complex and very hard to read. I would suggest either moving it to a separate function covered by tests. Or you can instead use a more functional approach and transform it into several atomic steps using a combination of filter and flatMap/map functions.

4. Balance Criticism with Praise

Acknowledge good practices and clever solutions, especially if you added a bunch of change requests. This creates a positive atmosphere and encourages the author.

5. Focus on code, Not the coder

Keep your comments focused on the code itself, not the person who wrote it. Instead of saying “You didn’t handle this edge case,” try “This edge case doesn’t seem to be handled. Consider adding a check for…”

6. Prioritize Your Feedback

Distinguish between must-fix issues and nice-to-have improvements. This helps the author focus on critical changes first. You can use labels or prefixes to indicate the importance of your comments, such as:

Critical: This method may cause a null pointer exception under certain conditions.
Suggestion: Consider using lazy evaluation for better performance in this function.
Nitpick: A for...of loop would probably be better in this case instead of while.

Conclusion

Code reviews can sometimes take a lot of time before all unclear comments are resolved. By following the guidelines mentioned in this article, you can make the process more efficient, valuable, and enjoyable for everyone involved.

My 2024 Post-Mortem: Honest review of a year that didn't go as planned

Tue, 21 Jan 2025 00:00:00 +0000

Let’s make it clear. My 2024? It wasn’t great.

In many ways, it felt like a failure. I had systems, habits, and planning routines in place, yet I ended the year feeling that I had lost track of what really mattered.

At the end of each year, our social media feeds are flooded with “the best year ever” posts. Although it feels good to celebrate wins, these posts can make us feel like failures if we don’t have a six-figure business or thousands of followers.

That’s why I decided to share this honest review, because I want to show it’s ok to make mistakes, that we all struggle sometimes.

And that it is important to learn from our mistakes.

Why didn’t I achieve what I wanted?

No matter how perfect your system is, if your planning is not connected to the bigger picture — a dream, vision, purpose, or whatever — it’s useless. You just do the tasks as they come without much impact. The results won’t compound and you will feel like a hamster on a wheel.

I had that connection, but I lost track of it.

I use a bullet journal for weekly and monthly goal setting and rely on Notion to organize almost everything else. That was one of the problems. My goals were hidden deep in Notion, which made it hard for me to check them regularly.

Here is the full list of the issues that held me back:

I didn’t check my goals regularly. My goals were buried in my digital system, so I couldn’t see them easily. The friction was too big.
I set too many goals. I focused on some, ignored others, and eventually lost sight of what was most important.
I have too complex, hard-to-track goals. I spent too much time and effort to track all the stuff. In the end I didn’t have the willpower to track them at all.
I struggled with prioritization. I spent time on low-impact tasks instead of working on the ones that mattered most. For example, with Clipio, I now see that I should have focused on getting users and releasing the product.
I underestimated my capacity. With three kids, I had less energy and time than I thought. I struggled to find time for work and the energy to push myself.
My goals were digital, but my planning was analog. I love Notion (I’m building a web-clipping tool for it - Clipio), but I rarely wanted to open Notion to check my goals.

Lessons learned for 2025

While 2024 was disappointing in terms of goals and achievements (aside from more time with my family), it was also a year of learning. And I learned a lot during that year, especially during my yearly review.

Moving forward, here’s how I’m changing my approach:

1. Fewer goals, more focus

Instead of juggling a long list of goals and complex tracking mechanisms, I’m simplifying. For 2025, I have one main theme for the year written on a small card. All tasks and projects I decide to do must fit into this theme. On the back, there are a few bullet points with examples. My yearly goals are written on a small sheet of paper that I keep in my diary so I can see them anywhere. And they are easy to track.

2. Focus on what I can control

I will focus on what I can control. I can control how often I write, how many calls for papers I submit, when I go to sleep, but I cannot control how many followers I get.

3. Analog over digital for planning

While Notion is great for storing knowledge and writing, my goal planning will now be analog. It is easier to see, review, and act on a paper plan. A simpler, low-friction system means I will check my goals more often.

4. Build stronger systems and habits

I set my mornings for exercise or writing before I get my kids ready for school.
I set time blocks for tasks. For example, instead of a task like “Write a blog post,” I schedule “Write for 30 minutes.” Short, timed tasks feel less hard to start and can fit into any day. Being consistent will help me produce more content.
I plan to focus more on my health (which sucks ever since I started working from home during Covid) — regular morning exercise, after-lunch walks (even when home), more veggies.
I will get proper sleep (good, long sleep is the ultimate productivity hack).
I will regularly review my goals on paper to stay connected to them.

A key idea: it’s okay to fail

If your 2024 didn’t look like the highlight reels on social media, you are not alone. The internet can make it seem like everyone is winning: building six-figure businesses and reaching huge milestones. But behind the scenes, many of us are just trying to figure things out.

And that is okay.

Don’t give up. Keep testing new ideas, keep adjusting, keep learning, and most importantly, keep moving forward.

Here’s to a more intentional 2025.

4+1 ways how to handle errors in your code

Sat, 29 Mar 2025 00:00:00 +0000

We, developers, love the “happy path”.

We create a code that happily assumes everything will go perfectly well. But reality isn’t so kind. Servers crash, APIs fail, developers make mistakes, and users do unexpected things.

Errors will happen in our apps. So let’s stop ignoring them and instead be ready to deal with them. In this article, I will walk you through 4 + 1 ways how to handle errors in your code.

The Consequences of Poor Error Handling

We all know errors in the apps are bad. So, why do we still treat error handling as an afterthought? When we ignore proper error handling, the impact is felt everywhere:

Terrible UI/UX – Users have no clue what is happening in the system, what went wrong, or how to fix it.
System instability – Critical errors can be silenced and ignored, or tiny issues make the app unusable.
Debugging nightmares – Hunting down silent failures is frustrating and time-consuming.

So, how can we deal with errors? Let’s break down the common (and sometimes bad) approaches to error handling.

The many ways to handle errors

1. Ignoring errors and hoping for the best

Sure, not all errors are equal.

Some errors, like failed analytics events, are harmless and can be ignored. But, ignoring critical errors can be catastrophic. Silent failed API calls can lead to users losing data. Generic error messages don’t help users recover, as they don’t know what is happening. They also can’t report the bug properly because they have no extra info.

2. Returning weird values

A practice I’ve seen more times than I’d like.

Some developers return false or -1 to indicate failure instead of using proper error handling. This creates confusion because the caller has no idea what false means in that context.

Is the result false?

Or did the function fail?

If it failed, what went wrong?

This approach produces a bunch of questions and confusion. If something goes wrong, be explicit. This also makes type-checking a nightmare when success returns structured data and failure returns a random value.

3. Throwing errors without proper handling

Ok, so ignoring errors or returning weird values is bad. Let’s just throw an error and move on, right?

Well, not really.

Throwing an error isn’t bad by itself. But without solid error handling in the app, you’re just throwing errors randomly. Be careful with that.

Especially if your code is used by others. IDEs won’t show if a function might throw—they only show the return value (the happy path). Developers can miss that the function might throw and skip the error handling (unless they know the internal logic).

4. Using `try...catch` blocks

Using try...catch around code that might fail is a good start. But the question is: What happens after catching the error?

Options vary based on context:

Handle it immediately – Show a friendly message to the users, retry a request, etc.
Rethrow the error – Useful if a higher-level handler should deal with it. But make sure such a handler exists.
Return structured error objects – Help us pass errors along without breaking function contracts.

Note about Promises: I'm not giving Promises a standalone section since they are similar to try...catch. While more explicit, we know a promise can be rejected, errors can still be ignored (and they often are).

Let’s stop at the last point: Return structured error objects and have a closer look. We can actually treat errors like — well — not errors.

Instead of throwing and spreading panic, we can treat them as normal data. Like returning a string or an object from a function.

Bonus: Treat errors as data

Throwing is a side effect that breaks function purity. A better approach is to treat errors as data. Acknowledge that something can go wrong and describe it. This way, a function always returns something predictable and prevents crashes.

Why is it better?

Humans love certainty. We tend to ignore the unknown.

By returning an error as a valid value, we force devs to deal with it or consciously ignore it. Of course, some errors are unpredictable (like server down or out of memory), but most can be caught with handlers in the right spots.

This approach has several pros: It’s explicit, transparent, and eliminates surprises. Other devs see both success and error as possible return values. It’s clear that the code can fail and how.

This helps us write better, more robust code.

Here is an example from my work. I had to handle an API response, nothing fancy, just showing the data or the error state. The problem was that I had to use a different UI for various error states and, in some cases, make another request. But I had no clue what errors could be returned from the API. I had to manually simulate various conditions to see possible values. And I’m not sure that I have handled all the cases. If the error as a data approach was used, I would see what errors are possible and how to handle them.

Examples of error-as-data patterns

Object-based approach (eg. used by Supabase):

A function always returns an object with optional error and data properties. In case of failure, the function populates the error property instead of throwing. The caller checks for error first.

If there is no error, we can safely use data. Otherwise, we handle the error our way.

function fetchUsers() {
  const { error, data } = await apiClient(`/users/`);
  if (error) {
    handleError(error);
    return;
  }
  return data;
}

This also works well with TypeScript, which forces us to handle possible errors.

Result pattern

Instead of a plain object, we return a class (usually called Result or Either). It works in a similar fashion as the object-based approach mentioned above. The class has a property that is used to check if the result of the function is an expected value or an error. But since it’s a class, it often has extra utility functions baked in.

This pattern has several benefits:

Composition – You can chain functions that return/accept the Result class.
Safety – You can pass the Result around safely, not needing to worry about errors.
Helpers – Since the Result is a class, it often comes with various utility helpers. Methods like map, unwrap, etc. so you can work with the result in a more functional way.

function readFile(path: string): Result<string, 'invalid path'> {
  if (existsSync(path)) {
    return Result.Ok(readFileSync(path));
  } else {
    return Result.Err('invalid path');
  }
}

const result = readFile('test.txt');
if (result.isOk()) {
  const text = result.value;
} else {
  const err = result.error;
}

// OR using helpers
return result.map(val => firstLettersToUppercase(val)).map(val => val.replace(' ', '_'));
// If the reading of a file was successful, we can map over the result
// and transform it with the provided function.
// In case of an error, the map will be ignored. We can chain and compose multiple steps
// like this and handle the potential error state only at the end.

Some languages have this built-in (like Rust). And hopefully, JavaScript will have this too one day. Meanwhile, we can use polyfills or libraries like ts-result-es.

The downside? More boilerplate. But unless your code is very small, the pros outweigh the cons.

Conclusion: Think about errors before they happen

Something will go wrong. Maybe not today. Maybe not in your dev environment. But one day it will.

How you handle that defines your system’s robustness.

Don’t push problems up the call stack or pretend they don’t exist. Handle errors intentionally.

When you model errors as data:

Your code is more predictable.
Your system is easier to debug.
Your team shares a clear idea of what failure looks like.

So next time you’re choosing how to handle failure, remember: a bit of verbosity beats a silent crash.

Reflecting on my indiehacking journey building Clipio

Tue, 03 Jun 2025 00:00:00 +0000

After over a year of development, I finally launched Clipio — a browser extension that lets you save web content effortlessly into Notion. This article is a reflection about my journey with highs and lows and lessons I have learned the hard way.

First some numbers:

Over 1 year of development, 18 upvotes on ProductHunt and #33 product of the day, made exactly 1 sale.

Not an impressive numbers.

But here’s the thing: I don’t count it as a total failure either, because I have learner a ton of things I wouldn’t otherwise.

The good things

Let’s be real: the money didn’t pour in. But Clipio still gave me something more important — validation, exprience and connections.

That first sale was an important validation for me that I can make money online (but probably not with Clipio).
I use the product myself — and it solves a problem I actually care about.
I walked away with a huge list of blog and content ideas - both technical and non-technical.
I learned a lot knowledge in backend, software architecture, product management, sales and marketing.
And the most importantly, I’ve got few concrete ideas for what to build next — and how to do it better.

The bad things

Not everything went smoothly. Here’s a breakdown of the biggest mistakes — and what I learned from each.

1. The ProductHunt launch

I put in the effort, tried to stir some buzz. But in the end it didn’t worked.

18 upvotes. Very small traction.
These days all the top products were all AI-based — it almost seems like if you don’t have AI, you have no chance.
Without being featured or a huge following before the launch, you will most likely don’t get much upvotes.

Lesson: Be better prepared. Build a following before the launch. And yes, AI-first products are dominating PH right now.

2. I suck at marketing

I’ll admit it: I struggle with marketing.

It feels awkward and is heavily outside of my comfort zone. I tried with things, but nothing really worked.

Aside from that I had a hard time putting together a good value proposition to actually get the interest and explain the value to the potential users. I fully realized this when preparing for ProductHunt launch when I spend unreasonable amount of time creating description for the launch. This can signal that the product is not a good fit as well and might need some pivot.

Lesson: Think about value proposition first and validate that. Nex time I will try to create fake ProductHunt lunch () to realize what am I actually offering and selling.

3. I have built a product for bad audience

I use Clipio and it solves my own problem. That’s the first step to build good and successful product. But you still need to sell it. Pair that with my marketing skills and that’s where I met some troubles.

My target audience was almost completely outside my network.
I mostly know developers — not exactly heavy Notion users.
I failed to generate interest or even validate interest early.

Having poor overlap between my audience and my target group didn’t really help with marketing the product. And I also had a problem deciding whether I want to pivot and start writing for Notion users or stick with my current audience and not market my product very well.

I had only small overlap between my network and Clipio target audience, making marketing harder.

Don’t get me wrong. I totally believe you can build a great product even for group outside of your network. But it will be harder.

This is called “Founder-Market Fit” and you can read more about it for example from Jorge Medina in his post on LinkedIn

Lesson: Build for an audience you already understand and have access to. For me, that means devs, indie hackers, or small business owners — groups where I already have reach. It will make marketing and selling much easier.

4. I lost motivation as the development dragged on

I underestimated how much time it will take me to build a Clipio. Initially I thought I will build a first good version in 3 months. But slowly this become a year.

As development dragged on, my updates slowed. Initially I posted daily or weekly about my progress on social media and send a monthly update to the people on the waitlist. But as the time progressed my frequency dropped. In the end it almost stopped.

This was just another proof that my motivation dropped a lot over the long year development.

You should really try to ship some thing as fast as possible and get feedback/validation from the users. Without it, your energy will slowly vanish (and you might just waste your time).

Lesson: Ship fast while you’re still excited. Consider validating something in a week or two, then double down or move on. Momentum matters.

Lesson: You’ll always underestimate how long it takes. Be ready to cut scope and compromise. Use existing tools, even if imperfect.

5. I Got Stuck on Tooling

At one point, I spent hours debugging weird build issues — Nx configs, Tailwind quirks, Vite version mismatches, etc. So instead of a productive day I was fighting issues without any value.

Lesson: Stick to battle-tested stacks. Avoid unnecessary custom configs. Don’t build what you can buy — unless it’s your core value prop.

Conclusion

Building a Clipio was a great experience and I have learned a lot. Especially today, with the AI hype this was a great way to broaden my skills and validate that I can build something people will want to use.

Of course I have made a mistakes along the way, but I have learned a valuable lessons thanks to that. I have wrote this article to reflect on this journey and share those lessons with you so you can learn from my mistakes.

Reverse engineering Linear - part 1: Header

Sun, 07 Sep 2025 00:00:00 +0000

With the advancement of AI, I’ve decided to try something different from building. Something that was previously very hard. I threw an AI at production, minified JavaScript code, and reverse engineered it back to readable JSX files and analyzed how it’s built.

The goal: Learn from top-tier software engineers and share valuable lessons with others.
Target: Linear - software I deeply admire for its engineering and UX quality.

This article is just the first in a series of articles I plan to write about Linear — as what started as a simple investigation turned into a deep rabbit hole.

Why Header?

There is a lot I want to explore in the Linear codebase. Initially, my plan was to dive into Linear’s actions and keyboard navigation. However, while digging into the UI, I realized that even something as ordinary as the header has a few interesting ideas to uncover.

So I have decided to start small and with something easier to digest before we dive into the more complex topics.

Anatomy of the Header

Let’s first have a look at the header and key components, so we know what we are dealing with in the rest of the article.

The header has 4 main parts:

Title - children in React so it can be almost anything, most of the time it contains context-aware breadcrumbs showing the path from top view to the current location.
Tabs - some views can have tabs, which usually contain different custom views, filters, etc. This section will break to next line on smaller screens.
Side - group of components on the right side of the header, usually icon buttons with some quick actions.
Subheader - not always present, usually contains filters.

Some more variants of the header:

What have I found interesting

1. Next level of responsive design

Linear app works and looks great anywhere — from smartphones to large screens. Most of it is achieved through traditional CSS media queries. Either used directly in CSS or via React hooks (using matchMedia DOM API in the background).

But Linear goes beyond traditional CSS breakpoints.

There is a ResponsiveSlot component used in the header (in the Side slot). The purpose of this component is to hide its content based on available space in the wrapping ResponsiveSlotContainer component.

It doesn’t use breakpoints. Instead, it calculates available space using a system of resize observers and hides the content of the slot based on its priority.

Here is how it works:

priority prop defines how important that slot (its content) is for the app. Lower priority slots are hidden first when there is not enough free space.

Each slot registers itself via React context to a manager (MobX store) with all necessary info about the slot, see code below.

registerSlot(name, priority, ref) {
  const element = ref.current;
  if (!element || manager.slots.get(name)) return;

  // Each slot has a resize observer attached to it.
  const resizeObserver = new ResizeObserver((entries) => {
    const entry = entries[0];
    const inlineSize = Math.ceil(entry?.borderBoxSize[0]?.inlineSize ?? 0);

    if (inlineSize > 0) {
      const slot = manager.slots.get(name);
      if (slot && slot.width !== inlineSize) {
        runInAction(() => {
          slot.width = inlineSize;
          calculateVisibility(manager);
        });
      }
    }
  });

  resizeObserver.observe(element, { box: "border-box" });

  // Details of the slot are stored in the manager as well for later use
  manager.slots.set(name, {
    name,
    priority,
    ref,
    observer: resizeObserver,
    width: element.offsetWidth,
    visible: true,
  });
  insertSlotByPriority(manager, name, priority);
}

Resize observers are also attached to the containers. There are actually 2 nested containers to detect when the content actually overflows the available space (this is done with a bit of CSS flexbox magic).
If there is a change in conditions — resize event detected by observer, change of priority or registering of new slot, etc. — the manager will recalculate available space. And if needed, starts hiding lower-priority items dynamically (renders null), independent of breakpoint or position across all the header elements.
This avoids rigid media queries (works more like container query) and ensures that essential controls are always visible.

Play with this demo in the CodeSandbox.

Over-engineered?

Maybe. But definitely clever and beautiful. It shows Linear’s attention to detail and design. Ensuring that relevant stuff is visible and less important goes away if there is not enough room.

Sadly, I found only a few usages across the app in the code. And after careful analysis, I believe those cases are not working due to the CSS setup. There is a missing min-width: 0 on the top container, which forbids it to shrink below the size of the inner one. Effectively never triggering the hiding.

Not sure if this is a bug or if this is intentional (if someone from Linear reads this, please let me know). So I had to make a few adjustments to make it actually work as it is supposed to in my demo.

Nevertheless, it’s a great example of React composition on a bigger scale. It works out of the box, you just wrap some component in the header with ResponsiveSlot and that’s it. No props drilling or complex state management. And since the context is initialized in the Header component, you don’t have to deal with extra providers and similar. You just use the ResponsiveSlot as any other component.

2. Local State with MobX

Linear is using MobX as a state management tool (I will definitely cover state management in some later article). I have seen and even built a bunch of apps with MobX. Most of them had 1 or more large global states that could be consumed anywhere and usually it became quite a mess very soon (and a testing hell).

Remember the registry for ResponsiveSlot in the previous section? It is small MobX store. This store is created via a factory function when the Header component renders and is then saved in the React context to make it available to other components.

This has several benefits:

No state leakage - the store is private and used only in the Header component.
Small, purpose-specific state - which makes it easy to reason about.
Still gives you the benefits of MobX - reactive updates only when truly needed, which is great for performance.

This is a clever pattern. It blends the simplicity of local state with MobX’s reactivity. In Clipio, I use small state that I inject into the components to avoid usage of global objects. But having it like this directly in React never crossed my mind.

Here is a simplified example:

// Factory function to create MobX store with properties and
// methods to change them.
function createResponsiveSlotManager() {
  const manager = {
    names: [],
    slots: new Map(),
    visibility: new Map(),
    isVisible(name) {
      const slot = manager.slots.get(name);
      return slot?.visible;
    },
    // ... other methods
  };

  // Wrap store in MobX
  return makeObservable(manager, {
    names: observable,
    slots: observable.deep,
    visibility: observable,
    updateContainerWidths: action,
    // ... other methods
  });
}

// Define React context provider and inject the store
function ResponsiveSlotProvider({ children }) {
  const responsiveSlotManager = useMemo(() => createResponsiveSlotManager(), []);

  // ... code left out for brevity

  return (
    <ResponsiveSlotContext.Provider value={responsiveSlotManager}>
      {children}
    </ResponsiveSlotContext.Provider>
  );
}

3. Dynamic hiding of the tabs

Tabs in the header don’t look special at first glance, but then the fun starts when you have too many to fit into the view. The tabs that won’t fit are hidden and instead a button to open a popover with the complete list of tabs appears.

There are a few details I really like:

The trigger shows the number of hidden tabs, but if the active tab is one of the hidden ones, it will be visible as a label instead.
In the popover you can see all tabs and you can easily reorder them using drag and drop (btw Linear uses DnD kit for drag and drop interactions).
You can also reorder the tabs inline - in such case all tabs will appear and you can drag and drop them in the list.

I have seen and even built dynamic hiding of the list based on available size of the container. Most of the time the solutions weren’t perfect and at certain edge cases they broke. But I didn’t manage to break it even once in Linear (I really tried). And the solution is very performance-effective as well.

Schema of how the tabs hiding work

Tabs are hidden using CSS visibility: hidden to make the extra tabs invisible, but they are still in the DOM and occupy the exact same spot (overflow is set to hidden).
- This avoids extra layout flickering that might appear in solutions that really remove the items from the DOM (or use display: none).
- It also makes it easy to enable drag and drop and show entire list for reordering.
The popover trigger (that 2 more button) is then absolutely positioned after the last visible item, and its size is taken into the calculations when the app decides if another tab should be hidden or shown.
The width calculation happens when the active tab or the actual tabs change (and it happens in the useLayoutEffect hook). And then when the size of the tabs container changes (using a resize observer for that).

Below is simplified version of the code that calculates which tabs should be hidden and what should be the position and size of the popover trigger button at the end:

function calculateTabLayout(containerRef, activeFacetIndex) {
  const container = containerRef.current;
  const containerWidth = container.offsetWidth;
  const moreButtonWidth = TAB_GAP + MORE_BUTTON_WIDTH + NEW_VIEW_BUTTON_WIDTH;

  // Special handling for active tab - ensure it's always visible
  const activeTab = container.children[activeFacetIndex];
  const activeTabWidth = activeTab.offsetWidth + TAB_GAP + DROPDOWN_WIDTH + NEW_VIEW_BUTTON_WIDTH;

  // We pick the smaller of the 2 - available space or active tab width
  const maxActiveWidth = Math.min(activeTabWidth, containerWidth);

  let currentWidth = 0;

  // Iterate over all tabs except the last one (that's why subtracting -2 - for a new view button)
  for (let i = 0, max = container.children.length - 2; i <= max; ++i) {
    const child = container.children[i];
    const isLast = i === container.children.length - 2;

    if (child instanceof HTMLElement) {
      const childWidth = child.offsetWidth;

      // The clever part: dynamically calculate required space
      // Default: reserve space for "more" button
      let requiredSpace = moreButtonWidth;

      if (isLast) {
        // Last tab only needs "new view" button
        requiredSpace = NEW_VIEW_BUTTON_WIDTH;
      } else if (i < activeFacetIndex) {
        // Before active tab: ensure active tab fits
        requiredSpace = maxActiveWidth;
      }

      // Decision point: hide this tab if it won't fit with required space
      if (currentWidth + childWidth + requiredSpace > containerWidth) {
        return {
          hideAfterIndex: i,
          buttonLeft: currentWidth,
          buttonMaxWidth: i <= activeFacetIndex ? maxActiveWidth : moreButtonWidth,
        };
      }

      currentWidth += childWidth + TAB_GAP;
    }
  }

  return { hideAfterIndex: -1 }; // All tabs fit
}

What I have learned

I have picked up a bunch of interesting ideas and inspiration just from the header that I will definitely use in the future (and some I have already used).

Dynamic hiding of components based on available space - smart usage of CSS instead of relying too much on JS.
An example that a MobX state doesn’t always have to be global, but you can encapsulate it in context (which makes testing setup so much easier)
Composition is one of the key principles in React and Linear does it really well:
- Small utility hooks (for measuring element size, checking visibility etc.)
- Components to drive animations or handle heavy-lifting for menus and actions.
- But also bigger components that create logical blocks on the page (like header in this article) and are often bound together by small focused React context to carry state (it is used a lot from what I have seen so far).

Coming next

Digging into Linear’s codebase is really fun and a great source of learning. But this is just a beginning so stay tuned for part 2, where I will dig into their context-aware actions and amazing keyboard support.

How I plan my year (after ruthlessly simplifying the process for 5 years)

Mon, 19 Jan 2026 00:00:00 +0000

Every January, I have a tradition. I rent a small cottage in the middle of the Czech Republic (hotel Kouty, absolutely amazing place), disconnect from everything, and spend a weekend reflecting on the past year and thinking about the year ahead.

This year was my fifth time doing it. And I’ve finally found a system that works.

In the past, I always thought I had to get the most out of the weekend. I came prepared with pages of questions, various planning frameworks and templates. I would spend hours filling them out, setting quarterly goals, and creating elaborate tracking systems. I came back home with a plan and felt productive, but also tired and overwhelmed. Most of it was abandoned by February.

So each year, I simplified.

I ruthlessly cut what didn’t work and intentionally did less. And after 5 years, I ended up with something I can actually stick to. A process that’s more about thinking than filling out templates.

This year, I went with 3 priorities for the weekend:

Reflect – Look back at the past year. What worked and what didn’t? What gave me energy?
Relax – Rest and chill. I deliberately scheduled most of my Saturday to do nothing. But as you’ll see, this is the most productive part of the entire process.
Realign – Check my direction. See what’s important, where I’m heading. Return home with energy and clarity.

Reflect

Reflection is where the weekend starts, though this time I started earlier during Christmas vacation. I went over my notes from the year to see what resonated with me — wins and failures, repeating patterns, etc. By the time I arrived at the offsite on Friday evening, I just needed to wrap it up.

I use Bullet Journal as the main source (previously I tracked most of this in Notion). Throughout the year, I capture events, tasks, and notes. At the end of each month, I review and write down the key stories, ideas, and lessons. This ongoing practice makes the yearly reflection much easier — I’m not trying to remember twelve months of life from scratch.

Some of the questions I ask myself:

What were my biggest achievements and key events?
What went well this year?
What didn’t work?
What gave me energy?
What drained me?
What am I grateful for?

I don’t overthink this part. The goal is to get an honest picture of the year, not to write down every single detail. You can see the complete list of questions in my Notion template.

Relax and Realign

On Saturday morning, I thought about the year ahead. Not about specific goals, but the general direction. What do I want to do (in my career or as a hobby)? What changes would make my life better? How can I support my family? Where do I want to steer my career? I wrote whatever came to mind. Questions, ideas, half-formed thoughts. I didn’t try to structure it too much at this point, just bullet points.

I also did a personal SWOT analysis. I don’t do it every year, but it’s useful when I feel stuck or when I’m considering bigger changes (like AI taking over the world). Another great tool for this purpose is Ikigai.

That was it for most of the day.

The relaxing part started with a late and long breakfast (hotel breakfasts are the best). I didn’t have any specific plans. A walk in the snowy countryside. Sat on the couch, enjoyed the silence, the view, and good wine. Sauna in the afternoon.

Doesn’t sound like hard work, right? At first I just relaxed and enjoyed myself. It didn’t take long for my mind to get calm and bored. And silence and a bored mind are the best tools for thinking. I tried calm music on Friday but got irritated and turned it off — I enjoyed the silence more.

I let my mind wander across the topics I had set in the morning. This sounds almost too simple, but it’s the part that matters most. Things that felt unclear suddenly made sense. A lot of really cool ideas came to me during this time — things I’m keen on trying out during the year. Interesting connections, realizations about my life, possible directions, and more. And I took notes.

A lot of notes.

In the evening, I sat down again and wrote more concrete things. Not detailed goals, but themes and priorities. A few specific projects I wanted to tackle. Systems I wanted to put in place.

From goals to systems

Sunday morning was for wrapping up. I reviewed what I wrote on Saturday, what I wanted to focus on this year, and created specific goals from that.

One of the biggest changes in my approach was shifting from specific goals to systems and processes.

A few years ago, I would set goals like “Write 8 blog posts this year.” Sounds concrete and measurable (and it is). But goals like this often don’t work. At least they don’t for me. By March, I’d be behind schedule and feeling guilty about it.

Now I think about it differently. Instead of “Write 8 blog posts”, I commit to a process: two hours a week dedicated to writing. The output takes care of itself. Some weeks I make great progress, some weeks I don’t. But the system keeps me moving forward. I focus on how to make progress, not just what to achieve.

Setting goals is the easy part. The hard part is figuring out how to actually make progress (I do admit that years of experience as a scout leader and leadership instructor help).

Most people (and companies) get stuck there. They write down what they want to achieve, attach unrealistic deadlines, and call it a yearly plan.

That’s where systems come in. It’s not enough to say “I will write more.” You need to figure out how to make it happen. And that’s where I focus most of my energy during the planning weekend.

What does a system look like in practice?

A fixed schedule for writing (two hours every Saturday morning, or in my case 30 minutes in the morning before kids wake up)
Arranging time with my wife so I can focus on side projects
Rules I commit to follow (no computers or phones after 21:30)
A process for tracking interesting conferences and submitting talks to each one

This shift made planning feel lighter. I’m not setting myself up for failure with arbitrary targets. I’m building habits that compound over time.

Tools I use

Over the years, I’ve tried many tools. Here’s what works (or has worked) well for me:

My yearly review Notion template – This is what I use these days (last 2 years). Year Compass is a great tool, but too verbose for me. So I have created my own condensed version. Just the essential and relevant questions. It fits on a few pages, which makes it easy to review throughout the year. I also added a few questions from other sources.
Year Compass – I used this for the first few years. It’s a free booklet with reflection questions and planning prompts. Well-designed, but I found it too long and verbose. And some questions weren’t that relevant to me.
Set of questions from Daniel Gamrot – These are great questions when thinking about your life and where to steer it. It’s in Czech, but translating it with AI shouldn’t be a problem these days.
Yearly review from Dickie Bush and Nicolas Cole – You have to add your email to get access, but it’s worth it. I took a bunch of questions from there for my review as well.
Questions from FS.blog – Another source of great questions if you want to dive deep. Same as above, you will need to provide your email for this one (but you should read the FS.blog newsletter anyway).
Bullet Journal – For tracking daily and weekly progress. Nothing fancy — just a simple notebook where I capture events, tasks, and notes. At the end of each month, I review and synthesize the key stories. This is the foundation for my yearly reflection.
Pen and paper – For the weekend itself, I prefer writing by hand. It’s slower, which is good. It forces me to think before I write.

What I cut over the years

Equally important is what I stopped doing:

Questions that weren’t relevant
Too many goals – we have a tendency to overestimate our free time and underestimate how long something takes. This is another common mistake when planning. I used to have many goals. Now I usually stick to 1-3 big yearly goals.
Detailed quarterly goals – Too rigid. Life changes too fast.
Elaborate tracking systems – I spent more time maintaining them than benefiting from them. I now only track what really brings me value.
Multiple planning frameworks – Combining different methodologies just created confusion.

The pattern is clear: anything that required ongoing maintenance got cut. The best system is one you actually use.

Making it work for you

I’m not saying my approach is the right one for everyone. But if you’ve struggled with yearly planning — if you’ve set goals in January that felt irrelevant by March — maybe the answer isn’t a better framework. Maybe it’s simplification.

Find a way to give yourself uninterrupted time to think. Remove the inputs. Let your mind wander. See what surfaces.

You might be surprised how much clarity comes from doing less.

Tomas Pustelnik

What every JavaScript developer should know about HTML and CSS

Use HTML elements with correct semantics

Learn how to use form elements

Wrap forms in <form> element

Always use inputs with labels

Use type attribute on a button element

Make things accessible

Always provide styles for focused interactive elements

Use correct elements for interactions in the app

Don’t nest buttons and links

Box model and sizes

Box-sizing CSS property

Inline elements have extra space in between them

Margin collapsing

Use appropriate sizing units

Stacking context

CSS specificity

Conclusion

Don't ignore Fieldset and Legend HTML elements

What are they good for?

Some downsides

Conclusion

Tools & resources I use for front-end development

Basic stuff

CSS

Performance and optimizations tools

Accessibility

Honorable mentions

The end

What have I learned when releasing Qjub

TLDR - Lessons I have learned

Full story

Consistent work on stuff that matters

Releasing it

Moving forward

Optimizing CSS for faster page loads

Why loading time matters?

How does CSS affect load times

Limit size of your stylesheet

Use critical CSS

Lazy-load stylesheets

Use code-splitting for your stylesheets

Split CSS based on media queries

Page based code-splitting

Component based code-splitting

Summary

What I read to stay up-to-date

What is my workflow

Blogs

Personal sites

Other

Newsletters

Twitter

What you might not know about sizing in CSS

How does height: 100%; work

How sizing in Flexbox works

Beware of the extra padding and border

Large grid items breaking from the grid layout

Summary

Freezing development of Qjub

Why I’ve decided that way?

1. Writing a blog makes more sense to me

2. The unclear focus of Qjub

What it means for Qjub and its users

Next steps

Real-world CSS vs. CSS-in-JS performance comparison

TLDR:

What I measured and how

Network comparison

Coverage

Lighthouse performance audit

Performance profiling

Comparing user interaction

Conclusion

How and why I've migrated from Netlify to Cloudflare

Migration steps

Build plugins

Include code snippets during build time

Domain transition

Wrap forms in `<form>` element

How does `height: 100%;` work