Forem: Jose Felix

6 Tips for Tailwind CSS Development (with resources!)

Jose Felix — Tue, 29 Dec 2020 15:29:10 +0000

In my previous post, I gave a myriad of reasons why Tailwind CSS is a great option for new and existing projects. When first starting out, it can be daunting to learn every utility class name and know what will fit the situation best in the present and future. This is why, in this post, I will give you tips that I have learned throughout my journey learning Tailwind. These are not rules, but I've found they have made my development easier and more readable.

1. Use 'clsx' to Join Classes

Let's start with something that is highly recommended for every project: using clsx for joining class names. Clsx is a simple JavaScript utility for conditionally joining classes together. It makes our lives easier by giving us syntactic sugar to handle complex styles for CSS solutions like CSS modules, or Tailwind CSS.

💡 This library is the same as Classnames but has a smaller bundle size and better performance.

Its syntax varies depending on the developer's preference and use case. Its syntax can range from arrays to objects. Let's look at all the possibilities:

// EXTRACTED FROM https://github.com/lukeed/clsx
import clsx from "clsx";

// Strings (variadic)
clsx("foo", true && "bar", "baz");
//=> 'foo bar baz'

// Objects
clsx({ foo: true, bar: false, baz: isTrue() });
//=> 'foo baz'

// Objects (variadic)
clsx({ foo: true }, { bar: false }, null, { "--foobar": "hello" });
//=> 'foo --foobar'

// Arrays
clsx(["foo", 0, false, "bar"]);
//=> 'foo bar'

// Arrays (variadic)
clsx(["foo"], ["", 0, false, "bar"], [["baz", [["hello"], "there"]]]);
//=> 'foo bar baz hello there'

// Kitchen sink (with nesting)
clsx(
  "foo",
  [1 && "bar", { baz: false, bat: null }, ["hello", ["world"]]],
  "cya",
);
//=> 'foo bar hello world cya'

This diversity is very powerful and useful when handling complex UIs.

I have chosen two syntaxes for writing Tailwind CSS classes: object notation for handling conditionals and comma-separated values for prefixes.

I first started using the basic string inline evaluation, but soon realized that my classes were ending up crammed. Take a look at this example:

clsx(
  "classes",
  cond1 && "classes classes1 classes2",
  cond2 && cond3 && cond4 && "...",
);

This is considered one of the drawbacks of Tailwind. It can quickly become unreadable and unpleasant to maintain. So I chose JavaScript objects to handle conditional class names.

No matter how many conditions there are, it is easier to read and keep track of. Let's look at the same code as above, but in the new syntax:

clsx("classes", {
  "classes classes1 classes2": cond1,
  "...": cond2 && cond3 && cond4,
});

Immediately one can notice how much easier it is to read, and one can avoid the berated long list of class names.

Furthermore, when working with prefixes like responsive class names and dark mode, we would have:

<div
  class="block bg-white text-left space-y-1 py-2 w-full sm:w-1/2 sm:space-y-0 md:w-1/3 md:space-x-6 dark:bg-gray-700"
/>

My solution to these types of long class names is using comma-separated values in clsx. Like this:

<div
  class={clsx(
    "block bg-white text-left space-y-1 py-2 w-full",
    "sm:w-1/2 sm:space-y-0",
    "md:w-1/3 md:space-x-6",
    "dark:bg-gray-700",
  )}
/>

If needed and you use a code formatter like Prettier, it will send each value to a new line. This, as you may see, makes classes easier to read and modify in the future.

💡If there are few class names like 4 or 5 then I use a plain string since there are no readability improvements otherwise.

You may be asking about the performance loss by using a JavaScript library like clsx. It will affect performance but in a negligible way. The library is so small (311 bytes) and fast that users wouldn't notice any performance difference during runtime.

2. Separate Into Small Components

Tailwind's inline classes allow elements to not rely on the context of implementation. This means styles can be portable — movable through any context without losing meaning.

We should take advantage of it and create as many components as we can. This makes our code more readable by giving it a better composition, and it is easier to maintain in the long run.

Take for example the following snippet:

const Post = ({
  content,
  frontmatter,
  slug,
  nextPost,
  previousPost,
}: Props) => (
    <div className="px-10 pt-40 pb-24 space-y-40 md:pt-48">
      <article className="prose prose-lg xl:prose-2xl">
        <header>
          <h1 className="text-center">
            {frontmatter.title}
          </h1>
          <Image
            className="rounded-lg"
            src={frontmatter.cover_image}
            alt="cover image"
          />
        </header>
        <ReactMarkdown
          escapeHtml={false}
          source={content}
          renderers={{
            code: CodeBlock,
            inlineCode: InlineCode,
            image: InlineImage,
          }}
        />
      </article>
      <hr className="max-w-4xl mx-auto text-center border-black mb-20"/>
      <section className="flex flex-col items-center mx-auto space-y-20">
        <header>
          <h1 className="text-5xl font-bold">You may also like</h1>
        </header>
        <div className="flex flex-col space-y-10 sm:flex-row sm:space-y-0 sm:space-x-20">
          {previousPost && <RecommendedPostCard post={previousPost} />}
          {nextPost && <RecommendedPostCard post={nextPost} />}
        </div>
      </section>
      <hr className="max-w-4xl mx-auto text-center bg-black border-black" />
      <Subscribe className="w-full p-0 mx-auto" />
    </div>
);

When you read this for the first time, you may not even know what each element is doing, aside from those that have specific names already like ReactMarkdown and Image.

Since our styles do not rely on the context, we can create new smaller components that will make it a lot easier to reason about our code.

const Post = ({
  content,
  frontmatter,
  slug,
  nextPost,
  previousPost,
}) => (
    <div className="px-10 pt-40 pb-24 space-y-40 md:pt-48">
      <article className="prose prose-lg xl:prose-2xl">
        <PostHeader frontmatter={frontmatter} />
        <ReactMarkdown
          escapeHtml={false}
          source={content}
          renderers={{
            code: CodeBlock,
            inlineCode: InlineCode,
            image: InlineImage,
          }}
        />
      </article>
      <Divider className="mb-20" />

      <RecommendedPosts previousPost={previousPost} nextPost={nextPost} />

      <Divider className="bg-black" />
      <Subscribe
        vertical
        showLottie={false}
        className="w-full p-0 mx-auto"
      />
    </div>
);

const PostHeader = ({ frontmatter }) => (
  <header>
    <h1 className="text-center">
      {frontmatter.title}
    </h1>
    <Image
      className="rounded-lg"
      src={frontmatter.cover_image}
      alt="cover image"
    />
  </header>
);

const RecommendedPosts = ({
  previousPost,
  nextPost,
}) => (
  <section className="flex flex-col items-center mx-auto space-y-20">
    <header>
      <h1 className="text-5xl font-bold">You may also like</h1>
    </header>
    <div className="flex flex-col space-y-10 sm:flex-row sm:space-y-0 sm:space-x-20">
      {previousPost && <RecommendedPostCard post={previousPost} />}
      {nextPost && <RecommendedPostCard post={nextPost} />}
    </div>
  </section>
);

const Divider: React.FC<DividerProps> = ({ className, ...other }) => (
  <hr className={clsx("max-w-4xl mx-auto text-center border-black", className)} {...other} />
);

By separating these components, we can be sure that our code will be easily read and have better composition.

Furthermore, modifying one of these components will be effortless in the future. Each one has a purpose and is isolated from extraneous logic. This means that developers can be sure they are modifying a specific element and are not affecting other features.

As a rule of thumb, every piece of elements that have constituted a specific role in the website can be separated into a component. This includes sections, navigation, cards, buttons, and even the page itself.

This does not mean that everything should be put in a component. It is best to look for those that will improve readability.

As long as you can't read your code like a normal book or article, it probably means you can benefit from the separation. While this is highly subjective, a way to objectively identify it is by looking for duplicate class names and their role on the site.

For example, the two <hr /> in the non-refactored Page component have nearly identical classes. Their only difference was an mb-20 class name in the first tag and bg-black in the second.

<hr className="max-w-4xl mx-auto text-center border-black mb-20"/>
// ...
<hr className="max-w-4xl mx-auto text-center border-black bg-black" />

So, to avoid repetition we created a component and sent the className prop to extend the classes.

const Divider: React.FC<DividerProps> = ({ className, ...other }) => (
  <hr className={clsx("max-w-4xl mx-auto text-center border-black", className)} {...other} />
);

3. Get VS Code Extensions

Since Tailwind CSS is so predictable, it opens a world of possibilities for extensions that improve development productivity and lower the learning curve.

Here are my five favorites:

Tailwind CSS IntelliSense

Tailwind CSS IntelliSense greatly improves the Tailwind development experience by providing advanced features like autocomplete, syntax highlighting, and linting.

I believe this is a must-have. It's very useful for learning Tailwind and remembering class names.

Further, it can read your tailwind.config.js and adapt to its values. This is very helpful when adding color, or an official plugin.

Refactor CSS

Refactor CSS is a neat extension that lets you identify recurring CSS class names in markup. This is an excellent indicator for knowing when to create a component.

Headwind

This one is huge. Headwind is an opinionated class sorter for Tailwind CSS. It enforces a specific order of classes. It creates a seamless organization in your components that is noticeable right away. In my opinion, it's a must-have.

💡 Recently, a new prettier plugin came out for sorting Tailwind classes. It is best to keep an eye on it and try it if you can. It is perfect for enforcing class order for teammates that use other editors or don't have the extension.

Tailwind Shades

Sometimes it is very useful to generate different shades for a specific HEX color. Tailwind Shades allows you to do so quickly and right within your editor.

Tailwind Docs

Tailwind Docs is a tool that makes Tailwind CSS documentation available on the command palette. This is very useful when one needs to remember a concept or is learning the framework. It also makes you avoid having to search on Google for the documentation link.

4. Rely on Plugins

It is no surprise that Tailwind CSS is extensible. Plugins help developers register new styles for Tailwind CSS through JavaScript.

One could go down a rabbit hole on what it is possible through plugins. But, in short, they are useful for teams looking to share their styles through the organization or for developers who wish to generate class names for complex use cases like animations.

Not only can plugins be created for personal or organizational reasons, but also the community creates very useful plugins that make the developer's life a lot easier.

Here are some of the best plugins you can use for speeding up your development:

Tailwind Forms

Tailwind Forms is a plugin developed by the official team of Tailwind CSS. It provides a style reset for form elements, making it easier to override its styles. This one is a must if one is creating custom forms.

Tailwind Typography

Tailwind Typography is another high-quality plugin developed by the Tailwind team. It provides a set of classes that add typographic defaults as Typography.js does.

It's necessary to style any HTML elements one can't control like, for example, those generated from Markdown.

This one is a must for developing websites that consume a CMS and generate elements through a parser.

💡 I use this plugin on my nextjs-starter-blog template. Check it out if you want or need to start a blog!

Tailwind CSS Debug Screens

Tailwind CSS Debug Screens is a small neat utility that shows the currently active responsive breakpoint. It is very useful when making layouts since one does not have to go to development tools to see current dimensions.

Tailwind CSS Theming

Tailwind CSS Theming is a plugin that solves the problem of multiple themes within Tailwind. It's perfect for applications that rely on CSS variables to change themes dynamically. I highly recommend this plugin if your project has more than one theme or needs a quick solution for handling themes.

Its main benefit is its readable and straightforward syntax.

// Extracted from:
// https://github.com/innocenzi/tailwindcss-theming/blob/master/docs/quick-start.md
// theme.config.js

const { ThemeManager, Theme } = require("tailwindcss-theming/api");

const base = new Theme().addColors({
  brand: "#44b3ac", // Your brand color
  "on-brand": "#ffffff", // For everything that goes on your brand color
  background: "#f7fafc", // A background color
  "on-background": "#1a202c", // For everything that goes on your background color
});

const dark = new Theme().addColors({
  brand: "#44b3ac", // Your brand color
  "on-brand": "#ffffff", // For everything that goes on your brand color
  background: "#1c1e26", // A background color
  "on-background": "#d5d8da", // For everything that goes on your background color
});

module.exports = new ThemeManager()
  .setDefaultTheme(base) // Sets the `base` theme as the default theme.
  .setDefaultDarkTheme(dark); // Sets the `dark` theme as the default theme for users that prefer the `dark` scheme.

5. Use Pre-Built Components

Since separating into small components is so easy in Tailwind, it is no surprise that its community has created a lot of beautiful component abstractions with it. There are even websites dedicated to this.

Here are some websites or libraries you can use to get pre-built components:

Tailwindcomponents

Tailwindcomponents is a free repository of open source components created by the community. This website is a gem because one can find pretty much anything one needs.

Everyone can submit their components and help other developers in building or learning layouts with Tailwind. Even Adam Wathan, the creator of Tailwind, submits layouts!

Tailwind Toolbox

Tailwind Toolbox is similar to Tailwindcomponents. It has many useful components and additional templates, plugins, tools, and generators. However, it only allows users to suggest resources and not upload their own. This means that content will not be as diverse and abundant as Tailwindcomponents, but it's very useful nonetheless.

Tailwind UI

Tailwind UI is a beautiful UI library created by Adam Wathan, and Steve Schoger, author of Refactoring UI. It contains a lot of components, albeit mostly behind a paywall. Nevertheless, the free samples are very high quality and can be useful to give an idea of how to implement a UI.

Tailblocks

Tailblocks is a website that contains common layouts done with Tailwind CSS. They are very useful for kicking off a website quickly.

Gust UI

Gust UI is a very simple component library built with Tailwind. I recommend this site if you need to get some quick React logic for common components like Sliders, Toggles, etc.

Meraki UI

Meraki UI is a Tailwind component library similar to Tailwind UI. It features common layouts and components for common use cases like authentication, navigation, footer, etc. It is worth checking out, especially since it's completely free.

Reach UI

Reach UI is a lifesaver for developers looking to create an accessible design system without dealing with the hassle of creating each component by hand. While these components are not made with Tailwind, they are open to being styled by it because of its granularity.

Its only disadvantage is that its styles must be overridden through an external stylesheet or by setting global important in Tailwind's config. Nevertheless, these can save a lot of time.

6. Use Other Styling Solutions

While this may seem counterproductive given how Tailwind CSS is a solution itself, using another one like CSS Modules or Styled Components is recommended to handle the heavy lifting. 90% of the time you should be using Tailwind, but any complex animation or new property is better handled through the former.

For example, let's say we want to set a max-width for a special component for a specific blog post. We wouldn't like to create a Tailwind class just for one use case, and inline objects may be off the charts because of preference.

Pairing up CSS Modules and Tailwind can solve this conundrum, since one can write Tailwind classes right alongside CSS properties. This makes it extremely powerful and makes stylesheets simpler and easier to maintain.

.root {
  @apply h-full bg-primary mx-auto transition-colors duration-150;

  max-width: 590px;
}

// Called in our code as:
import s from "./styles.module.css"

<section className={s.root}></section>

Another popular way of pairing up Tailwind is through a CSS-in-JS library like Styled Components. Recently, a library called twin.macro has received a lot of hype between developers. It allows developers to integrate Tailwind on an existing codebase with a CSS-in-JS library. This means it has all the benefits of CSS-in-JS: low build times, JavaScript integration, etc. Its syntax looks like this:

import tw, { styled } from "twin.macro";

const Input = styled.input`
  color: purple;
  ${tw`border rounded`}
`;

const Component = () => <Input />;

Check it out if you love CSS-in-JS and like to start having some of the benefits of Tailwind CSS.

Conclusion

Tailwind is an amazing CSS framework, and I expect to keep using it in the foreseeable future. By using these tips, I've found that my codebases are easy to read and seamless to maintain. I hope these were useful to you. If there is any tip or resource you think is relevant for this post, please leave it in the comments down below.

For more up-to-date web development content, follow me on Twitter, and Dev.to! Thanks for reading! 😎

Why Use Tailwind CSS for Your Next Project

Jose Felix — Tue, 17 Nov 2020 19:40:35 +0000

Tailwind CSS is a low-level, customizable CSS framework that is on the rise. It's frequently compared to Bootstrap. However, they are fundamentally different. Instead of delivering pre-designed components as Bootstrap does, Tailwind gives building blocks that allow the developer to build designs in no time at all.

Before I came across Tailwind, I started with CSS, moved to SCSS, and then moved to Styled Components. Throughout my journey, I had a lot of great experiences with each technology, however, none brought me the satisfaction and productivity boost that Tailwind has.

A Long Journey

Writing pure CSS is very good as a beginner since one can fully understand and memorize the rules needed to achieve a specific layout. Even as an advanced developer, one can reap very good results by being able to write custom CSS that matches exactly what is needed. Nevertheless, these rules most likely won't scale. Each element in the UI will require its own set of rules, and keeping track of hundreds of these rules can become daunting, and hard to maintain. This does not mean that it is impossible to keep them in check. With due practice and discipline, they can be organized and maintained very well.

To solve this problem, I moved from CSS to SCSS with a 7 in 1 architecture. At first, I loved how well my code was separated into 7 folders that represent specific components and sections of the site. Also, it opened a world of possibilities with new features like variables, functions, and nested rules. This made it a lot easier to guarantee that my site styles were easy to find and maintain. Nevertheless, I wanted to embed my styles inside my JavaScript, so I don't have to hop between files continuously. This is why I started using a CSS-in-JS solution like Styled Components.

Styled Components is my go-to whenever I cannot use Tailwind in a project. It is such an amazing library since it allows me to have all my styles exactly where they need to be used. Also, it makes the app use only the styles it needs, instead of importing all styles on each page. Even though it is by far a great upgrade from other solutions, it still had a problem: repetition. I felt I was writing the same rules over and over, and losing needed time. Also, my styles just kept getting bigger and bigger. When I realized this and found Tailwind, I chose to move on and I have never looked back since.

Syntax

Tailwind's syntax is very basic: append to HTML or JSX elements class names that represent one or more CSS declarations. Here is what it looks like:

<div class="max-w-sm mx-auto flex p-6 bg-white rounded-lg shadow-xl">
  <div class="flex-shrink-0">
    <img class="h-12 w-12" src="/img/logo.svg" alt="ChitChat Logo" />
  </div>
  <div class="ml-6 pt-1">
    <h4 class="text-xl text-gray-900 leading-tight">ChitChat</h4>
    <p class="text-base text-gray-600 leading-normal">
      You have a new message!
    </p>
  </div>
</div>

This will generate the following:

Each class name represents one or various CSS declarations. For example, flex represents display: flex;; p-6 padding: 1.5rem; mx-auto margin-left: auto; margin-right: auto;; and so forth.

This paradigm is called utility-first. It consists of building complex components from a constrained set of primitive utilities.

By using this approach, Tailwind obtains a myriad of benefits compared to custom CSS.

Smaller Styles

The first benefit of using Tailwind is writing CSS that does not grow linearly. By having utility class names that will be shared between elements, it guarantees a consistent bundle size. Furthermore, Tailwind paired with Purge CSS will remove any unused styles so the codebase will not be bloated with extra classes.

A site's CSS bundle with Tailwind CSS will look like this:

Styles may start higher at a certain point, but in the future, with more features, these styles will remain constant and save a lot of kilobytes.

Facebook adopted a similar approach, albeit with a custom CSS-in-JS library that leverages atomic CSS which is very similar to Tailwind's utility-first approach. With this approach, they reduced their CSS bundle size in their whole site from 413kb to 74kb. That is an ~82% reduction! And now we have this power in our hands without having to create a custom library.

💡 Atomic CSS classes can only have a unique CSS declaration. This differs greatly from utility-first CSS where classes can have multiple declarations.

Less Cognitive Load

Tailwind is designed to be component friendly. It is so much easier to separate a site's elements into smaller components and not pollute the codebase with objects or extraneous CSS classes. Furthermore, every class is inlined in the component, making it much easier to read and understand.

Take for example this navigation bar component with Styled Components:

const Navbar = () => {
  return (
    <Wrapper>
      <Items>
        <NavItem label="Home" icon={<Home size={16} />} />
        <NavItem label="Blog" icon={<Bookmark size={16} />} />
        <NavItem label="About" icon={<User size={16} />} />
      </Items>
    </Wrapper>
  );
};

const Wrapper = styled.nav`
  position: fixed;
  width: 100vw;
  bottom: 0;

  justify-content: center;
`;

const Items = styled.ul`
  flex: 1;
  padding: 0 2rem;

  justify-content: space-around;
`;

const NavItem = ({ label, icon, ...otherProps }) => (
  <Item {...otherProps}>
    <span>{icon}</span>
    {label}
  </Item>
);

const Item = styled.li`
  display: flex;
  flex-direction: column;
  align-items: center;

  font-size: 1.2rem;
`;

In my opinion, this snippet is very well organized, and it can be understood after it has been read.

Let's look at its Tailwind implementation:

const Navbar = () => {
  return (
    <nav className="fixed bottom-0 justify-center w-screen">
      <ul className="justify-around flex-1 px-8">
        <NavItem label="Home" icon={<Home size={16} />} />
        <NavItem label="Blog" icon={<Bookmark size={16} />} />
        <NavItem label="About" icon={<User size={16} />} />
      </ul>
    </nav>
  );
};

const NavItem = ({ label, icon, ...otherProps }) => (
  <li className="flex flex-col items-center text-xl" {...otherProps}>
    <span>{icon}</span>
    {label}
  </li>
);

Tailwind on the get-go consumes a lot less space. Also, its styles can be understood right away since they are read at the same time the developer scans the code. One does not have to jump over the file just to see its styles.

In this small example, it may not be obvious how cumbersome this can become in larger files. But on large codebases with multiple components per file, it is a nightmare to have all these separate styles between components. It takes a lot more time compared to Tailwind to understand how each element composes a UI.

You may be asking how one can reap the benefits of Styled Components' main forte: to permit the use of JavaScript in styling. This will depend on the context of the solution.

One can leverage the usage of an inline style object or conditional class names.

// Inline object
<CustomComponent styles={{ color: fontColorByBackground("#000") }} />;

// Conditional classes
import clsx from "clsx";
<CustomComponent
  className={clsx("flex", {
    "text-black": luminance > 0.18,
    "text-white": luminance < 0.18,
  })}
/>;

However, this may not be the most attractive solution for some teams. The good news is that since we are dealing with CSS, we can just use both Tailwind and Styled Components without cost (Emotion CSS prop or CSS modules can be a better match for Tailwind's paradigm).

💡 Keep in mind that Tailwind is the predominant solution, so one can reap its benefits. Styled Components is optional for heavy CSS/JavaScript manipulations. Also, this makes it easier for codebases that want to move on to Tailwind at an incremental pace.

Better Composition

Tailwind by default makes the developer think in components. It makes us want to keep it small and avoid repeatability. This is possible thanks to the low amount of space it requires to achieve a layout; how it makes us notice when styles are repeated or bloated; and how easy it is to read and remember styles when split into small components.

Think of this practice as creating CSS class names for every feature or section of a website. Instead of doing it in terms of CSS, we would do it for HTML. For example, if we have a Hero, then it will be best to have a component that represents the Hero section. Likewise, we could do the same with blog postcards, navigation, header, etc.

Let's look at the next snippet:

const IndexPage = () => {
  return (
    <section className="container p-2 mx-auto lg:p-8 xl:p-0">
      <h1 className="font-bold text-white text-11xl sm:text-12xl">Blog.</h1>
      <div className="flex flex-col mx-auto space-y-8 md:grid md:row-gap-6 md:col-gap-8 md:grid-cols-2">
        {posts.map(
          ({ frontmatter: { title, description }, slug, hasCoverImage }, i) => {
            const isFirstItem = i === 0;

            return (
              <div
                key={slug}
                className={clsx(
                  "w-full bg-white rounded-md font-body relative overflow-hidden",
                  isFirstItem && "md:col-span-2",
                  !isFirstItem && "md:col-span-1",
                )}
              >
                <a href="#">
                  {hasCoverImage && (
                    <img
                      className="object-contain w-full rounded-md md:object-cover"
                      src={src}
                      alt="cover image"
                    />
                  )}
                  <header className="flex flex-col items-center p-12 space-y-4 text-center bg-white rounded-md">
                    <h1 className="max-w-6xl text-5xl font-bold">{title}</h1>
                    <p className="max-w-5xl text-2xl font-medium">
                      {description}
                    </p>
                  </header>
                </a>
              </div>
            );
          },
        )}
      </div>
    </section>
  );
};

You'll notice it is hard to read and understand what its intent is unless one reads it meticulously. Classes are all over the place and HTML elements lack coherence. Immediately one knows there must be a better way to represent it.

If we start separating it into components, we immediately see its benefits:

const IndexPage = ({ posts }) => {
  return (
    <div className="container p-2 mx-auto lg:p-8 xl:p-0">
      <h1 className="font-bold text-white text-11xl sm:text-12xl">Blog.</h1>
      <Posts posts={posts} />
    </div>
  );
};

const Posts = ({ posts }) => (
  <div className="flex flex-col mx-auto space-y-8 md:grid md:row-gap-6 md:col-gap-8 md:grid-cols-2">
    {posts.map((postInfo, i) => {
      const isFirstItem = i === 0;

      return (
        <PostCard key={postInfo.slug} isFirstItem={isFirstItem} {...postInfo} />
      );
    })}
  </div>
);

const PostCard = ({
  frontmatter: { title, description },
  hasCoverImage,
  isFirstItem,
}) => (
  <div
    className={clsx(
      "w-full bg-white rounded-md font-body relative overflow-hidden",
      isFirstItem && "md:col-span-2",
      !isFirstItem && "md:col-span-1",
    )}
  >
    <a>
      {hasCoverImage && (
        <img
          className="object-contain w-full rounded-md md:object-cover"
          src={src}
          alt="cover image"
        />
      )}
      <header className="flex flex-col items-center p-12 space-y-4 text-center bg-white rounded-md">
        <h1 className="max-w-6xl text-5xl font-bold">{title}</h1>
        <p className="max-w-5xl text-2xl font-medium">{description}</p>
      </header>
      <div className="absolute top-0 right-0 px-6 py-8 mr-8 text-white bg-black">
        <p className="block font-semibold">Read more</p>
      </div>
    </a>
  </div>
);

Not only is it easier to read in the short term, but when we come back to it, we'll be able to understand it quicker. Also, when our code grows in size and may want to reuse elements like 'Read More', we can create a component of it easily and share it between elements.

ℹ This practice does not apply only to Tailwind. It should be used in all cases. However, Tailwind makes it easier to notice when to do it since its class names are agnostic to the implementation. CSS or CSS-in-JS libraries make you think the other way around: create classes or objects that are meant for only one context.

Higher productivity

It is no surprise that writing Tailwind classes is faster than writing CSS or CSS-in-JS. When we are adding declarations to selectors in a stylesheet, we have to write the property and value and add a colon. Thankfully, IDEs and text editors automatically help us with autocomplete and formatting. However, we still have to write the selectors and pieces of declarations to trigger autocomplete. By just writing styles inline, Tailwind in the long-term makes the process a lot faster.

Also, Tailwind has something called variants which are prefixes that can be added to classes, representing a specific CSS pseudo-class, a responsive breakpoint, or custom plugins.

Take for example media queries. In normal CSS, we would have:

/* Small (sm) */
@media (min-width: 640px) {
  /* ... */
}

/* Medium (md) */
@media (min-width: 768px) {
  /* ... */
}

/* Large (lg) */
@media (min-width: 1024px) {
  /* ... */
}

/* Extra Large (xl) */
@media (min-width: 1280px) {
  /* ... */
}

This may seem easy to read. However, imagine having hundreds of classes. Soon it may become hard to read and slow to modify.

Now, let's look at Tailwind's:

<!-- Width of 16 by default, 32 on medium screens, and 48 on large screens -->
<img class="w-16 md:w-32 lg:w-48" src="..." />

Here we define a width for each breakpoint. What makes this incredible is that we are scoping the styles within an element. Later, it will be a lot easier to remove or modify the declaration since it will not mesh within hundreds of rules.

Likewise, pseudo-classes translate more easily in Tailwind than in CSS. In this case, it is not because of maintainability or readability, but by the ease of writing. Adding a prefix is a lot faster than adding a whole new rule:

<input class="w-16 bg-orange-500 hover:bg-blue-500 focus:bg-red-500" />

<!-- 
Translates to: 

.block {
    width: 4rem;
    background: #ed8936;
}

.block:hover {
    background: #4299e1;
}

.block:focus {
    background: #f56565;
}

 -->

Finally, we have custom plugins. They allow you to add custom prefixes that will enhance your class's behavior. For example, they allow the developer to add a class depending on a condition like dark mode or overriding other classes by assigning !important.

<!-- Dark mode (Coming in v2) -->
<div className="bg-black dark:bg-white" />

<!-- Important (https://github.com/chasegiunta/tailwindcss-important) -->
<div className="!bg-red" />

Consistency

In addition to writing styles faster, Tailwind has a lot of pre-built classes for sizing and colors that will reduce or completely remove the need to implement a design system. This also means that there is a lower learning curve for an experienced developer in Tailwind to learn the styles on an existing project with it.

💡 You may be asking how consistent it is on browsers. Since Tailwind is such a low-level framework, it means that support for older browsers is up to the developer not to their implementation like bootstrap does.

High Customization

Tailwind gives the developer a generous default theme that will work very well for bootstrapped projects. Nonetheless, it exhorts developers to extend or modify these classes through the tailwind.config.js file.

Tailwind's configuration file allows developers to tamper right into Tailwind. Any change will be reflected in the final stylesheet. It also allows adding custom plugins, which opens a world of possibilities for third-parties.

Many developers when starting to use Tailwind will complain about one-off styles. Contrary to plain CSS, Tailwind may seem constricted to new styles since the default classes are abundant and look like they follow a specification like Bootstrap. However, since classes in Tailwind normally represent one CSS declaration, it is possible to extend, add, or remove them easily.

On the other hand, developers sometimes refuse to extend this configuration since they don't want to delve into the documentation, or just want to add multiple declarations to one class mainly for a component.

Since Tailwind uses PostCSS as its pre-processor, it means that it can extend its capabilities well outside its configuration file. The majority of codebases will have a CSS file that imports Tailwind styles through PostCSS.

Inside this file, one can create normal CSS classes but also using Tailwind's generous amounts of classes. Like this:

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

@layer components {
  .btn-blue {
    @apply bg-blue-500 text-white font-bold py-2 px-4 rounded;
  }
  .btn-blue:hover {
    @apply bg-blue-700;
  }
}

Overall, this means that everything that can be done in CSS is possible within Tailwind!

Great Upgrade Path

Tailwind's future is very bright. New updates come frequently. These add new CSS properties that are coming out for modern browsers, new prefixes, convenient PostCSS directives, new classes, and many more.

For example, in the upcoming 2.0 version, we'll be getting a new prefix for the dark mode. Previously, adding dark mode required some workarounds, however, now it will be native and easy to add by pre-pending dark: to classes applied on dark mode.

<div
  class="bg-white text-black dark:bg-black dark:text-white dark:hover:text-gray-300"
/>

Also, in version 1.7 (currently on version 1.9.6), we saw the addition of text background-clip for creating cool gradients texts. These are just a few examples of great updates that improve drastically the development experience and productivity.

Drawbacks

Tailwind CSS has a lot of benefits like increasing performance, consistency, and productivity. Regardless, it does not mean it is perfect for every codebase or developer team.

One of Tailwind's weaknesses can be its readability. At first, it may not seem obvious, but when a considerate amount of classes are added to an element, it can become daunting to read for some developers. Personally, I haven't had many problems with this, and I believe that with correct component abstractions this can be easily solved. Nonetheless, many developers can see this as a disadvantage.

Another of Tailwind's weaknesses is creating complex animations. Even though simple animations are included out-of-the-box and more can be added through the configuration, complex animation orchestrations are very hard to achieve.

For creating a complex animation, one would have to create a class name for each element. This will end up being more work than doing it within CSS. Thankfully, this can also be easily solved using Plain CSS through stylesheets, an animation library like Framer Motion, or a CSS-in-JS library like Styled Components. I believe any of these is valid and encouraged with Tailwind, however, some developers would just prefer to just use plain CSS for their animation without any library.

Another weakness is the need to learn an opinionated naming convention. This is a double-edged sword. On one hand, having opinionated styles means once learned, knowledge is transferable between projects and productivity greatly increases. On the other hand, one has to dedicate time to learn all nuances and how it works before being able to create something useful.

In my opinion, if one knows CSS, the Tailwind naming convention will be very easy to learn since its class names are very similar to plain CSS. Also, their proprietary extension provides autocomplete so that developers can ease in when learning or remembering class names.

Nevertheless, some teams will still be reluctant to introduce a framework that requires a learning curve, especially when time is a luxury.

Conclusion

Tailwind as a low-level CSS framework has become my preferred styling solution. It has solved most of the drawbacks I have encountered in my journey through different CSS solutions. It has increased my productivity, reduced the bundle size of my apps, made me more consistent, and changed my development paradigm.

Even though Tailwind has worked very well for me and many other developers, it does not mean that it is the perfect solution for every project. Evaluating its benefits for a codebase and its effects on the team are necessary before considering adopting it.

In the future, I see Tailwind growing more and being implemented in many projects even with an existing CSS solution. I've started seeing many modern projects that have started doing this like the Vercel e-commerce template.

In the end, Front-End developers are working with CSS. This means we can mesh different solutions as long as we guarantee maintainability, scalability, and performance. With this in mind, Tailwind is definitely one solution that must be considered for its myriad of benefits.

For more up-to-date web development content, follow me on Twitter, and Dev.to! Thanks for reading! 😎

Page Transitions In React

Jose Felix — Mon, 19 Oct 2020 19:47:43 +0000

Smooth and cool page transitions are something we all love to see while browsing on Dribbble. I have always been fascinated and asked myself how I could do it for my sites.

Once, I was able to achieve it in a site built with Next.js by using a library called next-page-transitions. It allowed me to create the transitions I wanted with CSS. However, I hit a problem.

It was very limiting and inflexible since it was made through CSS classes. I couldn't create a custom experience on every page without having a lot of classes and having to deal with re-renders. Thankfully, Framer Motion's Animate Presence API makes it possible to create sleek and custom page transitions in any React framework easily without having to worry about these problems.

Animate Presence

In my previous post, I introduced the <AnimatePresence/> component. It triggers the exit prop animations from all its children when they're removed from React's render tree. Basically, it detects when a component unmounts and animates this process.

Recently, Framer Motion introduced a prop called exitBeforeEnter. If it is set to true, it will only render one component at a time. It will wait for the existing component to finish its animation before the new component is rendered. This is perfect for handling page transitions since we can guarantee that only a component or page is rendered at a time.

A Small Example

Let's test what we learned about <AnimatePresence/>. First, we'll test it without the exitBeforeEnter prop by doing a simple transition to see how it behaves.

This website will be a mimic of an E-commerce. It will have two pages: Store and Contact Us. They will have a very simple layout. Like this:

Our first step is to wrap our pages inside a <AnimatePresence/>. Where we wrap it will depend on where our router is rendering the pages. Keep in mind that each of the children needs to have a unique key prop so it can track their presence in the tree.

In Next.js we would head to the _app.js file, and wrap the <Component> with <AnimatePresence/>.

// pages/_app.js

import { AnimatePresence } from "framer-motion";
import "../styles/index.css";

function MyApp({ Component, pageProps, router }) {
  return (
    <AnimatePresence>
      <Component key={router.route} {...pageProps} />
    </AnimatePresence>
  );
}

export default MyApp;

For Create React App, we would use it wherever our router is rendering the pages.

import React from "react";
import { Switch, Route, useLocation, useHistory } from "react-router-dom";
import { AnimatePresence } from "framer-motion";

const App = () => {
  const location = useLocation();

  return (
    <AnimatePresence>
      <Switch location={location} key={location.pathname}>
        <Route path="/contact" component={IndexPage} />
        <Route path="/contact" component={ContactPage} />
      </Switch>
    </AnimatePresence>
  );
};

💡 Check out the website's code for each framework in this GitHub repository.

Now that we have all our pages wrapped in an <AnimatePresence>, if we try to change routes, you'll notice that the current component never unmounts.

This happens because Framer Motion is looking for an exit animation for each page, and it is not found because we haven't defined any motion component yet.

Let's add a simple fade-out animation to each page. Like this:

import { motion } from "framer-motion"

<motion.div exit={{ opacity: 0 }}>
    ... content
</motion.div>

And now the components can unmount!

If you pay close attention, before our contact form disappears, the index page appears at the bottom, creating a distraction and ruining the fluidity of our animation. This would be really bad if we were to have a mount animation on the Index page.

This is where the exitBeforeEnter prop comes in handy. It guarantees that our component will have unmounted before allowing the new component to load in. If we add the prop to the <AnimatePresence/>, you will notice it is no longer a problem, and our transition is smooth and working as desired.

<AnimatePresence exitBeforeEnter/>

This is all that is needed to create transitions with Framer Motion. The sky is the limit when it comes to what we can do now!

A Beautiful Transition From Dribbble

Have you ever wanted to create amazing transitions like those seen in Dribbble? I always have. Thankfully, Framer Motion allows us to re-create these with ease. Take a look at this design by Franchesco Zagami:

Let's try to re-create this awesome transition.

When translating transition prototypes, it would be best to have the original file so the easings and details of the animation can be known. However, since we are taking a Dribbble design, we'll re-create it by estimating its values.

Initial Transition

One of the elements that we first see is a black background that moves toward the end of the screen. This is really easy to re-create because of Framer's abstractions.

First, we'll create a component that will house all our initial transition logic so it can be easier to maintain and develop.

const InitialTransition = () => {};

Second, add the black square which will have the size of the screen.

const blackBox = {
  initial: {
    height: "100vh",    
  },
};

const InitialTransition = () => {
  return (
    <div className="absolute inset-0 flex items-center justify-center">
      <motion.div
        className="relative z-50 w-full bg-black"
        initial="initial"
        animate="animate"
          variants={blackBox}
      />      
    </div>
  );
};

Instead of using motion props, we'll use variants since further down we'll have to handle more elements.

💡 If you want to learn how to use Framer Motion variants, you can check out my beginner's tutorial!

So far, we will have a black square in the middle of our screen. We'll use the bottom and height properties to create a downward movement. The bottom property will make it collapse towards the bottom.

const blackBox = {
  initial: {
    height: "100vh",
    bottom: 0,
  },
  animate: {
    height: 0,    
  },
};

const InitialTransition = () => {
  return (
    <div className="absolute inset-0 flex items-center justify-center">
      <motion.div
        className="relative z-50 w-full bg-black"
        initial="initial"
        animate="animate"
          variants={blackBox}
      />      
    </div>
  );
};

This is what we have now:

If you compare this to our reference, you'll notice the animation happens very quickly and not fluid enough. We can fix this with the transition property. We'll modify the duration to make our animation slower and ease to make it smoother.

const blackBox = {
  initial: {
    height: "100vh",
    bottom: 0,
  },
  animate: {
    height: 0,
    transition: {
      duration: 1.5,
      ease: [0.87, 0, 0.13, 1],
    },
  },
};

It will look much more similar:

Now, we have to re-create the text. Albeit, we'll do something different. Since our text is not located in the middle of our navbar, we'll just fade it out.

The text is a little harder than the black square because if we take a close look it has an animated layer similar to a mask. A way we could achieve this effect is through SVG elements, specifically the <text/> and <pattern/>. It will look like this:

<motion.div
  className="absolute z-50 flex items-center justify-center w-full bg-black"
  initial="initial"
  animate="animate"
  variants={blackBox}
>
    <motion.svg className="absolute z-50 flex">
      <pattern
        id="pattern"
        patternUnits="userSpaceOnUse"
        width={750}
        height={800}
        className="text-white"
      >
        <rect className="w-full h-full fill-current" />
        <motion.rect className="w-full h-full text-gray-600 fill-current" />
      </pattern>
      <text
        className="text-4xl font-bold"
        text-anchor="middle"
        x="50%"
        y="50%"
        style={{ fill: "url(#pattern)" }}
      >
        tailstore
      </text>
    </svg>
</motion.svg>

This works by setting a custom text fill with <pattern/>. It will have two <rect/>. One for the color of the text and the other for the animation which will be a motion element. Basically, the latter will hide and will leave a white color.

Let's proceed to animate this.

First, let's introduce a new transition property called when. It defines when an element should carry out its animation. We want our black box to disappear when all children are done rendering hence afterChildren:

const blackBox = {
  initial: {
    height: "100vh",
    bottom: 0,
  },
  animate: {
    height: 0,
    transition: {
      when: "afterChildren",
      duration: 1.5,
      ease: [0.87, 0, 0.13, 1],
    },
  },
};

Now, when our text finishes rendering, our black box will do its animation.

Second, we'll animate the <svg/> . Here is its variant:

const textContainer = {
  initial: {
    opacity: 1,
  },
  animate: {
    opacity: 0,
    transition: {
      duration: 0.25,
      when: "afterChildren",
    },
  },
};

<motion.svg variants={textContainer} className="absolute z-50 flex"></motion.svg>

Finally, the <rect/>:

const text = {
  initial: {
    y: 40,
  },
  animate: {
    y: 80,
    transition: {
      duration: 1.5,
      ease: [0.87, 0, 0.13, 1],
    },
  },
};

<motion.rect
  variants={text}
  className="w-full h-full text-gray-600 fill-current"
/>

💡 You may be asking yourself where do I get most of these animation values. All of them except the ease were fine tweaked through estimation. For easing, I used this cheat sheet, specifically the easeInOutExpo values.

With all these hooked up, you should see this:

Awesome! It's looking very close to our design.

You may have noticed that we can still scroll even though our screen is supposed to be busy showing our transition. Luckily this is really easy to fix. We just need to apply overflow: hidden to our body when it is animating and remove it when it's done.

Thankfully, motion components have event listeners for this exact situation: onAnimationStart, and onAnimationComplete. The former is triggered when the animation defined in animate starts and the latter when it ends.

On our InitialTransition add the following:

<motion.div
  className="absolute z-50 flex items-center justify-center w-full bg-black"
  initial="initial"
  animate="animate"
  variants={blackBox}
  onAnimationStart={() => document.body.classList.add("overflow-hidden")}
  onAnimationComplete={() =>
    document.body.classList.remove("overflow-hidden")
  }
> 
</motion.div>

Animating the Content

All that is left is to create sleek animation for our content. We won't copy the same animation as the design since it wouldn't match our site very well. What we'll do is a staggering fade in down effect on the children. Let's create our variants:

const content = {
  animate: {
    transition: { staggerChildren: 0.1, delayChildren: 2.8 },
  },
};

const title = {
  initial: { y: -20, opacity: 0 },
  animate: {
    y: 0,
    opacity: 1,
    transition: {
      duration: 0.7,
      ease: [0.6, -0.05, 0.01, 0.99],
    },
  },
};

const products = {
  initial: { y: -20, opacity: 0 },
  animate: {
    y: 0,
    opacity: 1,
    transition: {
      duration: 0.7,
      ease: [0.6, -0.05, 0.01, 0.99],
    },
  },
};

export default function IndexPage() {
  return (
    <motion.section exit={{ opacity: 0 }}>
      <InitialTransition />

      <motion.div
        initial="initial"
        animate="animate"
        variants={content}
        className="space-y-12"
      >
        <motion.h1 variants={title} className="text-6xl font-black text-center">
          Welcome to tailstore!
        </motion.h1>

        <motion.section variants={products} className="text-gray-700 body-font">
        </motion.section>
      </motion.div>
    </motion.section>
  );
}

You'll be familiar with most of the properties except delayChildren. It applies a delay to all the children of a propagated animation. In other words, it will display the children after a certain amount of time.

Aside from this, we are just making the element fade down, add a duration of 0.7 seconds, and smooth it with an easing. Here is the result:

Let's do the same for our contact page:

const content = {
  animate: {
    transition: { staggerChildren: 0.1 },
  },
};

const title = {
  initial: { y: -20, opacity: 0 },
  animate: {
    y: 0,
    opacity: 1,
    transition: {
      duration: 0.7,
      ease: [0.6, -0.05, 0.01, 0.99],
    },
  },
};

const inputs = {
  initial: { y: -20, opacity: 0 },
  animate: {
    y: 0,
    opacity: 1,
    transition: {
      duration: 0.7,
      ease: [0.6, -0.05, 0.01, 0.99],
    },
  },
};

<motion.section
  exit={{ opacity: 0 }}
  class="text-gray-700 body-font relative"
>
  <motion.div variants={content} animate="animate" initial="initial" class="container px-5 py-24 mx-auto">
    <motion.div variants={title} class="flex flex-col text-center w-full mb-12">     
    </motion.div>
    <motion.div variants={inputs} class="lg:w-1/2 md:w-2/3 mx-auto">        
    </motion.div>
  </motion.div>
</motion.section>

UX Improvements

Transitioning between Contact and Store will take a long while since it will play the initial transition again. Doing this every time will annoy the user.

We can fix this problem by only playing the animation if it is the first page the user loads. To achieve this, we'll listen for a route change globally, and determine if it is the first render. If it is, we'll show the initial transition; otherwise, skip it and remove the delay on the children.

In Next.js we would detect a route change through the routeChangeStart event on _app.js.

💡 Solutions will vary between frameworks. For the sake of keeping this blog post as simple as possible, I will elaborate on Next.js implementation. However, the repository will have solutions in their respective frameworks.

On _app.js:

function MyApp({ Component, pageProps, router }) {
  const [isFirstMount, setIsFirstMount] = React.useState(true);

  React.useEffect(() => {
    const handleRouteChange = () => {
      isFirstMount && setIsFirstMount(false);
    };

    router.events.on("routeChangeStart", handleRouteChange);

    // If the component is unmounted, unsubscribe
    // from the event with the `off` method:
    return () => {
      router.events.off("routeChangeStart", handleRouteChange);
    };
  }, []);

  return (
    <Layout>
      <AnimatePresence exitBeforeEnter>
        <Component
          isFirstMount={isFirstMount}
          key={router.route}
          {...pageProps}
        />
      </AnimatePresence>
    </Layout>
  );
}

We are keeping the state on the first mount which is updated only when a user does the first route change. And, we pass this variable as a prop to the currently rendered page.

On our index.js :

const content = (isFirstMount) => ({
  animate: {
    transition: { staggerChildren: 0.1, delayChildren: isFirstMount ? 2.8 : 0 },
  },
});

// ...

export default function IndexPage({ isFirstMount }) {
  return (
    <motion.section exit={{ opacity: 0 }}>
      {isFirstMount && <InitialTransition />}

      <motion.div
        initial="initial"
        animate="animate"
        variants={content(isFirstMount)}
        className="space-y-12"
      >
        <motion.h1 variants={title} className="text-6xl font-black text-center">
        </motion.h1>

        <motion.section variants={products} className="text-gray-700 body-font">        
        </motion.section>
      </motion.div>
    </motion.section>
  );
}

That's it! Our page has amazing transitions and the user will not feel annoyed by replaying the same animation over and over.

Conclusion

Sleek page transitions are very important to achieve awesome web experiences. Using CSS can be hard to maintain since one will deal with many classes and lack of independence. Thankfully, Framer Motion solves this problem with Animate Presence. Coupled with exitBeforeEnter, it allows developers to create amazing page transitions. It is so flexible and powerful that through a few lines of code, we could mimic a complex animation found on Dribbble.

I hope this post inspires you to create awesome page transitions so you can impress your future employer or clients.

For more up-to-date web development content, follow me on Twitter, and Dev.to! Thanks for reading! 😎

Getting Started with React Animations

Jose Felix — Tue, 08 Sep 2020 20:03:43 +0000

Interaction plays a key role in shaping the experience a user has on an application. Animations help define these interactions since the user's eyes tend to pay attention to moving objects. These catchy and moving elements tell a story that helps the application differentiate from competitors and bring a better user experience.

Creating animations can be daunting, especially programming and handling orchestrations (how these coordinate between each other). Thankfully, amazing people have created abstractions in libraries that allow the developer to create seamless, hardware-accelerated animations efficiently.

In this post, I will give an introduction to Framer Motion and create simple animations with it. We'll be learning about motion components, orchestration, dragging, and automatic animations.

React Animation Libraries

In React, we have two main animation libraries: React Spring and Framer Motion. I like both of them, but I believe each one has a use case.

React Spring is a spring-physics based animation library. These animations emulate real spring physics for smooth animations. It is really powerful and flexible. Almost all properties of HTML tags can be fully animated with React Spring. This is especially important for complex and SVG animations. However, its main disadvantage is its high learning curve.

Framer Motion is a motion library. It is easy to learn and powerful with orchestrations. Contrary to React Spring, it has more types of animations: spring, tween, and inertia. Tweens represent duration-based animations like CSS, and inertia decelerates a value based on its initial velocity, usually used to implement inertial scrolling.

Framer Motion is perfect for handling animations on 99% of sites. Its main disadvantage is its lack of documentation and some properties won't work for SVG animations.

Choosing between these libraries depends greatly on what you are building and how much you are willing to devote to learning animations. React Spring can do all that Framer Motion does with more flexibility, but it is harder to read and understand. I recommend it for custom, complex animations especially for SVG and 3D (Three.js).

For most websites, Framer Motion is better since it can handle most common cases and its learning curve is really low compared to React Spring. Also, its way of handling animations is more intuitive and declarative. This is why we'll focus on this library and learn about animations with it. The fundamentals of Framer Motion will be transferable to React Spring. However, its syntax will be more abstract.

How It Works: Motion components

Framer Motion's core API is the motion component. There's a motion component for every HTML and SVG element. They work exactly the same as their HTML counterparts but have extra props that declaratively allow adding animations and gestures.

Think of the motion component as a big JavaScript object that can be used to access all HTML elements. Here are some ways one would call a motion component:

<motion.div />
<motion.span />
<motion.h1 />
<motion.svg />
...

As said before, they allow for extra props. Some of the most used are:

initial defines the initial state of an element.
style defines style properties just like normal React elements, but any change in the values through motion values (values that track the state and the velocity of the component) will be animated.
animate defines the animation on the component mount. If its values are different from style or initial, it will automatically animate these values. To disable mount animations initial has to be set to false.
exit defines the animation when the component unmounts. This works only when the component is a child of the <AnimatePresence /> component.
transition allows us to change animation properties. Here one can modify the duration, easing, type of animation (spring, tween, and inertia), duration, and many other properties.
variants allows orchestrating animations between components.

Now that we know the basic props that motion can contain and how to declare them, we can proceed to create a simple animation.

Mount Animations

Let's say we want to create an element that on mount will fade in down. We would use the initial and animate prop.

Inside the initial property, we'll be declaring where the component should be located before it mounts. We'll be adding an opacity: 0 and y: -50. This means the component initially will be hidden and will be 50 pixels up from its location.

In the animate prop, we have to declare how the component should look when it is mounted or shown to the user. We want it to be visible and located on its initial position, so we'll add an opacity: 1 and y: 0.

Framer Motion will automatically detect that the initial prop has a different value from the animate prop, and animate any difference in properties.

Our snippet will look like this:

import { motion } from "framer-motion";

<motion.div initial={{ opacity: 0, y: -50 }} animate={{ opacity: 1, y: 0 }}>
  Hello World!
</motion.div>;

This will create the following animation:

Congratulations on creating your first animation with Framer Motion!

💡 You may have noticed that styles are missing from the snippets above. Some of the snippets will lack the styles in order to focus on Framer Motion's functionality.

📕 All animations in this post will have their own Storybook. Here is the link of the latter.

Unmount Animations

Unmounting or exit animations are crucial when creating dynamic UIs, especially when deleting an item or handling page transitions.

To handle exit animations in Framer Motion, the first step is to wrap the element or elements in an <AnimatePresence/>. This has to be done because:

There is no lifecycle method that communicates when a component is going to be unmounted
There is no way to defer unmounting until an animation is complete.

AnimatePresence handles all this automatically for us.

Once the elements are wrapped, they must be given an exit prop specifying their new state. Just like animate detects a difference in values in initial, exit will detect the changes in animate and animate them accordingly.

Let's put this into practice! If we take the previous component and were to add an exit animation, we want it to exit with the same properties as it did in initial

import { motion } from "framer-motion";

<motion.div
  exit={{ opacity: 0, y: -50 }}
  initial={{ opacity: 0, y: -50 }}
  animate={{ opacity: 1, y: 0 }}
>
  Hello World!
</motion.div>;

Now, let's add a <AnimatePresence/> so it can detect when our component unmounts:

import { motion } from "framer-motion";

<AnimatePresence>
  <motion.div
    exit={{ opacity: 0, y: -50 }}
    initial={{ opacity: 0, y: -50 }}
    animate={{ opacity: 1, y: 0 }}
  >
    Hello World!
  </motion.div>
</AnimatePresence>;

Let's see what happens when the component unmounts:

📕 Storybook Link

Orchestration

One of Framer Motion's strong suits is its ability to orchestrate different elements through variants. Variants are target objects for simple, single-component animations. These can propagate animations through the DOM, and through this allow orchestration of elements.

Variants are passed into motion components through the variants prop. They normally will look like this:

const variants = {
  visible: { opacity: 0, y: -50 },
  hidden: { opacity: 1, y: 0 },
}

<motion.div initial="hidden" animate="visible" variants={variants} />

These will create the same animation as we did above. You may notice we passed to initial and animate a string. This is strictly used for variants. It tells what keys Framer Motion should look for inside the variants object. For the initial, it will look for 'hidden' and for animate 'visible'.

The benefit of using this syntax is that when the motion component has children, changes in the variant will flow down through the component hierarchy. It will continue to flow down until a child component has its own animate property.

Let's put this into practice! This time we will create a staggering list. Like this:

In the image, each item has an increasing delay between each entrance. The first one will enter in 0 seconds, the second in 0.1 seconds, the third in 0.2, and it will keep increasing by 0.1.

To achieve this through variants, first, let's create a variants object where we'll store all possible states and transition options:

const variants = {
  container: {},
  card: {},
};

variants.container and variants.card represent each motion component we'll have.

Let's create the animations for the cards. We see that the cards go from left to right while fading in. This means we have to update its x position and opacity.

As aforementioned, variants can have different keys for their animation states, however, we will leave it as initial and animate to indicate before mount and after mount, respectively.

On initial, our component will be 50 pixels to the left and its opacity will be 0.

On animate, our component will be 0 pixels to the left and its opacity will be 1.

Like this:

const variants = {
  container: {},
  card: {
    initial: {
      opacity: 0,
      x: -50,
    },

    animate: {
      opacity: 1,
      x: 0,
    },
  },
};

Next, we have to add the stagger effect to each of these cards. To achieve this we have to add the container.transition property which allows us to update the behavior of our animation. Inside the property, we'll add a staggerChildren property that defines an incremental delay between the animation of the children.

const variants = {
  container: {
    animate: {
      transition: {
        staggerChildren: 0.1,
      },
    },
  },
  card: {
    initial: {
      opacity: 0,
      x: -50,
    },

    animate: {
      opacity: 1,
      x: 0,
    },
  },
};

Now, if we hook this variant to the motion components:

import { motion } from "framer-motion";

const variants = {
  container: {
    animate: {
      transition: {
        staggerChildren: 0.1,
      },
    },
  },
  card: {
    initial: {
      opacity: 0,
      x: -50,
    },

    animate: {
      opacity: 1,
      x: 0,
    },
  },
};

const StaggeredList = () => {
  return (
    <motion.div
      initial="initial"
      animate="animate"
      variants={variants.container}
    >
      {new Array(5).fill("").map(() => {
        return <Card />;
      })}
    </motion.div>
  );
};

const Card = () => (
  <motion.div variants={variants.card}>Hello World!</motion.div>
);

With this, our animation is complete, and we have a sleek staggered list ready!

📕 Storybook Link

Dragging

Dragging is a feature that can be daunting to implement in an app. Thankfully, Framer Motion makes it a lot easier to implement its logic because of its declarative nature. In this post, I will give a simple, general introduction to it. However, in a future tutorial, I may explain in more detail how to create something more complex like a slide to delete.

Making an element draggable is extremely simple: add a drag prop to a motion component. Take for example the following:

import { motion } from "framer-motion";

<motion.div drag>Hello World!</motion.div>;

Adding the drag prop will make it draggable in the x-axis and y-axis. It should be noted that you can restrict the movement to a single axis by providing the desired axis to drag.

There is a problem with just setting the drag property. It is not bound to any area or container so it can move outside the screen like this:

To set constraints we give the dragContraints an object with our desired constraints for every direction: top, left, right, and bottom. Take for example:

import { motion } from "framer-motion";

<motion.div
  drag
  dragConstraints={{
    top: -50,
    left: -50,
    right: 50,
    bottom: 50,
  }}
>
  Hello World!
</motion.div>;

These constraints allow the element to move 50 pixels maximum in any direction. If we try to drag it, for example, 51 pixels to the top, it will be stopped and bounced. Like this:

It is as if there is an invisible wall in the form of a square that won't allow the component to move further.

📕 Storybook Link

Layout Property

The layout prop is a powerful feature in Framer Motion. It allows for components to animate automatically between layouts. It will detect changes to the style of an element and animate it. This has a myriad of use cases: reordering of lists, creating switches, and many more.

Let's use this immediately! We'll build a switch. First, let's create our initial markup

import { motion } from "framer-motion";

const Switch = () => {
  return (
    <div
      className={`flex w-24 p-1 bg-gray-400 bg-opacity-50 rounded-full cursor-pointer`}
      onClick={toggleSwitch}
    >
      {/* Switch knob */}
      <motion.div
        className="w-6 h-6 p-6 bg-white rounded-full shadow-md"
        layout
      ></motion.div>
    </div>
  );
};

Now, let's add our logic:

import { motion } from "framer-motion";

const Switch = () => {
  const [isOn, setIsOn] = React.useState(false);

  const toggleSwitch = () => setIsOn(!isOn);

  return (
    <div onClick={toggleSwitch}>
      {/* Switch knob */}
      <motion.div layout></motion.div>
    </div>
  );
};

You may have noticed that only our knob has the layout prop. This prop is required on only the elements that we wish to be animated.

We want the knob to move from one side to the other. We could achieve this by changing the container flex justification. When the switch is on, the layout will have justify-content: flex-end. Framer Motion will notice the knob's change of position and will animate its position accordingly.

Let's add this to our code:

import { motion } from "framer-motion";

const Switch = () => {
  const [isOn, setIsOn] = React.useState(false);

  const toggleSwitch = () => setIsOn(!isOn);

  return (
    <div
      style={{
        background: isOn ? "#48bb78" : "rgba(203, 213, 224, 0.5)",
        justifyContent: isOn && "flex-end",
        width: "6rem",
        padding: "0.25rem",
        display: "flex",
        borderRadius: 9999,
        cursor: "pointer",
      }}
      onClick={toggleSwitch}
    >
      {/* Switch knob */}
      <motion.div
        style={{
          width: "3rem",
          height: "3rem",
          background: "white",
          borderRadius: "100%",
          boxShadow:
            "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
        }}
        layout
      ></motion.div>
    </div>
  );
};

I added some other styles so it can resemble the look of a switch. Anyway, here is the result:

Great! It is amazing how Framer Motion can do this automatically without having to deal with extra controls. Anyhow, it looks a little bland compared to what we are used to seeing on apps like Settings. We can fix this pretty quickly by adding a transition prop.

import { motion } from "framer-motion";

const Switch = () => {
  const [isOn, setIsOn] = React.useState(false);

  const toggleSwitch = () => setIsOn(!isOn);

  return (
    <div
      style={{
        background: isOn ? "#48bb78" : "rgba(203, 213, 224, 0.5)",
        justifyContent: isOn && "flex-end",
        width: "6rem",
        padding: "0.25rem",
        display: "flex",
        borderRadius: 9999,
        cursor: "pointer",
      }}
      onClick={toggleSwitch}
    >
      {/* Switch knob */}
      <motion.div
        style={{
          width: "3rem",
          height: "3rem",
          background: "white",
          borderRadius: "100%",
          boxShadow:
            "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
        }}
        layout
        transition={{
          type: "spring",
          stiffness: 500,
          damping: 30,
        }}
      ></motion.div>
    </div>
  );
};

We define a spring-type animation because we want a bouncy feel.

The stiffness defines how sudden the movement of the knob will look.

And, damping defines the strength of the opposing force similar to friction. This means how fast it will stop moving.

These together create the following effect:

Now our switch looks more alive!

📕 Storybook Link

Conclusion

Creating animations can be daunting, especially when many libraries have complex jargon. Thankfully, Framer Motion allows developers to create seamless animations with its declarative and intuitive API.

This post was meant as an introduction to the fundamentals of Framer Motion. In future posts, I will create complex animations like swipe to expand and delete, drawers, shared layout, and many more. Please let me know in the comments if you have any suggestions as to what you want to see animated!

For more up-to-date web development content, follow me on Twitter, and Dev.to! Thanks for reading! 😎

Kick-Start Your Newsletter: Mailchimp Custom Form with React

Jose Felix — Sat, 15 Aug 2020 16:49:09 +0000

Recently, I had to create a subscription form for my blog/portfolio website. I decided to use Mailchimp because of its popularity and how highly efficient it is at handling subscribers. They have many form templates for getting started quickly. However, these templates handle the requests directly on the form's HTML instead of through a Front-End library like React. This is great for a simple website that does not require different states or interactions. Nonetheless, for my site, I wanted to use React to create a custom experience for my users. Through various attempts, I was able to find a testable and efficient way to handle these forms in React without sacrificing interactivity.

In this article, I will explain how we could implement a custom Mailchimp form with React using JSONP or a serverless function.

Serverless Functions or JSONP

You may be asking what you should choose between JSONP and serverless. My recommendation would be to go with serverless since it is more flexible, secure, and simpler to test. However, it requires you to set up a serverless provider like Amazon AWS, Vercel, Netlify, etc., which is not always possible in certain situations. On the other hand, JSONP is really easy to get started, and only React with some dependencies is needed.

In this post, I'm going to implement it first with JSONP, and then with serverless.

Getting Your Mailchimp's Generated Form URL

Before we can start, we need to get the URL for sending a subscription request. Since we are going to be doing both a JSONP and serverless, we will have to get the URL of the solution we need.

Getting JSONP URL

To get the URL, head to Signup Forms under Audience in your admin account dashboard.

Once there, select Embedded Forms.

Under Copy/paste onto your site, look for the URL inside the action attribute in the form. This is the URL we will be using.

That's it, nice job! Now, you can start creating your JSONP hook.

Creating a Hook For Subscribing Through JSONP

The reason why we are going to use JSON with Padding (JSONP) instead of fetch/Axios is that if we try to do a POST request to Mailchimp servers we will get a CORS error. This happens because by default the fetch/Axios API doesn't allow creating requests to different origins unless the response from the other domain includes the right CORS headers. Unfortunately, Mailchimp will never send the right CORS header for security reasons. JSONP is one interesting technique that allows us to make a GET request to servers of different origins. It basically allows us to bypass the CORS policy.

The first step for creating our hook is to install the jsonp package:

npm install jsonp
// or
yarn add jsonp

First, we declared a Status object which contains all of the possible states of our request, so we can determine the state in our form in a predictable way.

export const Status = {
    idle: 'IDLE',
    loading: 'LOADING',
    success: 'SUCCESS', 
    error: 'ERROR'
}

Second, we declare a toQueryString function which converts an object to a query string to be added as URL parameters.

/*

    Converts {foo: 'bar', key: 'bar2'} to 'foo=bar&key=bar2'

*/

function toQueryString(params) {
  return Object.keys(params)
    .map((key) => key + "=" + params[key])
    .join("&");
}

Third, inside our hook, we declare two React state variables, one for the error output and the other for the value received.

const [status, setStatus] = React.useState(Status.idle);
const [error, setError] = React.useState(null);
const [value, setValue] = React.useState(null);

Finally, we have a subscription method that will receive the data we need for the user to subscribe. This subscribe method first converts all our data into a query string and appends it to a new URL that replaces the post with post-json resource. Then we proceed to do the request while setting the status and error as needed.

const subscribe = React.useCallback((data) => {
    const params = toQueryString(data);
    const ajaxURL = url.replace("/post?", "/post-json?");
    const newUrl = ajaxURL + "&" + params;

    setError(null);
    setStatus(Status.loading);

    jsonp(newUrl, { param: "c" }, (err, data) => {
      if (err) {
        setStatus(Status.error);
        setError(err);
      } else if (data.result !== "success") {
        setStatus(Status.error);
        setError(data.msg);
      } else {
        setStatus(Status.success);
        setValue(data.msg);
      }
    });
  }, []);

Putting all this together:

export const Status = {
    idle: 'IDLE',
    loading: 'LOADING',
    success: 'SUCCESS', 
    error: 'ERROR'
}

function toQueryString(params) {
  return Object.keys(params)
    .map((key) => key + "=" + params[key])
    .join("&");
}

export function useMailChimp(url) {
  const [status, setStatus] = React.useState(Status.idle);
  const [error, setError] = React.useState(null);
  const [value, setValue] = React.useState(null);

  const subscribe = React.useCallback((data) => {
    const params = toQueryString(data);
    const ajaxURL = url.replace("/post?", "/post-json?");
    const newUrl = ajaxURL + "&" + params;

    setError(null);
    setStatus(Status.loading);

    jsonp(newUrl, { param: "c" }, (err, data) => {
      if (err) {
        setStatus(Status.error);
        setError(err);
      } else if (data.result !== "success") {
        setStatus(Status.error);
        setError(data.msg);
      } else {
        setStatus(Status.success);
        setValue(data.msg);
      }
    });
  }, []);

  return { subscribe, status, error, value };
}

That's it! Our hook is ready to be used in our app. Here is an example of how you could use it in your app.

import React from 'react'
import {useMailchimp, Status} from 'hooks'

const SubscribeForm = () => {
  const [form, setForm] = React.useState({firstName: '', email: ''})
  const {subscribe, status, error, value} = useMailchimp('YOUR_MAILCHIMP_URL')

  const handleInputChange = event => {
    const target = event.target
    const name = target.name
    const value = target.value

    setForm(form => ({
      ...form,
      [name]: value,
    }))
  }

  const handleSubmit = () => {
    // We are performing some simple validation here.
    // I highly recommend checking a fully-fledged solution
    // for forms like https://react-hook-form.com/
    if (form.firstName === '' || form.email === '') return

    subscribe({
      FNAME: form.firstName,
      EMAIL: form.email,
    })
  }

  if (status === Status.loading) {
    return <Loading />
  }

  if (status === Status.error) {
    return <Error error={error}/>
  }

  if (value.includes('Already subscribed')) {
    return <Success subscribed />
  }

  if (value) {
    return <Success />
  }

  return (
    <form>
      <label htmlFor="firstName">First Name</label>
      <input
        id="firstName"
        value={form.firstName}
        onChange={handleInputChange}
      />

      <label htmlFor="email">Email</label>
      <input id="email" value={form.email} onChange={handleInputChange} />

      <button onClick={handleSubmit}>Subscribe 📨</button>
    </form>
  )
}

Some of the main available names for your data keys are EMAIL, FNAME (first name), and LNAME (last name). You can find others on Mailchimp's website.

Getting the Serverless URL and API key

To get a URL available for a serverless integration we need two things:

The server where your Mailchimp account is located.
Your Audience List ID.

Mailchimp's API route is as follows:

https://SERVER.api.mailchimp.com/3.0/lists/LIST_ID/members

To get your server, you just have to check the subdomain you use to access your account.

For your Audience List ID, click Audience and then All contacts.

Click your desired audience. Click the Settings drop-down and choose Audience name and defaults.

In the Audience ID section, you’ll see a string of letters and numbers. This is your audience ID.

Once you have both of these, substitute them in the URL:

https://SERVER.api.mailchimp.com/3.0/lists/LIST_ID/members

For the API key please refer to Mailchimp's docs where there's a quick and beautiful tutorial.

Creating a Serverless Function for Subscribing Users

The serverless function integration depends on your provider. However, they will look very similar to each other. That said, I will be creating the function with Next.js API Routes.

I will ask for the same properties as I did for JSONP which are the user's first name and email. Therefore, I will have EMAIL and FNAME fields. For other available properties please refer to Mailchimp's website.

Our first step is to create the function:

import { NextApiRequest, NextApiResponse } from "next";

export default async (req, res) => {
 if (req.method === "POST") {
  } else {
    res.setHeader("Allow", ["POST"]);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
};

Then, let's add some validation with an amazingly simple validation library called ow. It will prevent faulty provided values in the request.

Let's add the package:

npm install ow
// or
yarn add ow

And in our function add some basic validation for our API key, email and first name:

import ow from "ow";
import { NextApiRequest, NextApiResponse } from "next";

function owWithMessage(val, message, validator) {
  try {
    ow(val, validator);
  } catch (error) {
    throw new Error(message);
  }
}

owWithMessage(
  process.env.MAILCHIMP_API_KEY,
  "MAILCHIMP_API_KEY environment variable is not set",
  ow.string.minLength(1)
);

const isEmail = ow.string.is((e) => /^.+@.+\..+$/.test(e));

export default async (req, res) => {
    try {
    console.log("> Validating input", " name: ", firstName, " email:", email);
    owWithMessage(firstName, "the name is too long", ow.string.maxLength(120));
    owWithMessage(
      email,
      "The email is invalid. Please enter a valid email address.",
      isEmail
    );
  } catch (e) {
    console.log("> Validation failed", e.message);
    res.status(403).json({ message: e.message });
  }

 if (req.method === "POST") {
  } else {
    res.setHeader("Allow", ["POST"]);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
};

To perform requests to Mailchimp's servers we need an API key. If you did not follow the instructions above, you can refer to Mailchimp's docs on how to get this key.

We will be declaring our authorization string with the generated API KEY which will be stored in an environment variable.

const authorization =
  "Basic " +
  Buffer.from("randomstring:" + process.env.MAILCHIMP_API_KEY).toString(
    "base64"
  );

Now, what's left is handling the request to Mailchimp's servers. I will be using the fetch API since Next.js now is able to use its server-side. For other providers, it is best to use libraries like node-fetch or Axios.

Mailchimp has an interesting way of handling subscribers. Once a user has been subscribed, he cannot use the subscribe endpoint again if he were to unsubscribe and would want to subscribe again. To solve this, one has to use a PATCH request method instead of a POST. Therefore, we have to verify the status of the contact before selecting a request method.

To check and update the status of a subscriber or member, Mailchimp requires it to be included in the URL as an MD5 hash. For this, we will be using a library called blueimp-md5.

Let's translate all this to code. We will have three mini services: checkContactStatus, addNewMember, and subscribeContact.

import md5 from "blueimp-md5";

function addNewMember(email: string, firstName: string) {
  return fetch("https://SERVER.api.mailchimp.com/3.0/lists/LIST_ID/members", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization,
    },
    body: JSON.stringify({
      email_address: email,
      status: "subscribed",
      merge_fields: {
        FNAME: firstName,
      },
    }),
  });
}

function subscribeContact(email: string) {
  return fetch(
    `https://SERVER.api.mailchimp.com/3.0/lists/LIST_ID/members/${md5(
      email.toLowerCase()
    )}`,
    {
      method: "PATCH",
      body: JSON.stringify({
        status: "subscribed",
      }),
      headers: {
        authorization,
      },
    }
  );
}

function checkContactStatus(email: string) {
  return fetch(
    `https://SERVER.api.mailchimp.com/3.0/lists/LIST_ID/members/${md5(
      email.toLowerCase()
    )}`,
    {
      headers: {
        authorization,
      },
    }
  );
}

Let's connect these services in our function:

if (req.method === "POST") {
    try {
      const { status } = await (await checkContactStatus(email)).json();

            // Add the contact if there is no member associated with the given email.
      if (status === 404) {
        const message = await (await addNewMember(email, firstName)).json();

                // Return a Not Acceptable code when Mailchimp detects 
                // a spam email or invalid property
        if (message.status === 400) {
          message.status = 406;
          return res.status(406).json({ message });
        }

        if (message) {
          return res.status(200).json({ message });
        }
      } else if (status === "subscribed") {
        res.status(400).json({ message: "User already subscribed" });
      } else {
                // Resubscribe the user
        const message = await (await subscribeContact(email)).json();
        if (message) {
          res.status(200).json({ message });
        }
      }
    } catch (err) {
      console.log(err);
      res.status(500).json({ message: err });
    }
  } else {
    res.setHeader("Allow", ["POST"]);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }

Now we can handle the edge cases of subscribing users. It is so much easier to test than using JSONP since we can stub the network calls.

Here is the complete function:

import { NextApiRequest, NextApiResponse } from "next";
import ow from "ow";
import md5 from "blueimp-md5";

function owWithMessage(val, message, validator) {
  try {
    ow(val, validator);
  } catch (error) {
    throw new Error(message);
  }
}

owWithMessage(
  process.env.MAILCHIMP_API_KEY,
  "MAILCHIMP_API_KEY environment variable is not set",
  ow.string.minLength(1)
);

const isEmail = ow.string.is((e) => /^.+@.+\..+$/.test(e));
const authorization =
  "Basic " +
  Buffer.from("randomstring:" + process.env.MAILCHIMP_API_KEY).toString(
    "base64"
  );

function addNewMember(email: string, firstName: string) {
  return fetch("https://SERVER.api.mailchimp.com/3.0/lists/LIST_ID/members", {
    method: "POST",
    headers: {
      "content-type": "application/json",
      authorization,
    },
    body: JSON.stringify({
      email_address: email,
      status: "subscribed",
      merge_fields: {
        FNAME: firstName,
      },
    }),
  });
}

function subscribeContact(email: string) {
  return fetch(
    `https://SERVER.api.mailchimp.com/3.0/lists/LIST_ID/members/${md5(
      email.toLowerCase()
    )}`,
    {
      method: "PATCH",
      body: JSON.stringify({
        status: "subscribed",
      }),
      headers: {
        authorization,
      },
    }
  );
}

function checkContactStatus(email: string) {
  return fetch(
    `https://SERVER.api.mailchimp.com/3.0/lists/LIST_ID/members/${md5(
      email.toLowerCase()
    )}`,
    {
      headers: {
        authorization,
      },
    }
  );
}
export default async (req: NextApiRequest, res: NextApiResponse) => {
  const { firstName, email } = req.body;

  try {
    console.log("> Validating input", " name: ", firstName, " email:", email);
    owWithMessage(firstName, "the name is too long", ow.string.maxLength(120));
    owWithMessage(
      email,
      "The email is invalid. Please enter a valid email address.",
      isEmail
    );
  } catch (e) {
    console.log("> Validation failed", e.message);
    res.status(403).json({ message: e.message });
  }

  if (req.method === "POST") {
    try {
      const { status } = await (await checkContactStatus(email)).json();

      if (status === 404) {
        const message = await (await addNewMember(email, firstName)).json();

        if (message.status === 400) {
          message.status = 406;
          return res.status(406).json({ message });
        }

        if (message) {
          return res.status(200).json({ message });
        }
      } else if (status === "subscribed") {
        res.status(400).json({ message: "User already subscribed" });
      } else {
        const message = await (await subscribeContact(email)).json();
        if (message) {
          res.status(200).json({ message });
        }
      }
    } catch (err) {
      console.log(err);
      res.status(500).json({ message: err });
    }
  } else {
    res.setHeader("Allow", ["POST"]);
    res.status(405).end(`Method ${req.method} Not Allowed`);
  }
};

That's it! In our components, we can request our function and act accordingly to the result. For reference, here are the possible subscription states according to their HTTP status codes:

200 - Successfully added subscriber or resubscribed.
400 - User is already subscribed.
403 - User has sent invalid credentials to the function.
406 - User has sent a spam email or credentials that are invalid on Mailchimp.
500 - Function has encountered an unexpected error.

Here is a quick example:

import React from "react";
import axios from "axios";

export const Status = {
  idle: "IDLE",
  loading: "LOADING",
  success: "SUCCESS",
  error: "ERROR",
};

async function subscribe({ firstName, email }) {
  const response = await axios.post("/api/subscribe", {
    firstName,
    email,
  });
  return response;
}

const SubscribeForm = () => {
  const [form, setForm] = React.useState({ firstName: "", email: "" });
  const [subscribeState, setSubscribeState] = React.useState({
    status: Status.idle,
    value: "",
    error: null,
  });

  const handleInputChange = (event) => {
    const target = event.target;
    const name = target.name;
    const value = target.value;

    setForm((form) => ({
      ...form,
      [name]: value,
    }));
  };

  const handleSubmit = () => {
    // We are performing some simple validation here.
    // I highly recommend checking a fully-fledged solution
    // for forms like https://react-hook-form.com/
    if (form.firstName === "" || form.email === "") return;

    subscribe({ firstName: "", email: "" }).then((res) => {
      switch (res.status) {
        case 200:
          setSubscribeState({
            status: Status.success,
            value: res.data,
            error: null,
          });
          break;
        case 400:
          setSubscribeState({
            status: Status.success,
            value: "Already Subscribed",
            error: null,
          });
          break;
        case 403:
        case 406:
        case 500:
          setSubscribeState({
            status: Status.error,
            value: "",
            error: res.data,
          });
          break;
      }
    });
  };

  if (subscribeState.status === Status.loading) {
    return <Loading />;
  }

  if (subscribeState.status === Status.error) {
    return <Error error={error} statusCode={subscribeState.status} />;
  }

  if (subscribeState.value.includes("Already subscribed")) {
    return <Success subscribed />;
  }

  if (subscribeState.value) {
    return <Success />;
  }

  return (
    <form>
      <label htmlFor="firstName">First Name</label>
      <input
        id="firstName"
        value={form.firstName}
        onChange={handleInputChange}
      />

      <label htmlFor="email">Email</label>
      <input id="email" value={form.email} onChange={handleInputChange} />

      <button onClick={handleSubmit}>Subscribe 📨</button>
    </form>
  );
};

Conclusion

Mailchimp is very popular and amazing to manage your subscribers or audience. Creating a custom form in a Front-End library like React can be daunting, especially since a normal server request to Mailchimp's servers using fetch or Axios won't work. With JSONP or a serverless function, one can create an amazing experience not bound to template forms.

Choosing between JSONP and a serverless function depends on how robust the implementation has to be. JSONP is best for a quick solution that requires minimal code and no serverless providers. On the other hand, a serverless function allows for a testable, robust, and safer solution.

For more up-to-date web development content, follow me on Twitter, and Dev.to! Thanks for reading! 😎

Make Text Match Any Background Color

Jose Felix — Sun, 26 Jul 2020 20:21:02 +0000

Have you ever needed to use text inside a card that has generated colors? Or give the user the capacity to choose their own color for a component that contains text like a navbar? These are situations where texts need to adapt to the current background color. Making each color match the text would be tedious and unscalable. By using the luminance and contrast ratio, we can determine if the text should be dark or bright while guaranteeing an accessible contrast.

Contrast Ratio

The goal of text with a background is that it can be easily read by the users, including those with moderately low vision. To understand when a text is legible or not, first, we have to understand what contrast ratio is. Contrast ratio is a property that is defined by the luminance (amount of light) of the brightest color (white) to that of the darkest color (black) that a system is capable of producing. According to the W3C, the formula is (L1 + 0.05) / (L2 + 0.05), where

L1 is the relative luminance of the lighter of the colors, and
L2 is the relative luminance of the darker of the colors.

The luminance scale can go from 0.0-1.0. Black is 0.0 and white is 1.0. You may notice that if we calculate the ratio with the extremes of the scale's interval (1.0 + 0.05) / (0.0 + 0.05) we would get 21, and if both are 0.0 then we get 1. This means that the ratios will range from 1 to 21. These are commonly written as 1:1 to 21:1.

The recommended contrast ratio between a text and a background should be at least 4.5:1.

Determining Text Color Dynamically

Now that we know what contrast ratio we should aspire to, it is time to find a formula so that we can determine which color to use.

According to Mark Ransom, to determine if we need a darker or brighter color, we just need to compare the contrast of the background color with white and black. If the contrast for black is higher, then we use black, otherwise, we use white. We can represent this in JavaScript in the following way:

if ((L + 0.05) / (0.0 + 0.05) > (1.0 + 0.05) / (L + 0.05)){
    use #000000
} else {
  use #ffffff
}

If we simplify it:

if (L > Math.sqrt(1.05 * 0.05) - 0.05){
    use #000000
} else {
  use #ffffff
}

Now, all that is left is calculating the luminance!

Calculating the Luminance

Getting the luminance is pretty straightforward if you have an RGB color. According to the W3C, the formula for luminance is L = 0.2126 * R + 0.7152 * G + 0.0722 * B where R, G and B are defined as:

if RsRGB <= 0.03928
then R = RsRGB/12.92
else R = ((RsRGB+0.055)/1.055) ^ 2.4
if GsRGB <= 0.03928
then G = GsRGB/12.92
else G = ((GsRGB+0.055)/1.055) ^ 2.4
if BsRGB <= 0.03928
then B = BsRGB/12.92
else B = ((BsRGB+0.055)/1.055) ^ 2.4

In JavaScript this would translate to:

/*
    If color has the following format: 
    const rgbColor = {
        r: 100,
        g: 100, 
        b: 100
    }
*/

// Extracted from Polished
// Code is licensed with an MIT license
function getLuminance(rgbColor) {
  const [r, g, b] = Object.keys(rgbColor).map((key) => {
    // Our color numbers represent an 8-bit channel.
    // The formula requires a sRGB channel which is defined by
    // ColorChannelIn8bit / 255
    const channel = rgbColor[key] / 255;
    return channel <= 0.03928
      ? channel / 12.92
      : ((channel + 0.055) / 1.055) ** 2.4;
  });
  return parseFloat((0.2126 * r + 0.7152 * g + 0.0722 * b).toFixed(3));
}

Frequently, we don't have our colors in RGB, but in hex or color name. That is why I recommend checking out polished library which exposes a getLuminance function that returns the luminance given a hex or color name.

Bringing It All Together

Now that we know how to determine the color's value using its luminance and comparing contrast ratios, we are ready to apply it to an app. For the sake of this post, I will display how to do this with a quick possible scenario. We have a card in which the user can change the background color with a color picker. Our job is to select a text color that is accessible and visible to all our users.

Here is a sandbox with the finished product. Feel free to tinker with it!

Conclusion

Adjusting the text color to match a background is very common when developing dynamic UIs. A contrast ratio of 4.5:1 is essential to guarantee an accessible contrast between a text and a background. By comparing the contrast ratios of both white and black using the background color's luminance, it is possible to efficiently determine the text color used with a background.

For more up-to-date web development content, follow me on Twitter, and Dev.to! Thanks for reading! 😎

References

Using React Spring to Animate SVG Icons: Dark Mode Toggle

Jose Felix — Wed, 15 Jul 2020 22:41:49 +0000

Don't want to code along? See this button as a package on GitHub.

Creating amazing user experiences for users on a website is the main objective of a web developer. Sometimes we see amazing animations that bring the website to life. In this instance, I want to focus on a dark and light mode toggle, specifically a sun and moon transition. Here are some examples of what we will be inspired by:

We will be building this with SVGs and React Spring. In short, what makes this method possible is the use of an SVG mask. It allows us to hide two icons in one, and change their properties with animation using React Spring. This will guarantee a fluid spring-physics transition and be able to use JavaScript to display whichever icon we need.

I assume you have created a React project. If not, please do so with something like Create React App.

Getting the Icons

We'll use the following sun and moon icons from Feather Icons:

These icons are licensed under the open-source MIT License.

Here are the SVG codes for only the sun since we will be creating the moon icon through a mask!

<svg
  xmlns="http://www.w3.org/2000/svg"
  width="24"
  height="24"
  viewBox="0 0 24 24"
  fill="none"
  stroke="currentColor"
  stroke-width="2"
  stroke-linecap="round"
  stroke-linejoin="round"
>
  <circle cx="12" cy="12" r="5" />
  <line x1="12" y1="1" x2="12" y2="3" />
  <line x1="12" y1="21" x2="12" y2="23" />
  <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
  <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
  <line x1="1" y1="12" x2="3" y2="12" />
  <line x1="21" y1="12" x2="23" y2="12" />
  <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
  <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
</svg>

Meshing Both Icons Into One

In order to create the moon, we have to understand what is an SVG mask. It is an element that defines an alpha mask for compositing the current object into the background. In other words, SVG masks allow us to define areas in the background that are transparent or not using SVG elements. In CSS we determine the opacity of the mask (how much of the element is shown) by using colors. The closer the color is to black the less opacity it will have and the closer to white the more opacity.

We will be using a circle shape inside the mask to hide a portion of the sun's circle so it will create the curve of the moon.

Something like this:

First, we will fill the circle since it will make it easier to create our mask:

<svg
  xmlns="http://www.w3.org/2000/svg"
  width="24"
  height="24"
  viewBox="0 0 24 24"
  fill="none"
  stroke="currentColor"
  stroke-width="2"
  stroke-linecap="round"
  stroke-linejoin="round"
>
  <circle fill="black" cx="12" cy="12" r="5" />
  <line x1="12" y1="1" x2="12" y2="3" />
  <line x1="12" y1="21" x2="12" y2="23" />
  <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
  <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
  <line x1="1" y1="12" x2="3" y2="12" />
  <line x1="21" y1="12" x2="23" y2="12" />
  <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
  <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" /></svg
>;

Then, wrap our lines in a <g/> which is basically the div for SVG elements:

<svg
  xmlns="http://www.w3.org/2000/svg"
  width="24"
  height="24"
  viewBox="0 0 24 24"
  fill="none"
  stroke="currentColor"
  stroke-width="2"
  stroke-linecap="round"
  stroke-linejoin="round"
>
  <circle fill="black" cx="12" cy="12" r="5" />
  <g stroke="currentColor">
    <line x1="12" y1="1" x2="12" y2="3" />
    <line x1="12" y1="21" x2="12" y2="23" />
    <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
    <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
    <line x1="1" y1="12" x2="3" y2="12" />
    <line x1="21" y1="12" x2="23" y2="12" />
    <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
    <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
  </g>
</svg>

We will have something like this:

Now, we will create our mask. To declare a mask in SVG, we create a <mask/>, give it an id, and reference it in the element to be masked, in this case, the <circle/>.

<svg
  xmlns="http://www.w3.org/2000/svg"
  width="24"
  height="24"
  viewBox="0 0 24 24"
  fill="none"
  stroke="currentColor"
  stroke-width="2"
  stroke-linecap="round"
  stroke-linejoin="round"
>
  <mask id="mask"></mask>
  <circle fill="black" cx="12" cy="12" r="5" mask="url(#mask)" />
  <g stroke="currentColor">
    <line x1="12" y1="1" x2="12" y2="3" />
    <line x1="12" y1="21" x2="12" y2="23" />
    <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
    <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
    <line x1="1" y1="12" x2="3" y2="12" />
    <line x1="21" y1="12" x2="23" y2="12" />
    <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
    <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
  </g>
</svg>

With this change, we won't be able to see our icon temporarily because the mask is assuming everything must be transparent. Therefore, let's start by creating a pseudo-canvas that will show the whole icon. To achieve this, inside the mask we will create a <rect/> (rectangle) that will have the same height and width of the SVG, and filled with white that will show everything (remember anything closer to white has higher opacity and vice versa).

<svg
  xmlns="http://www.w3.org/2000/svg"
  width="24"
  height="24"
  viewBox="0 0 24 24"
  fill="none"
  stroke="currentColor"
  stroke-width="2"
  stroke-linecap="round"
  stroke-linejoin="round"
>
  <mask id="mask">
    <rect x="0" y="0" width="100%" height="100%" fill="white" />
        
  </mask>
  <circle fill="black" cx="12" cy="12" r="5" mask="url(#mask)" />
  <g stroke="currentColor">
    <line x1="12" y1="1" x2="12" y2="3" />
    <line x1="12" y1="21" x2="12" y2="23" />
    <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
    <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
    <line x1="1" y1="12" x2="3" y2="12" />
    <line x1="21" y1="12" x2="23" y2="12" />
    <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
    <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
  </g>
</svg>

Now that we are showing our icon through our mask, we have to draw a circle with a black fill which will hide the portion of our circle and display the moon. Before doing this, we will do two things: increase the radius of the circle since the sun has a lower radius than the moon, and hide the rays temporarily

<svg
  xmlns="http://www.w3.org/2000/svg"
  width="24"
  height="24"
  viewBox="0 0 24 24"
  fill="none"
  stroke="currentColor"
  stroke-width="2"
  stroke-linecap="round"
  stroke-linejoin="round"
>
  <mask id="mask">
    <rect x="0" y="0" width="100%" height="100%" fill="white" />     
  </mask>
  <circle fill="black" cx="12" cy="12" r="9" mask="url(#mask)" />
  {/* <g stroke="currentColor">
        <line x1="12" y1="1" x2="12" y2="3" />
        <line x1="12" y1="21" x2="12" y2="23" />
        <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
        <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
        <line x1="1" y1="12" x2="3" y2="12" />
        <line x1="21" y1="12" x2="23" y2="12" />
        <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
        <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
      </g> */}
</svg>

Finally, let's add a circle inside our mask. The circle will be located at the same x of the center but will be at the top to hide only a fraction of our center circle. Also, we will rotate the SVG using a style attribute to show the moon in its right position.

<svg
  xmlns="http://www.w3.org/2000/svg"
  width="24"
  height="24"
  viewBox="0 0 24 24"
  fill="none"
  stroke="currentColor"
  stroke-width="2"
  stroke-linecap="round"
  stroke-linejoin="round"
  style={{ transform: "rotate(40deg)" }}
>
  <mask id="mask">
    <rect x="0" y="0" width="100%" height="100%" fill="white" />
    <circle cx="12" cy="4" r="9" fill="black" />
        
  </mask>
  <circle fill="black" cx="12" cy="12" r="9" mask="url(#mask)" />
  {/* <g stroke="currentColor">
        <line x1="12" y1="1" x2="12" y2="3" />
        <line x1="12" y1="21" x2="12" y2="23" />
        <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
        <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
        <line x1="1" y1="12" x2="3" y2="12" />
        <line x1="21" y1="12" x2="23" y2="12" />
        <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
        <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
      </g> */}
</svg>

With this, our moon is ready!

Animating the Icons

To change from moon to sun we have to follow the next steps:

Reduce the radius of the center circle.
Hide the mask's circle.
Show the rays.
Rotate the SVG to its original position.

We could achieve this with normal React state or CSS animations, but that will not create smooth spring-based animations that create the feeling we want. Therefore, we will be using React Spring. Let's install it:

yarn add react-spring

Once added, let's proceed to create an object that will house the two state properties: one for the sun and the other for the moon:

const properties = {
  sun: {
    r: 9,
    transform: "rotate(40deg)",
    cx: 12,
    cy: 4,
    opacity: 0,
  },
  moon: {
    r: 5,
    transform: "rotate(90deg)",
    cx: 30,
    cy: 0,
    opacity: 1,
  },
};

You may have noticed that in the sun we are rotating it to 40° instead of 0°. I did this to make the animation go from bottom to top which looks better in my opinion.

First, let's give the component a state. I will name it isDarkMode since my main purpose is to use these icons for dark mode. Then, create a toggle function to change states and add the cursor: "pointer" property in styles.

const AnimatedIcon = () => {
  const [isDarkMode, setDarkMode] = React.useState(false);

  const toggleDarkMode = () => {
    setDarkMode((previous) => !previous);
  };

  return (
    <svg
      xmlns="http://www.w3.org/2000/svg"
      width="24"
      height="24"
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      stroke-width="2"
      stroke-linecap="round"
      stroke-linejoin="round"
      style={{ transform: "rotate(40deg)", cursor: "pointer" }}
      onClick={toggleDarkMode}
    >
      <mask id="mask">
        <rect x="0" y="0" width="100%" height="100%" fill="white" />
        <circle cx="12" cy="4" r="9" fill="black" />
            
      </mask>
      <circle fill="black" cx="12" cy="12" r="9" mask="url(#mask)" />
      {/* <g stroke="currentColor">
        <line x1="12" y1="1" x2="12" y2="3" />
        <line x1="12" y1="21" x2="12" y2="23" />
        <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
        <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
        <line x1="1" y1="12" x2="3" y2="12" />
        <line x1="21" y1="12" x2="23" y2="12" />
        <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
        <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
      </g> */}
    </svg>
  );
};

Second, let's declare our springs. A spring is a way to move data from point a to b with animation, simulating the smoothness of a real spring. We can declare one using the hook useSpring. Furthermore, we will use our current state to handle changing between the properties in our object.

// ...

const { r, transform, cx, cy, opacity } =
  properties[isDarkMode ? "dark" : "light"];

const svgContainerProps = useSpring({ transform });
const centerCircleProps = useSpring({ r });
const maskedCircleProps = useSpring({ cx, cy });
const linesProps = useSpring({ opacity });

// ...

These hooks will return props that, by giving it to an animate.HTMLElement, it will render the values with animation. It can represent any HTML tag; for example, animated.svg, animated.div, etc. Knowing this, let's hook it up with our icon's elements:

// ...
return (
  <animated.svg
    xmlns="http://www.w3.org/2000/svg"
    width="24"
    height="24"
    viewBox="0 0 24 24"
    fill="none"
    strokeWidth="2"
    strokeLinecap="round"
    strokeLinejoin="round"
    stroke="currentColor"
    onClick={toggleDarkMode}
    style={{
      cursor: "pointer",
      ...svgContainerProps,
    }}
  >
    <mask id="myMask2">
      <rect x="0" y="0" width="100%" height="100%" fill="white" />
      <animated.circle style={maskedCircleProps} r="9" fill="black" />
    </mask>

    <animated.circle
      cx="12"
      cy="12"
      style={centerCircleProps}
      fill="black"
      mask="url(#myMask2)"
    />
    <animated.g stroke="currentColor" style={linesProps}>
      <line x1="12" y1="1" x2="12" y2="3" />
      <line x1="12" y1="21" x2="12" y2="23" />
      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64" />
      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78" />
      <line x1="1" y1="12" x2="3" y2="12" />
      <line x1="21" y1="12" x2="23" y2="12" />
      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36" />
      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22" />
    </animated.g>
  </animated.svg>
);

As a bonus, let's add some spring configuration to make our animations smoother and cooler!

const properties = {
  dark: {
    r: 9,
    transform: "rotate(40deg)",
    cx: 12,
    cy: 4,
    opacity: 0,
  },
  light: {
    r: 5,
    transform: "rotate(90deg)",
    cx: 30,
    cy: 0,
    opacity: 1,
  },
  springConfig: { mass: 4, tension: 250, friction: 35 },
};
// ...

const svgContainerProps = useSpring({
  transform,
  config: properties.springConfig,
});
const centerCircleProps = useSpring({ r, config: properties.springConfig });
const maskedCircleProps = useSpring({
  cx,
  cy,
  config: properties.springConfig,
});
const linesProps = useSpring({ opacity, config: properties.springConfig });

// ...

That's it, now we have our sleekly animated icon! Feel free to modify it however you would like.

Conclusion

Creating amazing user experiences on websites depends greatly on micro-interactions. An example of where these can be implemented is by animating icons that represent an action. Learning about SVGs, masks, and an animation library like React Spring, we could create an amazingly smooth dark and light mode toggle. Hopefully, this opens the possibility of creating other animated icons which will guarantee awesome and performant interactions, bringing a website to life.

For more up-to-date web development content, follow me on Twitter, and Dev.to! Thanks for reading! 😎

How to Change Between Light and Dark Themes in Ant Design

Jose Felix — Mon, 29 Jun 2020 20:53:55 +0000

Don't want to code along? Check out the GitHub repository of this post with a full example!

Ant Design is a great UI library for bootstrapping an application quickly. I love it a lot and have been using it to create my student dashboard. However, there is a big disadvantage: lack of dynamic theming. When I faced the need to implement a dark mode for my dashboard, I noticed AntD didn't have a provider for styles; instead, it utilizes Less Stylesheets. This means that in order to modify the variables dynamically you would have to recompile the styles and at runtime, this is not feasible. In this post, I'll explore how I solved this conundrum.

Note: This tutorial will only work with static themes: themes that are just meant to be compiled once at build time. If you want to change, for example, the primary color to any color at runtime then you will have to use a library like react-app-rewire-antd-theme.

The Problem

Less stylesheets are really good for supercharging CSS and handle ever-increasing styles. However, the way React handles this is by using Webpack to compile the styles to CSS and then add them to the build. This means you can't modify its variables or properties as you would do through Less.js.

To fix the lack of modification there are libraries like react-app-rewire-antd-theme. This injects the less file with the colors to modify directly in HTML and uses window.modifyVars to recompile the styles with the new variables at runtime. This may work with a small number of variables, however, for hundreds of variables for a dark theme, it is just not feasible. It kills the performance of the client.

The Solution

I tried many approaches to solving this issue, from modifying CSS directly to react-app-rewire-antd-theme, and arrived at a solution that is production-ready: swapping between pre-fetched Less-compiled CSS stylesheets at runtime using react-css-theme-switch.

Getting AntD Stylesheets

The first thing we have to do is create the Less stylesheets that will contain AntD styles. To achieve this, we just have to import the variables and styles that we need for each theme. For example, for the light theme:

// light-theme.less

@import '~antd/lib/style/color/colorPalette.less';
@import '~antd/dist/antd.less';
@import '~antd/lib/style/themes/default.less';

// These are shared variables that can be extracted to their own file
@primary-color: #00adb5;
@border-radius-base: 4px;

For the dark theme:

// dark-theme.less

@import '~antd/lib/style/color/colorPalette.less';
@import '~antd/dist/antd.less';
@import '~antd/lib/style/themes/dark.less';

@primary-color: #00adb5;
@border-radius-base: 4px;

@component-background: #303030;
@body-background: #303030;
@popover-background: #303030;
@border-color-base: #6f6c6c;
@border-color-split: #424242;
@table-header-sort-active-bg: #424242;
@card-skeleton-bg: #424242;
@skeleton-color: #424242;
@table-header-sort-active-bg: #424242;

Compiling Less Files With Gulp

In this step, we have to achieve two main objectives: compile Less files to CSS and then append these to the public or static folder so they can be available for the client to be pre-fetched and injected.

There are several ways to compile Less stylesheets: using a task runner, a module bundler, or scripts. Using Webpack would mean creating a plugin and with every change, the styles would have to compile which will slow down development speed for styles that will remain relatively static. Using scripts can result in extensive and unreadable code. Therefore, I decided to go with the Gulp task runner since it applies a pipeline paradigm with files that maintain code simple and maintainable. Also, it has great support for minifying and compiling Less.

Install Gulp and necessary dependencies to minify, use postcss and resolve imports:

yarn add -D gulp gulp-less gulp-postcss gulp-debug gulp-csso autoprefixer less-plugin-npm-import

And create a gulpfile.js:

const gulp = require('gulp')
const gulpless = require('gulp-less')
const postcss = require('gulp-postcss')
const debug = require('gulp-debug')
var csso = require('gulp-csso')
const autoprefixer = require('autoprefixer')
const NpmImportPlugin = require('less-plugin-npm-import')

gulp.task('less', function () {
  const plugins = [autoprefixer()]

  return gulp
    .src('src/themes/*-theme.less')
    .pipe(debug({title: 'Less files:'}))
    .pipe(
      gulpless({
        javascriptEnabled: true,
        plugins: [new NpmImportPlugin({prefix: '~'})],
      }),
    )
    .pipe(postcss(plugins))
    .pipe(
      csso({
        debug: true,
      }),
    )
    .pipe(gulp.dest('./public'))
})

Finally, run npx gulp less, and all styles will automatically be compiled and appended to the public folder.

Changing Between Themes

Now that we have our themes inside the public folder, we can proceed to use them in our app.

First, let's add react-css-theme-switch:

yarn add react-css-theme-switcher

Then, in our index.js or where we are keeping our providers, we wrap the element with the ThemeSwitcherProvider. This will store our themes and current theme. Also, it allows the use of useThemeSwitcher, which changes themes and fetches other metadata:

// index.js
import React from "react";

import ReactDOM from "react-dom";

import "./index.css";
import App from "./App";
import { ThemeSwitcherProvider } from "react-css-theme-switcher";

const themes = {
  dark: `${process.env.PUBLIC_URL}/dark-theme.css`,
  light: `${process.env.PUBLIC_URL}/light-theme.css`,
};

ReactDOM.render(
  <React.StrictMode>
    <ThemeSwitcherProvider themeMap={themes} defaultTheme="light">
      <App />
    </ThemeSwitcherProvider>
  </React.StrictMode>,
  document.getElementById("root")
);

Now, we can use it like this:

import React from "react";
import "./App.css";
import { useThemeSwitcher } from "react-css-theme-switcher";
import { Switch, Input } from "antd";

export default function App() {
  const [isDarkMode, setIsDarkMode] = React.useState();
  const { switcher, currentTheme, status, themes } = useThemeSwitcher();

  const toggleTheme = (isChecked) => {
    setIsDarkMode(isChecked);
    switcher({ theme: isChecked ? themes.dark : themes.light });
  };

  // Avoid theme change flicker
  if (status === "loading") {
    return null;
  }

  return (
    <div className="main fade-in">
      <h1>The current theme is: {currentTheme}</h1>
      <Switch checked={isDarkMode} onChange={toggleTheme} />

      <Input
        style={{ width: 300, marginTop: 30 }}
        placeholder="I will change with the theme!"
      />
    </div>
  );
}

Inside our playground, we will be able to change smoothly between themes!

CSS Injection Order

You may notice our styles are being appended to the head at runtime which means that those that were added at build time will be possibly overridden.

On this screenshot, you may observe that the style tags which are build-time CSS declarations are located before those pre-fetched. To avoid overriding our styles, we can mark an insertion point in our HTML which will allow it to be injected at that location, avoiding collisions. Thankfully, we don't have to implement it ourselves since react-css-theme-switcher comes with a built-in solution.

To begin, add in your HTML a comment where you want the styles to be injected. Also, the text content of this will be the identifier we will pass to the ThemeSwitcherProvider.

// index.html

<!DOCTYPE html>
<html lang="en">
    <head>    
            ...
        <title>React App</title>
        <!--styles-insertion-point-->
    </head>
    <body>
    ...
    </body>
</html>

Finally, on the provider:

// index.js

ReactDOM.render(
  <React.StrictMode>
    <ThemeSwitcherProvider
      themeMap={themes}
      defaultTheme="light"
      insertionPoint="styles-insertion-point"
    >
      <App />
    </ThemeSwitcherProvider>
  </React.StrictMode>,
  document.getElementById("root")
);

With this, we are done! If you check your developer tools:

Our styles will be injected where we want them to. Now, it won't conflict with our styles!

Note: Watch out for HTML comment trim in production. Make sure your project works well in production and in development.

Conclusion

AntD is an amazing UI library which can help to create projects quickly and with a beautiful user interface. However, it has a major weakness: its styles are not easily configurable since they use Less stylesheets. Using Gulp to compile and extract AntD CSS and react-css-theme-switcher to inject and change between them, this issue could be solved in a performant way. In the future, it would be good to explore how to optimize these generated stylesheets by extracting duplicate styles and reducing fetched CSS size.

I hope you found this article useful. For more up-to-date web development content, follow me on Twitter, and Dev.to! Thanks for reading! 😎

Test Your Email Flow with Mailhog, a Fake SMTP Server

Jose Felix — Thu, 18 Jun 2020 21:02:57 +0000

Don't want to code along? Here is the GitHub repository for what we are building on this post!

Most apps sooner or later will have to deal with sending emails to the user, that being after registration or a specific event. After sending the email, a developer most likely would want to test how the user would receive it or if there is a link, how it reacts within the app. Using a real SMTP server for this can be tricky and could end up spamming a user with emails without needing to. That is why a fake SMTP server can be useful as it can allow you to send emails to a safe box that will trap all these emails and can be fetched if you need to use them to test your flow or content. There are many SaaS (Software as a Service) that can set up this server for you, however, they can be costly and limiting. That is why in this post, I'll be teaching you how to use Mailhog with Docker to create a fake email server and be able to fetch emails so you can use it on your tests.

Creating an Express Server

In this tutorial, I'll use an Express server with Nodemailer since it is my main toolset. Regardless, this method will work for any stack that can use SMTP as a client. First, start a node environment by running:

npm init -y

Then, install the required dependencies:

npm install --save express nodemailer

Next, create a server.js which will start our server:

const express = require("express");
const app = express();
const port = 3000;

app.get("/", (req, res) => res.send("Hello World!"));

app.listen(port, () =>
  console.log(`Example app listening at http://localhost:${port}`),
);

Add a start script in package.json to start our server:

{
  "scripts": {
    "start": "node server.js",
    "test": "echo \"Error: no test specified\" && exit 1"
  },
}

Finally, start the server with:

npm run start

Setting up Docker

Setting up Mailhog is as easy as using your OS install command. However, if you are sharing your repository with other developers it would be nice to use Docker so that it can work as expected on other machines or in CI (Continuous Integration). Also, the developer is able to clean the history as needed by just removing the container.

If you don't have Docker installed, please refer to their site and follow their instructions on how to install it for your OS.

Note: If you are using Linux, please install Docker Compose on their docs page

Once you have installed Docker, create a Dockerfile. This will fetch a Node.js image and start our server.

FROM node:10

# Create app directory
WORKDIR /usr/src/app

# Install app dependencies
# A wildcard is used to ensure both package.json AND package-lock.json are copied
# where available (npm@5+)
COPY package*.json ./

RUN npm install

# Bundle app source
COPY . .

CMD [ "node", "server.js" ]

Also, create a .dockerignore:

node_modules
npm-debug.log

Create a docker-compose.yaml which will start up our just created Dockerfile and also Mailhog.

version: '2.4'

services:
  node:
    build:
      context: .
      dockerfile: Dockerfile
    ports:
      - '3000:3000'

  mailhog:
    image: mailhog/mailhog:latest
    restart: always
    ports:
      - 1025:1025
      - 8025:8025

Finally, run:

docker-compose up --build

And you will see that our images will be built and our servers will start automatically!

Receiving Emails

To receive emails we just have to send them as we would for a normal SMTP. Go to server.js and add the following :

const express = require("express");
const nodemailer = require("nodemailer");
const app = express();
const port = 3000;

const transporter = nodemailer.createTransport({
  host: "mailhog",
  port: 1025,
});

app.get("/send_email/:email", (req, res) => {
  const { email } = req.params;

  const messageStatus = transporter.sendMail({
    from: "My Company <company@companydomain.org>",
    to: email,
    subject: "Hi Mailhog!",
    text: "This is the email content",
  });

  if (!messageStatus) res.json("Error sending message!").status(500);

  res.json("Sent!").status(200);
});

// ...

Here we create a Nodemailer transport with Mailhog's default credentials. Also, a GET route that receives an email parameter to where we want to 'send' it. Now if you head in your browser and type http://localhost:3000/send_email/test@test.com you will see a 'sent!' JSON response. If you head towards Mailhog's dashboard on [localhost:8025](http://localhost:8025), the email we just sent will be visible and you can open it to see any details such as headers, and text content.

Query Mailhog

Querying Mailhog is as easy as doing it for a REST server. To find all the possible routes to query, you can find their Swagger JSON and YAML on their GitHub. To get all the emails from a specific email we use the following GET route http://localhost:8025/api/v2/search. Since we sent a message to test@test.com our query will be http://localhost:8025/api/v2/search?kind=to&query=test@test.com. If you paste this in your browser you'll see the email we just sent!

Awesome! Now you can use this information for testing using Cypress or Jest.

Conclusion

Testing email flows is very important to guarantee a stellar experience for users, especially since these flows can sometimes be fundamental for general functionality like a sign-up confirmation. Using our real SMTP server can result in sending a user an email by mistake. Also, setting up a fake SMTP server using a SaaS provider like Mailtrap can be expensive. Instead, we can use Mailhog and Docker to create this server quickly that allows us to query for sent emails so we can use them in our tests without dealing with quota or price plans.

I hope you found this article useful. For more up-to-date web development content, follow me on Twitter, and Dev.to! Thanks for reading! 😎

40+ High-Quality Free Resources for Web Development

Jose Felix — Sun, 07 Jun 2020 21:55:43 +0000

Resources are extremely important for a programmer since they can greatly improve productivity while coding. I have been collecting many links throughout months and I wish to share some of them with you. Hopefully, they will be as useful to you as they have been to me. Without further ado, here are some great free and up-to-date resources!

Table of Contents:

Illustrations
Development
CSS
Tailwind
Design
Productivity

Illustrations

Error 404

This source is awesome for finding illustrations you can use for your website's 404 page.

Blush

Blush allows you to download all their illustrations for free for commercial and personal use. It is amazing since it features many illustration styles that can be composed to create new ones. Also, they have a Figma plugin so you can immediately get working on them inside your designs.

Smash Illustrations

Smash Illustrations features trendy characters and simple illustrations for free in commercial and personal use. It features more than 250+ objects and characters, and 20+ unique scenes so you can compose them however you like.

Control

Control features high-quality illustrations in solid and linear style for free. They are free to use for commercial and personal use. However, they are in .png format. If you need SVGs then you will have to pay $38 which isn't that bad for illustrations of this quality.

DrawKit

DrawKit features 220+ free to use illustrations. They all come in SVG so you can create awesome compositions! Also, they offer animated illustrations using lottie which is huge for cool and sleek website development.

Open Doodles

If you are a fan of sketchy illustrations then you will love Open Doodles. All illustrations are free to download in SVG or PNG format. Also, they have a composition route and generator so you can get the doodles you need!

Free Illustrations

Free Illustrations feature many illustration backgrounds that are perfect for landing page development.

Mixkit

Mixkit is the Unsplash of illustrations, or that is their objective. It features many illustration categories and also stock videos and music, all free of charge.

Delesign

Delesign gives you many clean illustrations for free. Their main strong point is their diversity.

Development

Majestic

Majestic is a zero-config UI for Jest which makes it easier to see tests log output, instead of using purely the terminal. It can be installed globally or just be opened in any repository using npx majestic

Carbon

Carbon is useful if you want to share sleek images of code snippets inside a tweet or blog.

Squoosh

Compress your images with almost unnoticeable quality loss. Also, you can edit image size and how much quality is lost making it a must for optimizing images for your site.

SVGOMG

SVGOMG delivers a GUI for optimizing your SVG files. Extremely important when working with SVGs for your site.

Kite

Kite is amazing for increasing your code productivity. I believe that in the future AI won't take our jobs but it will be augmented by tools like this. It offers autocompletion in your favorite editors using machine learning trained with 2+ million repositories. It currently works only with Python and JavaScript, but shortly, more languages will be available.

DevDocs

DevDocs is a documentation aggregator. It adds multiple libraries and API documentation in a clean and searchable interface. This is massive for general development so I highly recommend it.

DevHints

This website features cheat sheets for many tools such as bash, React, go, sass, and many more.

Wappalyzer

Want to know the stack of your favorite website? Say no more, Wappalyzer allows you to know fairly quickly. They also have an extension so you find these on the go.

iHateRegex

This site is a holy grail for those that don't want to create their own regex or search all through Google. Think of it as Google for regex.

LottieFiles

Ever heard of Lottie? I had not until I found this website. Lottie is a library that allows you to parse and run animations exported from Adobe After Effects. These animations are beautiful and LottieFiles houses thousands of these for free. However, take into consideration most of them have a CC-BY 2.0 license.

Shape Divider

Shape Divider allows you to generate sleek dividers for your website on the fly. It features a cool UI compared to other sites and works very well.

CSS

Animista

Need some CSS animations inspiration or snippets? Animista got you covered. It features many cool CSS effects that can speed up your development.

Pattern.css

Love to use patterns in your design? Then you will love this one. It is a CSS library that makes distinct classes available for you to create awesome patterns for your website.

CSSeffectsSnippets

Nifty CSS animations for your website.

98.css

98.css lets your nostalgic fantasies come true. If you need to build a website or electron app with Windows 98 style then 98.css will greatly help you.

Tailwind

TailwindComponents

Tailwind is very popular these days, and sites like this show why. TailwindComponents features hundreds of community-built components using tailwind.css. Some of these have a very high quality so be sure to check it out!

Tailblocks

Tailblocks features more high-quality Tailwind components. However, they provide a similar experience to Bootstrap so you can create a whole website using these. Absolutely a must to speed development.

Design

colors.lol

Need palettes that are overly descriptive? Colors.lol is the right place to go to find these. They feature 10+ of these palettes which can make your design more vibrant.

ColorMind

Colormind generates color schemes using deep learning. You can lock the colors and get others that complement that one.

Ucraft Logo Maker

This is my go-to whenever I need a quick logo for a side project. They feature thousands of icons that can help you create many logo combinations. For free commercial and personal use, they let you download a PNG version of your logo.

AppMockUp

AppMockUp lets you generate mock-ups for Android and iPhones without much work. If you are a mobile developer, be sure to check this one out.

Webframe

Webframe has thousands of design inspiration based on real websites.

FontSpark

FontSpark allows you to discover your next favorite font by generating different ones until you like it.

HackDesign

Have a lot of time and want to learn design? Then HackDesign is for you. This website features many lessons that can teach you what you need to become a designer.

Checklist Design

If you are designing or building a website, these checklists can be a life-saver. They guarantee accessibility and great UX for different sections of your site such as forms, typography, buttons, and many more.

Remove BG

The title is pretty self-explanatory. This tool makes it a breeze to delete the background from your images so you can use it in your designs or website.

Unscreen

Just like remove.bg but for gifs and videos.

Productivity

Sejda

Sejda provides an online sleek PDF editor. Awesome for editing your CV!

GetTerms

GetTerms generates a Privacy Policy and Terms of Service tailored for your app. This is awesome for saving time when building a web product.

Top Hunts Time Machine

This tool allows you to see the most famous products featured in Product Hunt. If you want to find resources, be sure to check this out monthly.

Notion

Notion is so good. So good that it is in fact my daily writing platform. I just love how clean and efficient it is for blogging and note-taking.

Writty

Need a super lean and sleek editor for writing? Then you will like Writty. It features a super simple editor that saves all you write inside your browser so you don't have to worry about it being exposed to the Internet so easily. Also, it is open-source which is a plus.

Grammarly

This is a must for writing anything on the Internet. I compare this tool to ESLint since it allows you to find errors before you even notice them. Developers can benefit from this whenever we are writing a GitHub issue, a Stack Overflow question, ...

OpenSource Builders

OpenSource Builders offers many open-source alternatives to common products such as Facebook, Slack, Shopify, and many more.

Wave

If you are a freelancer or have your own business, Wave can help with accounting, invoicing, and receipts for free on the web.

Clockify

A truly free time tracker for individuals and teams. Clockify allows you to log time easily and has many features for you to manage this data.

Untools

Untools features many thinking patterns that can help you during programming.

Conclusion

I hope all of these resources can help you build better websites and apps as they have helped me! If you have another favorite resource, please write them up in the discussion below.

For more up-to-date web development content, follow me on Twitter, and Dev.to! Thanks for reading! 😎

How to Find Solutions to Your Programming Problems Outside of Stack Overflow

Jose Felix — Tue, 02 Jun 2020 19:46:44 +0000

Every programmer has found himself looking for answers in Stack Overflow whenever he has no idea how to solve a problem. It is basically the haven of sharing solutions to frequent coding or to be discovered coding problems. However, what if you don't find the answer you are looking for and your posted question doesn't seem to be getting traction. In this case, there are some ways you can solve your contrived problem without needing Stack Overflow.

In this post, I'll teach you how I find solutions to my problems outside of Stack Overflow and how I no longer depend on it.

First Alternative: Using GitHub

GitHub is the best alternative to Stack Overflow. I've noticed common problems that are related to libraries or new features will mostly be found inside a GitHub discussion. Otherwise, those that are related to syntax errors will be in Stack Overflow. One way to find GitHub discussions is by using Google's site query filter:

site:github.com <YOUR QUERY>

This will return only results coming from GitHub, perfect for finding these discussions.

If you don't find any relevant results using the filter, there are other ways of finding these discussions.

One way is to use GitHub's search bar to find a preexisting library or repository that may contain solutions to problems similar to what you are facing. For example, if I am having problems setting up Circle CI with Cypress then I would search for Cypress Circle CI. Then look at the first results and analyze if they have what I'm looking for.

If a Library is Causing Problems

If you know a library is the culprit of your problem then you could search for an issue inside its codebase. For example, recently I had a problem with Cypress stubs. I wasn't finding any relevant answers to my problem on Google so I decided to search on their repository. When doing this kind of search be sure to check both open and closed issues.

When I search for my issue, I immediately found many related issues and ended up finding a solution in the second result.

If no issue is found, there is another way: create an issue. Creating an issue is very straightforward and there are many developers ready to help you with your problem. However, they can take some time before they are resolved.

The last alternative and sometimes most time consuming is to dive into the source code. You can use the repository's search bar to find relevant parts in the code that could lead you to a solution or opening a Pull Request with a fix.

Second Alternative: Finding an npm Package

I vaguely mentioned this before by using the GitHub search bar to find a preexisting library or repository. Regardless, npm has millions of packages that are published and ready to be installed with code that will solve your problem. Furthermore, npm has its own search bar which lets you filter by:

Popularity. indicates how many times the package has been downloaded. This is a strong indicator of packages that others have found to be useful.
Quality. Quality includes considerations such as the presence of a README file, stability, tests, up-to-date dependencies, custom website, and code complexity.
Maintenance. Maintenance ranks packages according to the attention they are given by developers. More frequently maintained packages are more likely to work well with the current or upcoming versions of the npm CLI, for example.
Optimal. Optimal combines the other three criteria (popularity, quality, maintenance) into one score in a meaningful way.

This information comes from this documentation page on npm's website.

My recommendation is to use these filters to your advantage. Filter mostly by Optimal so you can find which package is more likely to work for your codebase. Also, take into consideration its bundle size and capabilities such as tree shaking.

Third Alternative: Using an Online Tutorial

This is very useful if your problem is not solved by a library or it requires multiple steps or libraries to solve. You can find these tutorials by searching 'how to ...' on Google, Medium, Dev.to, YouTube, and many others. Do take note that these tutorials may use outdated methods, so be sure to check the date and find the most recent.

Fourth Alternative: Ask an Experienced Friend

Asking for help from a friend that has more experience is an efficient way to solve a problem. The main benefit is that their answer can be tailored to your problem and they can give advice along with the solution. Also, they could teach you how they solve problems when you can't find them online which is a big plus in the long run. If you don't know anyone that fits these criteria, feel free to use social media such as Reddit, Twitter, and Discord to meet other developers.

Fifth Alternative: Do it Yourself

If you have tried all other alternatives and still do not find your solution then it is time for you to create your solution. This will be the most time consuming of all. After you have found the solution to your problem then I recommend you share it with the world since someone may stumble on a similar problem like yours.

To find a solution by yourself I recommend that you follow the next steps:

Understand your problem. Try to cover each edge case where your problem occurs and maybe write down what you have found so you don't forget.
Research. Sometimes this may not be needed, but if it is necessary, be sure to check existing techniques that may help you. You could find leads in books, or through colleagues. For example, if you are having problems with Stack Overflow then search for books, videos, or courses on algorithms that can give you potential methods of solving the issue.
Come up with possible solutions. Brainstorm for possible solutions and write them down. If you can't come up with any then repeat the first two steps. Also, don't try to sweat solutions in one sitting, clearing your mind can allow your subconsciousness to find them for you.
Implement a solution. With all the solutions you have written try to select the one which seems most effective.
Revise. Check if your current solution is what you need by checking if you solved what you had written in step 1. Also, if it can be improved further by writing comments, testing, and cleaner syntax.

Conclusion

Software development is about solving problems so you can contribute to the world or yourself amazingly. I hope that this post has given you alternatives so you can find solutions to problems you will encounter throughout your career without using Stack Overflow. Don't get me wrong, Stack Overflow is amazing, and if you find your problem there or you posted your question and got an answer, then, by all means, use it. Best of luck in your development journey 🎉

Create and Publish a Supercharged TypeScript Codebase

Jose Felix — Mon, 25 May 2020 18:10:11 +0000

Our job as a programmer is to constantly find solutions to problems. Since we follow a DRY (don't repeat yourself) philosophy, whenever we encounter a problem, we immediately search for a module or discussion which has a solution. Sometimes the module found is not reliable to add to our codebase since it lacks proper testing coverage or doesn't look dependable at all.

In this post, I'll focus on the process of creating and publishing a TypeScript module. It will feature a codebase with proper testing and a publishing pipeline that will give you confidence while shipping code!

What We'll Use

Setting up a robust module codebase is hard. Adding tools like ESLint, Prettier, Jest, Rollup, or Webpack, a continuous integration pipeline, and many more can be daunting. A developer does not want or need to spend all day just to create the backbone of a library. That is why we'll use something called tsdx which sets this all up for us and also gives us some cool human-readable errors. Think of it as the create-react-app of modules.

Creating our Codebase

To start, let's run this command in the terminal. This will start a new project. I'll name our module react-awesome-library.

When choosing the library select any template you need. In this case, I'll use React.js.

npx tsdx create react-awesome-library

It will add all necessary dependencies, an example, a continuous integration pipeline with GitHub Actions, and a test. This is perfect for starting development right away!

This is an example of what it will generate.

Publishing The Module

First, create an npm account, and be sure to confirm your email. Head here if you don't have one.

Second, log in to your account in your terminal using:

npm login

It will prompt you to enter your username, password, and email.

Finally, just run npm publish to publish your package:

  npm publish

Supercharging Publishing Process

Whenever we need to publish a package, we'll probably want to:

Run written tests.
Update version in package.json. Most modules follow Semantic Versioning. It consists of a version number like this 1.1.2, where each number represents MAJOR.MINOR.PATCH. A major version indicates incompatible API changes. A minor version marks functionality that is backward-compatible. A patch version specifies that it is a backward-compatible bug fix.
Create a git tag for easier navigation between versions.
Push the new version to GitHub.
Push the new version to npm
Create a release note for the package.

Handling these can be tiresome and time-consuming. That is why a package called np makes it easier to do all these tasks. Thus, let's install it:

npm install --global np

You may have to use sudo for global installs.

For np to work we have to at least push once to a git repository. Here are some steps to set up for any git repository:

# Initialize git repository
git init

# Adds a remote repository
git remote add origin <REPOSITORY_URL>

# Commit changes
git add .
git commit -m "First Commit"

# Push your changes
git push -u origin master

After you have pushed your code changes, just run np --no-2fa (Note: here we disable 2-factor authentication, but it is highly recommended to enable it.) to publish your package.

That's it! It ran all necessary checks before publishing, and we can rest assured that we didn't miss anything in our pipeline.

Conclusion

Sharing code in a module is an important task for developers. Creating a module can be daunting since it requires setting up many tools like Webpack or Rollup, ESLint, Prettier, and many more. Thankfully, there are tools like tsdx and np that supercharge our development and reduce the time taken to set up a TypeScript package ready for development. 💻😎