DEV Community: Rafael Calpena

Common Improvements to your Next.js, Tailwind and Storybook Stack

Rafael Calpena — Fri, 01 Sep 2023 21:02:08 +0000

In the previous article of this series, we saw how to create a Next.js app with Tailwind and Storybook on a Stackomate dev-container. Now, we will see some common patterns and improvements that can be used to make your development workflow easier.

Avoid Import Path Issues

⚠️ It seems that using the default @ alias for Next.js may create some problems when importing such files in the Storybook server. Replacing them with relative paths, such as .., seem to have fixed the issues. We may revisit this issue in the future for further investigation.

Add Support for SVG Imports

One of the quickest ways to add support for SVG imports is to use the svgr cli. The cli will transpile SVG images into React components which can be used directly in your code.

Create a folder in the src/ directory of your Next.js project called svgr;
Move all of your SVG images to the src/svgr folder;
Optionally install the @svgr/cli package as a devDependency:

npm install --save-dev @svgr/cli

Run npx -y @svgr/cli --out-dir src/svgr -- src/svgr;

ℹ️ You should re-run this command whenever a new SVG file is added to the src/svgr folder.

ℹ️ You may also create a npm script in the package.json file to automate calling the command above, such as:

{
    "scripts": {
        "svgr": "npx -y @svgr/cli --out-dir src/svgr -- src/svgr"
    }
}

Import the generated javascript files from the src/svgr folder into your project:

import MyCustomIcon from '../svgr/my-custom-icon'

Use the `clsx` Library (Recommended)

The clsx library facilitates the construction of conditional classes, by receiving strings, objects and arrays. Here are some examples taken from its documentation:

import clsx from 'clsx';

clsx('foo', true && 'bar', 'baz');
clsx({ foo:true }, { bar:false }, null, { '--foobar':'hello' });
clsx(['foo', 0, false, 'bar']);

To install it, run npm install --save clsx in your application root folder.

Use the `twMerge` Library (Optional)

The twMerge (tailwind-merge) library "merges Tailwind CSS classes without style conflicts" source. Here is an example taken from its documentation:

import { twMerge } from 'tailwind-merge'

twMerge('px-2 py-1 bg-red hover:bg-dark-red', 'p-3 bg-[#B91C1C]')
// → 'hover:bg-dark-red p-3 bg-[#B91C1C]'

To install it, run npm install --save tailwind-merge in your application root folder. The maintainers of twMerge have also made a guide explaining about when and how to use it.

Manage Fonts with `@next/fonts`

Using @next/fonts includes benefits such as latency reduction and enhanced privacy. It is also built similarly to the component architecture used by React.

Our Recommendation:

Create a src/fonts folder and an index.tsx file, and export all fonts in such file.

// src/fonts/index.tsx

import { Rubik_Iso } from 'next/font/google'
import { Inter } from 'next/font/google'

export const rubikIso = Rubik_Iso({ subsets: ['latin'], weight: "400" });
export const inter = Inter({subsets: ['latin']})

Consume the exported fonts in your components

// src/stories/Header.tsx

import { rubikIso } from '../fonts';

// ...

export const Header = () => (
  <header>
    <div className={clsx(`bg-red-500 dark:bg-yellow-600`, rubikIso.className)}>
    // ...

Create a `SharedDefaults` Component

Creating a SharedDefaults component will provide a common component to be used both by Next.js and Storybook servers. This is a good strategy to declare fonts and themes, for example, as they can be referenced in your App component and stories.

Create a src/components folder;
Create a SharedDefaults.tsx file which accepts children props;

ℹ️ The SharedDefaults component may use Tailwind classes and @next/fonts. For example:

// src/components/SharedDefaults.tsx

import { rubikIso } from "../fonts";
import clsx from "clsx";
import { ReactNode } from "react";

export const SharedDefaults = ({children}: {children: ReactNode}) => {
    return <div className={clsx("bg-purple-800 text-white", rubikIso.className)}>
        {children}
    </div>
}

Wrap your Next.js components with the SharedDefaults component.

// src/app/page.tsx

import { SharedDefaults } from '@/components/SharedDefaults'

export default function Home() {
  return (
    <main className="flex min-h-screen flex-col items-center justify-between p-24">
      <SharedDefaults>
        <div className="z-10 max-w-5xl w-full items-center justify-between font-mono text-sm lg:flex">
        // ...
        </div>
      </SharedDefaults>
    </main>
  )
}

Wrap Storybook story components with SharedDefaults.

ℹ️ Instead of wrapping each stories component files in a SharedDefaults component, we recommend declaring the latter as a Storybook Decorator for context-mocking in the .storybook/preview.tsx file:

Stop the storybook server;
Rename the .storybook/preview.ts file to use .tsx extension;
Append the SharedDefaults wrapper to the decorators property (and declare a React import explicitly):

// .storybook/preview.tsx

import React from 'react';
import { SharedDefaults } from '../src/components/SharedDefaults';

// ...

  decorators: [
    // ... ,
    (Story) => (
      <SharedDefaults>
        <Story />
      </SharedDefaults>
    ),
  ]

ℹ️ If you don't see the SharedDefaults fonts/colors being applied in Storybook, it may be because the specific component overrides the font in its classes. For example, the Header.tsx component contains a storybook-header class that uses the Nunito Sans font. To verify that SharedDefaults fonts and themes are being applied, remove the conflicting classes from the className in the targeted components, and try again.

Conclusion

Although Next.js, Tailwind and Storybook have come a long way regarding mutual integration, some of the challenges mentioned in this article can arise for the developers. By applying our suggestions, it is possible to reduce the amount of work required in future phases of development, while still maintaining a consistent workflow.

Setup Next.js, Storybook and Tailwind on a Stackomate Dev-Container

Rafael Calpena — Fri, 01 Sep 2023 05:06:01 +0000

In this tutorial we will see how to setup a reproducible web development stack containing Next.js, Storybook and Tailwind inside a dev-container.

Using a dev-container provides a reproducible environment for your team, and guarantees the isolation of your project files. For example, different projects may contain different Node.js and/or Python versions. We will be using the Stackomate CLI, a global npm package capable of generating templates for development containers for variable purposes.

Creating a Dev-Container

First, let's create our new dev-containers with the Stackomate CLI by running
npx -y stackomate@latest dev-container create and following the default instructions. You will be prompted to select a container type. Below we explain the differences between two common options:

Option 1 - Node.js Dev-Container

You may select the node dev-container to achieve smaller image sizes and faster startup times. The developer can connect to the container via the terminal.

⚠️ Specifically for our web stack, internal ports 3000 and 6006 will be used by Next.js and Storybook servers, respectively, and thus they must be published to the host. This can be achieved by adding the following lines to the dev.docker-compose.yml file created by the stackomate cli:

ports:
  - 3000:3000
  - 6006:6006
expose:
  - 3000
  - 6006

Option 2 - Full Desktop Dev-Container

The desktop-web type contains a Ubuntu desktop interface with Node.js and a built-in reverse proxy installed. The developer can access Firefox, a default terminal and a simple file manager on the browser. It is a great choice for larger projects requiring complex configuration, such as website stacks requiring the generation of local SSL certificates. The desktop interface will be published internally on port 6080, by default. If you need another port, you can change the following lines in the generated dev.docker-compose.yml file:

ports:
  - 6080:6080
expose:
  - 6080

ℹ️ Note: you may create both container types for your web stack, if desired. You may also run them both at the same time.

Once you have created and edited your dev-containers, follow instructions in the generated README.md files to start them. For example, the node dev-container can be started by running cd ./dev-container/node && ./dev.sh (or ./sudo-dev.sh, if your Docker installation requires sudo permissions).

Creating Your Next.js App

Now that we have our container running, it is time to start creating our Next.js app inside of it:

Access /app inside your container terminal: cd /app;
Call the create-next-app cli: npx -y create-next-app@latest;

We recommend using the following options, except for the project name, which may be chosen arbitrarily. With these settings, Next.js will spare us from installing Tailwind and ESLint separately, and our project structure will contain a src folder and the latest App Router:

What is your project named? › my-test-app
Would you like to use TypeScript? › No / (Yes)
Would you like to use ESLint? › No / (Yes)
Would you like to use Tailwind CSS? › No / (Yes)
Would you like to use `src/` directory? › No / (Yes)
Would you like to use App Router? (recommended) › No / (Yes)
Would you like to customize the default import alias? › (No) / Yes

ℹ️ If you ever want to add Tailwind to an existing Next.js project, you can follow their official guide for more instructions.

⚠️ If you have created the Next.js project without the src folder, please make sure to update all imports in the next parts of this article to reflect the folder structure changes. For example, the src/app/globals.css file would otherwise be located in app/globals.css.

Wait for the bootstrapping process to be complete;
cd /app/my-test-app;

ℹ️ You can ignore linting warnings at the ./src/app/globals.css file, such as Unknown at rule @tailwindcss(unknownAtRules). If you really want to fix it though, you can follow this solution to add customAt rules.

Installing Storybook

We have Next.js and Tailwind installed, and now we must install Storybook and integrate all three:

Run npx -y storybook@latest init

ℹ️ Storybook should automatically detect the Next.js project type. It should also detect ESLint and ask:

We have detected that you're using ESLint. Storybook provides a plugin that gives the best experience with Storybook and helps follow best practices: https://github.com/storybookjs/eslint-plugin-storybook#readme

Would you like to install it? › (Y/n)

Choose Y to proceed with the Storybook ESLint Plugin installation.

Once Storybook has finished installing, it will automatically start on port 6006.

Go to your browser and open http://localhost:6006

Now Storybook has been seamlessly integrated with Next.js. You can check your package.json file for a @storybook/nextjs dependency. More details about all Next.js features supported by Storybook can be viewed on their package documentation page.

Adding Support for Tailwind on Storybook

Although Storybook has detected and integrated with our Next.js project, it has not detected Tailwind by default.

ℹ️ You can verify it by editing the src/stories/Header.tsx file: add the bg-red-500 class to the element containing className="storybook-header". If the header background does not turn red, then Tailwind is not working with Storybook yet.

Now, we integrate Tailwind with Storybook:

Include the src/stories directory in your tailwind.config.js, so that Tailwind can find and target React components in that folder:

const config: Config = {
  content: [
    './src/pages/**/*.{js,ts,jsx,tsx,mdx}',
    './src/components/**/*.{js,ts,jsx,tsx,mdx}',
    './src/app/**/*.{js,ts,jsx,tsx,mdx}',
    './src/stories/**/*.{js,ts,jsx,tsx,mdx}',
  ],
  // ...

⚠️ Before proceeding, we recommend to commit your git changes in the project directory: for example, run git add -A and git commit -m 'chore: add storybook and tailwind'.

Stop storybook, and install the @storybook/addon-styling package in your project:

npm i -D @storybook/addon-styling

Now run a codemod to help with the integration:

npx addon-styling-setup

You should see an output like this:

=========================================

 🧰 Configuring @storybook/addon-styling

=========================================

(1/3) Project summary
  • Built with webpack
  • Styled with tailwind

(2/3) .storybook/main.ts
  • Registering @storybook/addon-styling.

(3/3) .storybook/preview.ts
  • Adding import for withThemeByClassName decorator
  • Adding import for stylesheet
  • Adding withThemeByClassName decorator to config

✨ Done

Go to .storybook/preview.ts, and adjust the line below:

/* TODO: update import to your tailwind styles file. If you're using Angular, inject this through your angular.json config instead */
import '../src/index.css';

/* Import for our tailwind global styles file */
import '../src/app/globals.css';

Remove the styles generated by Next.js from the src/app/globals.css file, and just leave the Tailwind imports:

@tailwind base;
@tailwind components;
@tailwind utilities;

Open your storybook again by running npm run storybook

🎉 Now, you should now see the Header.tsx component with the red background in the Header story! 🎉

Integrating Tailwind Themes with Storybook

Tailwind can allow the user to change the appearance of a website using light and dark themes. However, some minor changes must be made if you want to toggle themes in the Storybook preview, which we will see next.

ℹ️ To verify support for dark themes, add dark:bg-yellow-600 to your Header.tsx component, and then toggle from light theme to dark theme in the top dropdown many times. Notice how only one of the background colors is used. This happens because, by default, Tailwind "uses the prefers-color-scheme CSS media feature" (source). Instead, we want to toggle it programatically:

Go to tailwind.config.ts and set the darkMode property to support manual toggling by class:

const config: Config = {
  darkMode: 'class',
  content: [
    // ...
}

Now, you should see the Header.tsx component change its background color from red to yellow depending on the theme you choose!

🎉 You can now develop your Next.js website with Tailwind and Storybook, happy coding! 🎉

ℹ️ Once you want to exit your dev-container, use CTRL+C to exit the storybook server, and type exit to stop and remove the development-container. Don't worry about your project files, they will not be lost as they are being mapped to the host 🙂.

If desired, we can further push our dev-containers to GitHub, and distribute them with other people in the team.

Conclusion

In this tutorial, we described a series of steps to create a complex project stack using Next.js, Tailwind and Storybook, along with some challenges and fixes to integrate the existing tools. We have used the Stackomate CLI to help us generate a dev-container and redistribute our development environment in a more predictable way. In the next articles, we will see further improvements that our stack can use to support more common features desired during development.

Batching Operations - When Pure Immutability Is Not Worth It

Rafael Calpena — Sun, 20 Sep 2020 20:29:35 +0000

In the previous part of the series I ended the article with a question:

Is it possible to improve copying performance when batching updates?

We saw that immutability is a great way of avoiding side-effects. So why (and when) would someone not use it?

Use Case Example

Imagine our UI Application contains:

A Set of email strings.
Functions for registering/unregistering emails. They receive an array of email strings, and then update the Set accordingly.

let emailSet = new Set([
    '1stEmail@mail.com', 
    '2ndEmail@mail.com',
    '3rdEmail@mail.com',
    //...
]);

const registerEmails = (list: string[]) => {
    list.forEach(email => {
        emailSet = new Set(emailSet).add(email)
    })
}

const unregisterEmails = (list: string[]) => {
    list.forEach(email => {
        emailSet = new Set(emailSet).delete(email)
    })
}

💡 Feel free to check my article about sets for an explanation about the concept.

Both functions update emailSet immutably: they always create a new copy of the Set with new Set() constructor, and then mutate only the newest version. This presents some challenges:

Constraint - Cloning can be Expensive

When cloning a Set, each item will be copied into the new Set, so the total time spent cloning is proportional to the Set size: O(size(Set)). This is the main reason why we should avoid cloning as much as possible, while still avoiding side-effects in the original Set.

Problem #1 - Cloning an Unchanged Set

An unnecessary clone will be performed if the function:

Registers an already existing email
Unregisters an inexistent email

This is easy to fix: we can update the functions to perform "selective cloning" (only change the Set if there is a real modification).

const registerEmails = (list: string[]) => {
    list.forEach(email => {
        /* Check if email not registered before cloning */
        if (!emailSet.has(email)) {
            emailSet = new Set(emailSet).add(email)
        }
    })
}

const unregisterEmails = (list: string[]) => {
    list.forEach(email => {
        /* Check if email registered before cloning */
        if (emailSet.has(email) {
            emailSet = new Set(emailSet).delete(email)
        }
    })
}

💡 Client-side frameworks (E.g.: Angular, React, etc) usually rely on === test to detect component changes. Forcing a useless clone wastes time both during the cloning process, as well as in the framework internal diff checks.

Problem #2 - Not Batching Mutations

Our code is still not performant under certain circumstances. If we receive a list of 10 emails to register/unregister, our Set could be cloned 10 times inside our forEach loop.

registerEmails([
    'a@mail.com', // New email, clone Set
    'b@mail.com', // New email, clone Set
    'c@mail.com', // New email, clone Set
    //... (New email, clone Set x7)
])

Is it possible to keep the immutability benefits while also speeding up code execution? We still want a new Set, but this much cloning is not desired in this case.

Batching

The solution to the problem above is called batching. From outside of the batching context, everything looks immutable (no side-effects), while on the inside it uses mutability when possible.

The batcher wraps a target object (in our case, the Set) and provides an API for changing it that follows the rules:

Delay cloning target until absolutely necessary (call willChange()).
After object is cloned, we can mutate it subsequently as many times as required (mutate currentValue).

Let's use the batcher in the registerEmails function as an example:

const registerEmails = (list: string[]) => {
    /* Create the batcher context for emailSet */
    let batcher = prepareBatcher(emailSet);

    list.forEach(email => {
        /* Use batcher currentValue property to refer to Set */
        if (!batcher.currentValue.has(email)) {
            /* Let batcher know a change is about to happen */
            batcher.willChange();
            /* We can mutate currentValue (Set) directly now */
            batcher.currentValue.add(email)
            /* Update our emailSet variable */
            emailSet = batcher.currentValue;
        }
    })
}

Composable Batchers

The previous code is performant, but code reusability can be present in our batching architecture. Here's one way to implement it:

Functions receives a batcher (which wraps the object to be modified) as argument instead of the object directly.
The function performs desired changes using the Batcher API.
In the end, the function returns the batcher (NOT the object).

Let's refactor the previous code snippet into more reusable functions:

/* This can be reused for any Set */
const add = <T>(batcher: Batcher<Set<T>>, item: T) => {
    if (!batcher.currentValue.has(item)) {
        batcher.willChange();
        batcher.currentValue.add(item);
    }
    return batcher;
}

/* This can be reused for any Set */
const remove = <T>(batcher: Batcher<Set<T>>, item: T) => {
    if (batcher.currentValue.has(item)) {
        batcher.willChange();
        batcher.currentValue.delete(item);
    }
    return batcher;
}

And now we can import the functions into our project:

const registerEmails = (batcher: Batcher<Set<string>>, list: string[]) => {
    list.forEach(email => {
        add(batcher, email);
    });
    return batcher;
}

const unregisterEmails = (batcher: Batcher<Set<string>>, list: string[]) => {
    list.forEach(email => {
        remove(batcher, email);
    });
    return batcher;
}

/* Call registerEmails */
let batcher = prepareBatcher(emailSet);
registerEmails(batcher, [...]);
emailSet = batcher.currentValue;

We can keep creating higher-level procedures:

const complexOperation = (batcher: Batcher<Set<string>>) => {
    /* Apply operations */
    registerEmails(batcher, [...]);
    unregisterEmails(batcher, [...]);
    unregisterEmails(batcher, [...]);
    registerEmails(batcher, [...]);
    return batcher;
}

let batcher = prepareBatcher(emailSet);
/* Call the function */
complexOperation(batcher);
/* Update variable */
emailSet = batcher.currentValue;

The cloning still happens at most once! If we had no optimizations, there could have been length(array) clones (with size(Set) item copies) for each register/unregister call inside complexOperation.
The code is modular and reusable, all we have to do is call prepareBatcher(emailSet) and provide it to the function.
The reference equality still stands for the object if no changes have been made.

Proof of Concept

I recently came up with a proof of concept for the Batcher Architecture. You can check the console.logs in the CodeSandbox example below:

The source code can be found at

Stackomate / monorepo

Data-structures for Typescript projects.

For now, one can use add, remove and filter methods. New operations will be available soon.

Math Concepts for Programming - Sets

Rafael Calpena — Sun, 13 Sep 2020 16:48:17 +0000

Today, I'm starting a series of posts about object relationships. In this post, we are going to see a foundational concept in Mathematics called Set. Let's check some use case examples and operations that can be applied to them.

Sets are "The Building Blocks"

A set is a well-defined collection of distinct objects.

The objects that belong to a set are called its elements (or points or members)

Source: Functional Analysis by P. K. Jain, Khalil Ahmad, and Om P. Ahuja

An informal way of defining a Set is a container (box/circle) that has distinct objects inside. We can represent it with the following notation:

S = {1, 2, 'some string'}

The elements of the Set are written inside the curly braces. S is an identifier to the Set.

The order of the objects does not matter.

S = {1, 2, 3} = {2, 3, 1} = {3, 2, 1}

The definition of Set does not allow for repetition of the same element, so each element should be represented at most once.

S = {1, 1, 2, 3, 2, 3} = {1, 2, 3}

Uses

We can use Sets to define the world around us.

The set of states in a country.

States = {'New York', 'California', 'Florida', 'Washington DC', ...} // size = 50

The set of username ids who have used your website this week.

usersFromLastWeek = {12938, 89032, 55866}

The empty set.

S = {}

Sets can also represent more complex cases.

The set of natural numbers (infinite).

S = {1, 2, 3, 4, ...} // Size = Infinity

The set of sets mentioned above.

S = { 
    {'New York', 'California', 'Florida', 'Washington DC', ...},
    {12938, 89032, 55866},
    {}
} // Size = 3

Self-containing sets.

S = {1, 2, S} =
{
    1, 2,
    { // S
        1, 2, { // S
            1, 2, {...}
        }
    }
} // Size = 3

💡 Elements contained in nested Sets are not considered direct elements from the Root Set (S).

Properties

Size = Number of elements present in the Set.

Operations

Operations are ways to read and/or transform the Set into another Set (or another object):

💡 The notation below is pseudo-code

Is Empty to check if Set size equals zero.

S1 = {}
isEmpty(S1) // = true
S2 = {1, 2, 3}
isEmpty(S2) // = false

Add one or more elements to the Set.

S1 = {1, 2}; 
S2 = add(S1, 3, 10); // = {1, 2, 3, 10};

Remove one or more elements from the Set.

S1 = {'a', 'b', 'c', 'd'}; 
S2 = remove(S1, 'c') // = {'a', 'b', 'd'}

Has to check if an element is contained in the Set.

S1 = {'a', 'b', 'c', 'd'}; 
has(S1, 'e') // False
has(S1, 'a') // True

Iterate to loop over elements in the Set.

S1 = {'Sandra', 'Mary', 'Louis'};
for (let person of S1) {
    // person = Sandra, Mary and Louis, respectively
    // Order may vary
}

Equals for comparing if one Set contains the exact same elements as another Set.

S1 = {'first', 'second', 'third'}
S2 = {'second', 'third', 'first'} // Order does not matter
equals(S1, S2) // True
S3 = {'fourth'}
equals(S1, S3) // False

Union: Creates a resulting Set that contains all elements from both Sets.

S1 = {'first', 'second', 'third'}
S2 = {'fourth'}
union(S1, S2) // = {'first', 'second', 'third', 'fourth'}

Difference: Creates a resulting Set with elements in Set1 that are not contained in Set2.

S1 = {'first', 'second', 'third'}
S2 = {'second'}
difference(S1, S2) // = {'first', 'third'}

Intersection: Creates a resulting set that contains only elements both present in Set1 and Set2

S1 = {'first', 'second', 'third'}
S2 = {'second', 'fourth'}
intersection(S1, S2) // = {'second'}

Disjoint: 2 sets are disjoint if their intersection is equal to the empty set.

S1 = {1, 2, 3}
S2 = {4, 5, 6}
areDisjoint(S1, S2) // = True

S3 = {3, 9, 10}
areDisjoint(S1, S3) // = False, because of "3"
areDisjoint(S2, S3) // = True

Filter for getting a set of only the elements that satisfy a given condition. The elements that do not satisfy the condition are not part of the result.

S1 = {1, 2, 3, 4, 5, 6}
numberIsEven = (number) => number % 2 === 0;
S2 = filter(S1, numberIsEven) // = {2, 4, 6}

Map for mapping Set elements into other elements

S1 = {1, 2, 3, 4, 5}
S2 = map(S1, (number) => number * 9)) // = {9, 18, 27, 36, 45}

Reduce for iterating on the Set and creating a new result. It takes an accumulator and item and returns a new value for the accumulator.

S1 = {1, 2, 3, 4, 5}
reduce (S1, (count, element) => count + element, 0) // Sum all elements, = 15

Symmetric Difference for obtaining the elements that are in either of the Sets, but not in both of them.

S1 = {1, 2, 3, 4}
S2 = {2, 4, 5, 6}
S3 = symmetricDifference(S1, S2) // = {1, 3, 5, 6}

Is Superset For checking whether one Set contains all elements of the other Set.

S1 = {1, 2, 3, 4}
S2 = {1}
isSuperset(S1, S2) // = true
S3 = {3, 4}
isSuperset(S1, S3) // = true
S4 = {3, 4, 5}
isSuperset(S1, S4) // = false

is Subset For checking whether all elements of one Set are contained in another Set.

S1 = {1, 2, 3, 4}
S2 = {1}
isSubset(S2, S1) // = true
S3 = {3, 4}
isSubset(S3, S1) // = true
S4 = {3, 4, 5}
isSubset(S4, S1) // = false

Find: Used to find one element in the Set that satisfies some constraint.

S1 = {1, 2, 3, 4, 5}
element = find(S1, n => n > 3) // = 4 or 5 (order may vary)

Every: Check if all elements of the Set satisfy some constraint.

S1 = {1, 2, 3, 4, 5}
element = every(S1, n => n < 10) // = True

S1 = {1, 2, 3, 4, 5}
element = every(S1, n => n < 3) // = False, because of 4 and 5

Order two or more Sets by their sizes. Returns a tuple with size as the number of Sets provided.

S1 = {1, 2}
S2 = {0}
S3 = {4, 1, 2}

order(S1, S2) // (S2, S1, S3)

Changes: A way to compare 2 Sets and find which elements must be removed or added from the first set to become equal to the second set.

S1 = {1, 2, 3, 4, 5, 6}
S2 = {4, 5, 6, 7}
Changes(S1, S2) = ({1, 2, 3}, {7}) // Starting from S1, remove 1, 2 and 3, and add 7 to transform it to S2

Cartesian Product: Multiply two sets in order to create a set of ordered pairs

S1 = {'a', 'b', 'c'}
S2 = {0, 1}
S3 = cartesianProduct(S1, S2) // = { ('a', 0), ('a', 1), ('b', 0), ('b', 1), ('c', 0), ('c', 1) }

In the next post, we are going to take a deeper look at ordered pairs and its uses.

Bonus

Russell's Paradox - a.k.a. The Barber Paradox

Happy Labor Day! What are you thankful for in your profession? And what could be improved?

Rafael Calpena — Mon, 07 Sep 2020 19:02:15 +0000

Lessons I've learned from building a COVID-19 Bot with 10K users on Telegram

Rafael Calpena — Fri, 28 Aug 2020 00:47:48 +0000

In the beginning of 2020, we came to know about COVID-19. It was only a matter of time until the virus arrived in Brazil, and in the midst of some confusion and fear, I decided to spend my time indoors writing some code targeted at our latest global problem. CoronavirusBrBot, a bot for tracking the situation of the pandemic in Brazil, was created on Telegram, became popular and at one point had ~18k users (including group users).

This article talks about the decisions I've made and challenges I've faced while creating and maintaining CoronavirusBrBot. It also talks about some technical choices suitable for side-projects with limited resources.

Make an MVP (Minimum Viable Product)

Focus on the minimum number of features required to ship your product as early as possible. This will give you quicker feedback from your users.

Back when cases were rare in Brazil, I wanted to receive mobile notifications from Ministry of Health's website data to track the current pace of the disease. So I focused on getting that done as my first feature.

Since I'm a web developer, my first thought was "I will create an App for this". But I eventually came to the conclusion that a Telegram Bot was much more appropriate for building my MVP, along with a very very simple database called Lowdb.

The "right tool" for the job can be simpler than you expect.

Using node-telegram-bot-api, all I had to do was create a bot using BotFather, and use Lowdb for a schemaless database structure and straightforward data manipulation.


Initial version of the bot.

Surround yourself with people with common goals

Don't be afraid to reach out for help. Once you find people with the same goals as you, you'll realize how much more you can create together.

wcota / covid19br

COVID-19 data in Brazil: cases, deaths, and vaccination at municipal (city) level. Description of the data: https://github.com/wcota/covid19br/blob/master/DESCRIPTION.en.md and https://doi.org/10.1590/SciELOPreprints.362

In order to improve the bot, I spent some time looking for COVID-19 resources until I found covid19br by W. Cota, who introduced me to a group of people working with COVID-19 data, including coronavirusbra1 who has done an outstanding job covering COVID-19 news. We were able to benefit from each other's work and referrals. For the bot, it meant earning new users and a new data source, as well as the support from the team during hard times.


Nowadays the bot provides multiple data sources.

Listen to what users have to say

One of the first features I implemented in CoronavirusBrBot was a command for the user to give us feedback. I was pleased to receive many ideas related to my initial plans, as well as new ones (e.g.: filter data by city) that were implemented afterwards and became popular. As long as you take opinions with a grain of salt and prioritize goals, listening to users will improve your development cycle.


Feedback channels are a great way to validate that you're on the "right track".

Avoid Premature Optimization

Don't be afraid to evolve your app as required, instead of designing the architecture for extreme scenarios in the first iteration. Often, you will be able to fix the issues quicker than your app scales. Examples:

The bot used to enqueue all messages and send them consecutively, one-by-one. This became slow by the time we got to ~500 users, as it took ~8 minutes to send updates to everyone. The solution was to parallelize messages at a rate of 20 messages/second (Telegram's limit is 30).
The log of actions used to be saved in the same database storing user information. That quickly became a bottleneck for performance, since LowDB has to stringify and parse all of the database content. Solution: moved the log to a separate append-only file.
Syncing the whole DB from RAM to disk also had an impact once we increased the sent messages frequency. Instead of saving the DB every time, I optimized the code to save once every 3 seconds for bulk sends, and before shutting down the server. Problem solved without needing to change databases :)

It doesn't have to be perfect

When using limited time and resources, don't bother about making it too perfect. Sacrifices in quality have to be made. Specifically for the bot:

Production and Development used to be the same environment. I was coding it late at night (2-4am) when almost nobody was using it, applying changes immediately with restart, and keeping an eye on the logs during the day to make sure nothing would break.
Code quality is not ideal. I did not use Typescript for this project. The project has huge .js files, and the folder structure is weird. But it runs, and that's good enough :)
Incidents happened: Most of the time, these were minor, e.g. sending messages twice. However in one time the database got corrupted due to the hard drive being full. Luckily I was able to revert to a backup created not so long before the incident.

Backups are essential, take them frequently and the consequences of loss of data will be greatly diminished.

Seize the Opportunity

If I were to launch the bot today, it probably wouldn't have been as popular as it is. Part of its success was due to the trust users have put into our work for delivering accurate information on a daily basis.

The sooner you start working on making your idea come true, the higher the probability it will be successful.


8,612 people + 5,138 indirect people (channel/group users) = 13,750 total users

Got an Idea?

Before you Start:

Trust your idea even if no one else does! Don't ask for people's approval as this can actually work against you. Be persistent.
Prepare yourself with a "no regrets" attitude. In the worst-case scenario you will have failed, wasted some time and acquired important knowledge. Meaning you will be ready for the next challenge in your life.
If you have to gather information about your audience, do some market research, which uses a more objective, unbiased approach than asking informal questions to people around you.

During the Process:

Use metrics and feedback from users to measure your app success.
Some people may not understand the value of your creation and the effort you've put into making it come true. There's nothing you can do about this! Don't waste time trying to convince anyone and...
Find people who NEED your app. Don't be discouraged in case your initial users (friends, colleagues, close ones, etc.) are indifferent to your creation, they might not overlap with your target audience. The internet is a gigantic place and your target audience is certainly there, you just have to keep looking.

If you build something good enough that reaches the intended target audience, users will come. If they build trust on your app, they will stay.

The Bot is Open Source

Feel free to check the code for the bot at:

Stackomate / coronavirus-bot

A Telegram Bot for keeping track of Coronavirus cases in Brazil.

Final Acknowledgments

Cover photo by CDC - Unsplash

I would like to give special thanks to
coronavirusbra1, Wesley Cota, Fabio Rehm, PokeCorona, leonardomed, hexry13, and aletoorres for providing me the data sources, graphs and support when I needed the most.
Check Coronavirusbra1's panel at coronavirusbra1.github.io.
Also, thanks to inlocotech and turicas for graphs and regional data.
CoronavirusBrBot would not have been possible without your help. ❤️

Javascript Objects Deep Dive: References, Primitives, Equality, Immutable, Tree and Circular

Rafael Calpena — Sun, 28 Jun 2020 06:59:17 +0000

Objects are a fundamental block for creating application state. Therefore, it's essential to understand how they work and what their manipulation strategies are.

Note: This article makes assumptions based on the way objects are handled in Javascript. Programming languages differ slightly on the topic, but many of the concepts covered below can be applied to your language of choice.

Variables and Memory

Our programs need to store, read and possibly modify data while running. Hence, there's a need to reach previously defined values in our code for later use. With Javascript, that can be done with variables:

let welcomeMessage = 'Hello World';
let age = 38;
let hungry = true;

Let's use a simplified analogy to represent what's going on under the hood. There are 2 tables of correspondence:

First table relates memory addresses to their current values. The number of addresses depend on the size of the available RAM in the machine.

Address	Value
001	'Hello World'
012	true
043	38

Second table relates variable names to memory addresses. These are the variables declared in our program.

VarName	Address
welcomeMessage	001
age	043
hungry	012

💡 Memory address indexes do not necessarily have a pattern.

References

See those memory address codes in the table (001, 043, 012)? We will call them References from now on. They're the physical address in memory where values are being stored.

Important: References are NOT variable names. Rather, variable names are pointing to a reference. That's an important distinction we have to make in order to understand the next concepts.

Reading Some Variable

In order to read some variable (for example, age), the program will obtain its specific memory address (reference), and then its value:

age -> 043 -> 38

Immutability

Think about creating a payment check to someone. Once we are done writing it, we expect it to remain unchanged. That's the reason we use pens (no removals) and cross-out void spaces (no additions).

What if the check had been misspelled?

In that case, it's a better idea to write a new check instead of overwriting the current one, shred the current check and throw it away in the garbage.

We are about to see that Immutability is also used in many programming scenarios, often due to the same reason (guaranteeing consistency).

Primitives

a primitive (primitive value, primitive data type) is data that is not an object and has no methods.

According to MDN Web Docs, Javascript contains 7 primitives: string, number, bigint, boolean, undefined, symbol and null.

We can consider Primitives one the lowest building blocks in the language. It's important to note that they have no methods.

I can call .toString() on a number, doesn't that mean it has properties/methods?

Not really. Javascript applies Autoboxing to primitives. One quick way to check this is to try creating a new property in the number:

let myNumber = 345;
myNumber.previousNumber = 344;
myNumber.previousNumber //undefined

If they did have properties, previousNumber would have been saved in the example above.

Primitives are Immutable

One important characteristic of primitives is that they do not allow for modifications after they are created.

Primitives are written with pens.

What does Immutable mean in programming terms, though? Going back to our memory analogy:

let myCoolPrimitive = 'This is a primitive';

Address	Value
047	'This is a primitive'

VarName	Address
myCoolPrimitive	047

The value inside Reference 047 is immutable. It cannot be altered anymore. So how to change the value for myCoolPrimitive?

let myCoolPrimitive = 'This is a primitive';
myCoolPrimitive = 'Can I change it though?';

Address	Value
047	'This is a primitive'
019	'Can I change it though?'

VarName	Address
myCoolPrimitive	019

The reference has been updated to a new string.

Let's also use an example with 2 variables this time:

let firstPrimitive = '1st primitive';
let secondPrimitive = firstPrimitive;

Address	Value
001	'1st primitive'

VarName	Address
firstPrimitive	001
secondPrimitive	001

/* ...Continuing code from snippet above */
secondPrimitive = 'Changed to second primitive';
console.log(firstPrimitive) // '1st primitive'

Address	Value
001	'1st primitive'
002	'Changed to second primitive'

VarName	Address
firstPrimitive	001
secondPrimitive	002

Only the targeted variable (secondPrimitive) will change its value.

Objects

If some value is not a primitive, then it is an object.

JavaScript objects are containers for named values, called properties and methods.

Source: W3Schools

Examples of objects include (but are not limited to): {}, [], Function, Date, HTMLElement, Set, Map, etc.

Objects are written with pencils

Unlike primitives, one can create an object and modify its properties later. That's mutable behavior, let's see an example:

let user1 = {name: 'Josh', credit: 200};
let selectedUser = user1;
let creditVar = user1.credit;

Address	Value
001	{name: `$002`, credit: `$003`}
002	'Josh'
003	200

💡 Object properties point to memory addresses. $ notation represents a reference.

VarName	Address
user1	001
selectedUser	001
creditVar	003

user1.credit = 600;

Address	Value
001	{name: `$002`, credit: `$004`}
002	'Josh'
003	200
004	600

VarName	Address
user1	001
selectedUser	001
creditVar	003

console.log(selectedUser.credit) //600
console.log(creditVar) //200

Credit Number got updated, it's a primitive so it created a new reference ($004).
The object was updated after it's creation (updated credit number reference from $003 to $004). Therefore, it is showing mutable behavior.
selectedUser and user1 are pointing to the same object. They are sharing the object and its properties, and if one variable updates a property, the other variable will also reflect the changes.
creditVar never got updated to 600 because it's pointing to the 200 primitive that was previously defined.

Objects Inside Objects

It's also possible to "nest" objects.

let math101 = {difficulty: 0.3}
let courses = {math: math101}

Address	Value
001	{math: `$002`}
002	{difficulty: `$003`}
003	0.3

VarName	Address
math101	002
courses	001

Circular Objects

It's possible to reference one object to itself as a property.

let a = {};
a.b = a;

Address	Value
001	{b: `$001`}

VarName	Address
a	001

It's also possible to reference 2 or more objects in a circular way.

let o1 = {};
let o2 = {};
o1.o2 = o2;
o2.o1 = o1;

Address	Value
100	{o2: `$101`}
101	{o1: `$100`}

VarName	Address
o1	100
o2	101

Object Tree

An Object Tree is a specific type of object that contains child objects where:

An object can only appear once in the tree (0 or 1 incoming edges).
There are no cycles in the graph.

This is a valid example of an Object Tree

Invalid example (E has 2 parent objects)

Invalid example (Graph contains cycle A -> C -> E)

Garbage Collection

You may have noticed in our examples that values can stay in memory even after they're not being used by any other variables (or objects). Fortunately Javascript comes with a Garbage Collector, which periodically wipes away unreachable values automatically, so we don't have to worry about explicitly deleting them from memory:

let someVar = 123;
someVar = "Now I'm a string!";

Address	Value
001	123
002	"Now I'm a string"

VarName	Address
someVar	002

After Garbage Collection, Address 001 should be released:

Address	Value
002	"Now I'm a string"

VarName	Address
someVar	002

Garbage Collection is dependent on the environment's implementation (Browser, Node.js, etc), but generally uses the "Mark-and-sweep Algorithm", according to this MDN Article about Memory Management

Equals Operator

NOTE: As a rule of thumb, use Triple Equals Operator (===) when possible instead of (==). See why here

In Javascript, the equals operator works differently for primitives and non-primitives:

let firstString = 'The quick brown fox jumps over the lazy dog';
let secondString = 'The quick brown fox jumps over the lazy dog';
console.log(firstString === secondString) // true

let firstObject = {};
let secondObject = {};
let thirdObject = secondObject;
console.log(firstObject === secondObject) //false
console.log(secondObject === thirdObject) //true

Address	Value
001	'The quick brown fox jumps over the lazy dog'
002	'The quick brown fox jumps over the lazy dog'
003	{}
004	{}

VarName	Address
firstString	001
secondString	002
firstObject	003
secondObject	004
thirdObject	004

When comparing 2 variables with ===:

Primitive Values will return true when their content is the same (even if memory addresses are different for each variable!)
Objects will return true only if the 2 variables point to the same memory address.

Comparing 2 objects deeply (by their content instead of reference) is often not desired since it can be computationally expensive and unpredictable (depends on the depth and key length of the objects). That being said, in extreme cases it's recommended to use some library method, for example Lodash's isEqual function

Immutable Objects

Avoiding Side Effects

Sharing the same object is a performance improvement (less memory is allocated). But there are times when you need independent copies. One example is extending from a base object.
In order to create Immutable objects, We can use spread operators for Arrays ([...]) and Objects ({...})

💡 Remember: The new object should behave as "read-only" after being cloned and applied the desired changes. If subsequent changes are needed, a new immutable object should be created. This will guarantee the object consistency promised by the immutable strategy.

let baseCar = {
    color: 'black', 
    convertible: false, 
    passengers: 5
}

let fancyCar = {...baseCar, convertible: true} 
/* {
    color: 'black',
    convertible: true,
    passengers: 5
} */

By creating different references, we can be sure that the baseCar will not be altered when there is a change in fancyCar. This avoids side-effects in our code.

Benefits Of Immutability

By using the concept of Immutable objects we can better integrate our code with features like:

Faster Change Detection: Updates often change only part of an object. By using === operator (fast), deep object comparison is possible by using references, avoiding expensive full object traversal (e.g. Lodash's isEqual).

If newObject !== oldObject, something changed. We can recursively inspect its properties and find the changed values faster.
"Time Travel": Previous versions of objects can be kept in memory. Each version is a snapshot of the object, which allows for inspection through time and helps to debug the code.

Nested Immutable Updates

Updating a nested object Immutably is relatively simple when your Object structure is a Tree. All we have to do is use the spread syntax in all the levels preceding the property.

Let's update obj.a.b.c immutably to false in the example below:

let obj = {
    a: {
       b: {
           c: true,
           e: 'mnop'
       },
       d: 456
    }
    y: {
        z: 12
    }
}

let obj2 = {
    ...obj,              //Copy obj properties
    a: {                 //Overwrite property obj.a
        ...obj.a,        //Copy obj.a properties 
        b: {             //Overwrite property obj.a.b
            ...obj.a.b,  //Copy obj.a.b properties
            c: false     //Overwrite obj.a.b.c property
        }
    }
}

The resulting object contains all properties defined in obj, with the update on obj.a.b.c = true. Notice only the changed objects have been cloned, so we can still use reference equals operator for unchanged properties:

obj.a === obj.a; //false
obj.y === obj2.y; //true

This is great for both cloning and equality check performance.

Complex Immutable Updates and Improvements

Is it possible to improve copying performance of nested objects when batching updates?

How to update nested immutable objects when they are not in the shape of a tree? How do multiple parents and object cycles interfere with our workflow?

These questions are harder to answer and will be covered in the next part of our series. Thanks for reading and stay tuned for the following chapters :)

DEV Community: Rafael Calpena

Common Improvements to your Next.js, Tailwind and Storybook Stack

Avoid Import Path Issues

Add Support for SVG Imports

Use the clsx Library (Recommended)

Use the twMerge Library (Optional)

Manage Fonts with @next/fonts

Create a SharedDefaults Component

Conclusion

Setup Next.js, Storybook and Tailwind on a Stackomate Dev-Container

Creating a Dev-Container

Option 1 - Node.js Dev-Container

Option 2 - Full Desktop Dev-Container

Creating Your Next.js App

Installing Storybook

Adding Support for Tailwind on Storybook

Integrating Tailwind Themes with Storybook

Conclusion

Batching Operations - When Pure Immutability Is Not Worth It

Use Case Example

Constraint - Cloning can be Expensive

Problem #1 - Cloning an Unchanged Set

Problem #2 - Not Batching Mutations

Batching

Composable Batchers

Proof of Concept

Stackomate / monorepo

Data-structures for Typescript projects.

Math Concepts for Programming - Sets

Sets are "The Building Blocks"

Uses

Properties

Operations

Bonus

Happy Labor Day! What are you thankful for in your profession? And what could be improved?

Lessons I've learned from building a COVID-19 Bot with 10K users on Telegram

Make an MVP (Minimum Viable Product)

Surround yourself with people with common goals

wcota / covid19br

COVID-19 data in Brazil: cases, deaths, and vaccination at municipal (city) level. Description of the data: https://github.com/wcota/covid19br/blob/master/DESCRIPTION.en.md and https://doi.org/10.1590/SciELOPreprints.362

Listen to what users have to say

Avoid Premature Optimization

It doesn't have to be perfect

Seize the Opportunity

Got an Idea?

The Bot is Open Source

Stackomate / coronavirus-bot

A Telegram Bot for keeping track of Coronavirus cases in Brazil.

Final Acknowledgments

Javascript Objects Deep Dive: References, Primitives, Equality, Immutable, Tree and Circular

Variables and Memory

References

Reading Some Variable

Immutability

Primitives

Primitives are Immutable

Objects

Objects Inside Objects

Circular Objects

Object Tree

Garbage Collection

Equals Operator

Immutable Objects

Avoiding Side Effects

Benefits Of Immutability

Nested Immutable Updates

Complex Immutable Updates and Improvements

Use the `clsx` Library (Recommended)

Use the `twMerge` Library (Optional)

Manage Fonts with `@next/fonts`

Create a `SharedDefaults` Component