DEV Community: Laura Carballo

Storybook for everyone: CSF vs. MDX

Laura Carballo — Tue, 20 Apr 2021 22:31:40 +0000

Today, I'm going to talk about Storybook v6. It is such a great tool to design, build, document and test isolated components and organize a perfect component library.

The Component Story Format (CSF) is the recommended way of writing stories but more recently, Storybook introduced the option of writing stories using MDX Format so we can easily document our components with a format that we are all very familiar with.

In this post I'll be covering both ways of writing stories with the aim of showing some benefits of both tools and let you choose what works best for your project.

I'll be using a simple Avatar component to serve as example and we'll be creating our stories based on it. I usually build my component libraries using React and Style Components so that's what we'll be using today too.

Our Avatar will look like this:

import styled from "styled-components";
import PropTypes from "prop-types";

export default function Avatar({ src, size, className, alt }) {
  return <Image size={size} className={className} src={src} alt={alt} />;
}

const Image = styled.img`
  border-radius: 100%;
  height: ${(props) => sizes[props.size]};
  width: ${(props) => sizes[props.size]};
`;

const sizes = {
  small: "30px",
  medium: "60px",
  large: "160px",
};

Avatar.propTypes = {
  /**
  The display src of the avatar
  */
  src: PropTypes.string,
  /**
  The display size of the avatar
  */
  size: PropTypes.oneOf(Object.keys(sizes)),
  /**
  Preserve className for styling
  */
  className: PropTypes.string,
  /**
  Include alt tag for accessibility
  */
  alt: PropTypes.string,
};

Avatar.defaultProps = {
  size: "medium",
  src: "/defaultAvatar.svg",
  alt: "avatar",
};

For those new to Storybook, a story is composed of a Canvas, which shows our rendered component and a Docs Block, which are the building blocks of Storybook documentation pages. The PropTypes function will be used in our Docs Block later to show our ArgsTable with all the args (props) included in our component.

Component Story Format (CSF)

Let's begin with Storybook's recommended syntax, CSF.

In CSF, stories are defined as ES6 modules. Consequently, each story is composed of a single default export and one or multiple named exports.

The default exports serves as a default structure for all the stories that we'll write for a component, in our case, the Avatar.

// Avatar.stories.js/ts

import React from "react";
import Avatar from "../components/Avatar";

export default {
  title: "Components/Avatar",
  component: Avatar,
};

The named export is a function that describes how to render a component, so it would simply look like this:

export const Default = () => <Avatar src="/defaultAvatar.svg" size="medium" />;

But we're usually building our component library for documentation purposes so we want to be able to interact with our story and check every use case. For this reason, it is quite handy to include args so we can benefit from the Controls addon and Actions addon.

In the Storybook documentation they use the .bind() method to create a reusable template to pass the components args to each of the component's stories. This comes in handy when we're going to have multiple stories from a single component since it reduces code repetition.

const Template = (args) => <Avatar {...args} />;

export const Default = Template.bind({});
Default.args = {
  src: "/defaultAvatar.svg",
  size: "medium",
  alt: "avatar",
};

export const Profile = Template.bind({});
Profile.args = {
  src: "/lauraAvatar.svg",
  size: "small",
  alt: "user profile",
};

But if you're working closely with designers or other colleagues that are not too comfortable or familiar with the .bind() method, passing args within each story is also good. We end up having a bit more repetition but the code is more readable and you can save yourself the JavaScript lesson.

export const Default = (args) => <Avatar {...args} />;
Default.args = {
  src: "/defaultAvatar.svg",
  size: "medium",
  alt: "avatar",
};

Alright, so now that we have completed our Avatar story we should probably include some documentation for it. That's when using CSF can get a bit tricky.

To add a description in our main Story, we need to insert it inside the parameters object usign parameters.docs.description.component in our export default or parameters.docs.description.story for our named exports.

export default {
  title: "Components/Avatar",
  component: Avatar,
  parameters: {
    component: Avatar,
    componentSubtitle:
      "An Avatar is a visual representation of a user or entity.",
    docs: {
      description: {
        component: "Some description",
      },
    },
  },
};

const Template = (args) => <Avatar {...args} />;
export const Default = Template.bind({});
Default.args = {
  src: "/defaultAvatar.svg",
  size: "medium",
  alt: "avatar",
};
export const Profile = Template.bind({});
Profile.args = {
  src: "/lauraAvatar.svg",
  size: "small",
  alt: "user profile",
};
Profile.parameters = {
  docs: {
    description: {
      story: `This is a story`,
    },
  },
};

As you can see, this is a bit of a tedious way of writing documentation.

MDX

Writing stories with MDX fixes the previous issue. It allows anyone familiar with the simple Markdown .md format to write documentation. The main benefit is that now non-technical team members can be a part of documenting component libraries.

Designers can now share their design tokens and write documentation to make developers understand the reason behind design patterns. Here is a very cool example from the Storybook MDX announcement article. Philip Siekmann created an amazing addon that generates design token documentation from your stylesheets and asset files and the demo file is documented using MDX.

Imagine that in our Avatar story we want to include documentation that ensure our component's best practices. MDX makes this super easy.

import { Meta, Story, Canvas, ArgsTable } from "@storybook/addon-docs/blocks";
import Avatar from "../components/Avatar";

<Meta
  title="Components/Avatar"
  component={Avatar}
  argTypes={{
    src: {
      name: "source",
      control: { type: "text" },
    },
    size: {
      name: "size",
      defaultValue: "medium",
      control: {
        type: "select",
        options: ["small", "medium", "large"],
      },
    },
  }}
/>

# Avatar

An `Avatar` is a visual representation of a user or entity.

The `small` size should only be used inside a `navbar`.

We should always make sure that we provide an alternative text for screen readers. Therefore, always ensure that the `alt` tag is being used in the component.

<Canvas>
  <Story
    name="Default"
    args={{
      src: "/defaultAvatar.svg",
      size: "medium",
      alt: "default"
    }}>
    {(args) => <Avatar {...args} />}
  </Story>
</Canvas>;

<ArgsTable of={Avatar} />

The ArgsTable is going to render a table in the Docs Blocks with all of the available args. Notice that when using MDX even if we have the Controls addon we can't interact with the component's arguments dynamically in the Docs Blocks but we can customise this table using argsType inside the <Meta /> component.

As you can see, the MDX structure is very similar to CSF since in the back, Storybook will compiled the MDX files into CSF.

Source Dynamic code snippet

If you're using decorators in your component, you might have encountered something like this inside the source code snippet:

// CSF
<div
  style={{
    margin: "2em",
  }}
>
  <No Display Name />
</div>

// MDX
<MDXCreateElement
  mdxType="div"
  originalType="div"
  style={{
    margin: "2em",
  }}
>
  <No Display Name />
</MDXCreateElement>

Decorators provide extra "external" information about a component like extra markup for styling, providing side-loaded data or including required context as ThemeProvider. We can use them globally but also render decorators individually inside each component. When used locally inside our component, these decorators are causing some issues inside the source code snippet.

There are plans of fixing this in the next version but currently, you can use a workaround changing the source code to code using parameters.docs.source.type.

export default {
  title: "Components/Avatar",
  component: Avatar,
  parameters: {
    docs: {
      source: {
        type: "code",
      },
    },
  },
};

I have created a PR for Storybook in an attempt to fix this, so it would be great to get any feedback from you all!

Conclusion

Both CSF and MDX provide a great way of building component libraries. Choosing one over the other mainly depends on your team structure or the usage your planning on having from your component library.

I recently ran a twitter poll on prefered method when writing stories and nearly 70% of the people (80 votes aprox.) voted on using CSF, which is understandable as it is still the standard and recommended way. But, MDX is still a very convenient way of writing stories in those cases where CSF seems a bit of a barrier for non technical users or our component needs precise and well structured documentation.

In my opinion you should not pick between CSF or MDX, they are both a great way of writing stories and both work best when complementing each other.

Media queries are more than responsive design

Laura Carballo — Mon, 12 Apr 2021 23:13:05 +0000

When we think of media queries we automatically think of this:

@media screen and (max-width: 640px) {
  /* CSS for mobile */
}

Media queries are generally used to build responsive applications but did you know that there is more to them than that? In this post I will be covering some of them with the purpose of giving more visibility to simple tools that can help the web be more accessible and also enhance user experience.

Responsive design

Using the @media rule leaves a space for us to change styling depending on different screen sizes and therefore provides a dynamic tool for building responsive designs.

But, when it comes to building a responsive layout, we can also use CSS grid. The minmax() CSS grid function is very simple to use and it helps us structure responsive layouts in one single line of code.

Think of the following layout:

With minmax() we are able to compose our layout and keep it responsive just using grid and we can use the @media rules for specific components and other edge cases.

Note: Although minmax() is supported in most browsers, it is not supported in Internet Explorer, so we need to keep that in mind when using it.

Accessibility

We all know that media queries are great to build responsive applications but what about using them to create accessible applications too?

Media queries prefers-reduced-motion and prefers-color-scheme allows us to do so. Others like, prefers-contrast and inverted-colors are not supported yet by many browsers so I won't be covering them much today.

Reduced Motion

Animations are very fun to build and they are a huge part of the web. While they can enhance our user's experience, animations can also cause some problems. Some users can get easily distracted or even get dizzy with certain effects.

With prefers-reduced-motion removing animations can be quite simple:

@media screen and (prefers-reduced-motion: reduce) {
  .animation {
    animation: none;
  }
}

reduce indicates that the user has indicated inside the computer settings that they prefer interfaces without animations.

The no-preference usecase indicates that the user has not made any preference in the system.

I truly recommend reading this article by Eric Bailey where he speaks about the impact and usage of animations and also provides this code, as a solution to turn off animations.

@media screen and (prefers-reduced-motion: reduce), (update: slow) {
  * {
    animation-duration: 0.001ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.001ms !important;
  }
}

The prefers-reduced-motion query is broadly supported so there is no excuse to not use it, simply do!

Contrast

Dark mode is the new feature that many companies are recently focusing on. This is useful for users sensitive to light or with low vision.

prefers-color-scheme also checks for the user's theme preferences in the system. If we already have a dark mode build for our website, we can automatically provide this option for our users based on their preferences.

@media screen and (prefers-color-scheme: dark) {
  body {
    background-color: black;
    color: white;
  }
}

light indicates that the user prefers a light theme or has not selected a preference and dark indicates a dark display.

Conclusion

Media queries have more to them than just achieving responsive designs, they can easily make our application more accessible for our users just by simply adding a couple lines of code.

If we can check for user's preferences from their browser or system settings we can automatically render the user's preferred options and save ourselves from building toggle functionalities.

We are still waiting on browser support for other queries like prefers-contrast and inverted-colors. Microsoft introduced -ms-high-contrast for Microsoft Edge v18 or earlier but it is a non-standard feature so it is not recommended to use in production sites and inverted-colors is only supported in Safari.

But, good news is that there seems to be a working draft for new media queries and there are more accessibility tools being introduced.

That's it for me today! Thanks for reading!

Serverless Authentication with AWS Lambda

Laura Carballo — Tue, 06 Apr 2021 12:25:14 +0000

When it comes to authentication it is highly recommended to use a third party service. There are multiple options like Auth0 or Magic.link that provide an easy to integrate authentication that allows us developers to not worry about security issues.

But, for those getting a bit curious about how authentication really works in serverless applications, I have come up with this easy tutorial that will guide you through the process.

We’ll be using serverless functions to configure our backend. I also like using the serverless framework, since it simplifies a lot the process of developing and deploying serverless functions, while the serverless offline plugin emulates AWS Lambda and API Gateway on your local machine.

With all of that said, let’s start!

Setup

As I’ve said, the serverless framework makes it easy to set up our serverless environment.

Just run these commands in your project's folder:

Install serverless CLI globally:

npm install -g serverless

Add serverless offline plugin:

npm install --save-dev serverless-offline

Make sure to set up your AWS credentials and run serverless to verify that everything is working properly.

We can now install our dependencies: jsonwebtoken, bcrypt and the cookie package.

npm install jsonwebtoken bcrypt cookie

serverless.yml

Briefly, the serverless.yml serves as a schema for our serverless application. It will configure our functions and create our users database in DynamoDB. We'll be configuring something like this:

Looking to our basic schema, we will be needing three lambda functions:

/signup and /login: handle POST requests with the user’s information from the login and sign up form.
/profile: handles GET request of our user’s profile retrieved from the database.

Regarding our database, to keep it simple we’ll create a single-table DynamoDB database with a partition key (HASH key) of userId and a sortKey (RANGE) which we’ll be our user’s profile. We won't be using the sortKey now but it will help us access data in the future once we start scaling our application.

service: users
frameworkVersion: "2"
provider:
 name: aws
 runtime: nodejs12.x
 environment:
   USERS_TABLE: { Ref: usersTable }
 iamRoleStatements:
   - Effect: Allow
     Action:
       - dynamodb:PutItem
       - dynamodb:GetItem
     Resource: { Fn::GetAtt: [usersTable, Arn] }
functions:
 signup:
   handler: handler.signup
   events:
     - http:
         path: signup
         method: post
         cors: true
 login:
   handler: handler.login
   events:
     - http:
         path: login
         method: post
         cors: true
 profile:
   handler: handler.profile
   events:
     - http:
         path: profile
         method: get
         cors: true
resources:
 Resources:
   usersTable:
     Type: AWS::DynamoDB::Table
     Properties:
       TableName: "users"
       AttributeDefinitions:
         - AttributeName: userId
           AttributeType: S
         - AttributeName: sortKey
           AttributeType: S
       KeySchema:
         - AttributeName: userId
           KeyType: HASH
         - AttributeName: sortKey
           KeyType: RANGE

plugins:
 - serverless-offline

If we run serverless deploy in our command line, serverless will deploy our functions and for now, it will create our database inside DynamoDB.

Creating JWT and generating a Cookie

Before we start building our functions, we need to ensure that our users are able to stay logged in while they browse through our application. To do so, we’ll create a JSON Web Token containing our userId and we’ll store it inside a cookie in the users browser, these tokens can then be verified and decoded allowing the user to browse the private routes from our application.

Important: Don’t forget to add your JWT secret and store it safely inside your .env file. It is important that you save this key in a safe place since it is what keeps your application secure and prevents unauthenticated users from impersonating others and accessing your private routes.
Also note that in production cookies should have a httpOnly attribute to prevent XSS, a Secure attribute to guarantee cookies are only transferred via HTTPS, and a SameSite=Strict attribute to prevent CSRF.

const jwt = require("jsonwebtoken");
const cookie = require("cookie");

const DAY = 24 * 60 * 60; // 1 day in seconds

const { JWT_SECRET } = process.env;

module.exports.generateCookie = (userId, expireTimeInDays) => {
  const token = jwt.sign({ userId }, JWT_SECRET, {
    expiresIn: expireTimeInDays + "d",
  });

  return cookie.serialize("token", token, {
    maxAge: expireTimeInDays * DAYS,
    httpOnly: true,
  });
};

Also, we should never store our user’s password in plain text inside our database so we’ll use bcrypt to hash it. We'll use bcrypt.hash to hash our user's password before we store it in our database and later use bcrypt.compare to check if the password the user provided when logging in is matching the hash.

const bcrypt = require("bcrypt");
const ITERATIONS = 12;

module.exports.hashPassword = async (password) => {
 const hash = await bcrypt.hash(password, ITERATIONS);
 return hash;
};

module.exports.matchPassword = async (password, hash) => {
 const match = await bcrypt.compare(password, hash);
 return match;
};

Setting up our handler functions

Let’s start with the signup handler. We will first parse the request body containing our user’s data, hash the password calling the hashPassword function and add the user’s inputs and hashed password inside DynamoDB.

Once that’s done, we’ll create a cookie that will be sent inside the response headers to the browser.

Also, we'll be using the user's email as our userId.

module.exports.signup = async (event) => {
  const { name, email, password } = JSON.parse(event.body);

  if (name && email && password) {
    const userId = email;
    const hash = await hashPassword(password);

    await dynamoDb
      .put({
        TableName: "users",
        Item: {
          userId: email,
          sortKey: "profile",
          name: name,
          password: hash,
        },
      })
      .promise();

    const cookie = generateCookie(userId, 1);

    return {
      statusCode: 200,
      headers: {
        "Set-Cookie": cookie,
      },
      body: JSON.stringify({ success: true }),
    };
  } else {
    return {
      statusCode: 401,
      body: JSON.stringify({
        success: false,
        error: "Enter a valid name/email/password",
      }),
    };
  }
};

Our login handler will check if the user's email exists in the database. We then check if the user’s password matches the hashed password in the database and create and send a cookie inside the response headers.

module.exports.login = async (event) => {
  const { email, password } = JSON.parse(event.body);

  if (email && password) {
    const { Item } = await dynamoDb
      .get({
        TableName: "users",
        Key: { userId: email, sortKey: "profile" },
      })
      .promise();

    if (!Item) {
      return {
        statusCode: 404,
        body: JSON.stringify({ success: false, err: "user not found" }),
      };
    }

    const { userId, password: hashedPassword } = Item;
    const matchedPassword = await matchPassword(password, hashedPassword);

    if (matchedPassword) {
      const cookie = generateCookie(userId, 1);
      return {
        statusCode: 200,
        headers: {
          "Set-Cookie": cookie,
        },
        body: JSON.stringify({ success: true }),
      };
    } else {
      return {
        statusCode: 401,
        body: JSON.stringify({ success: false, err: "incorrect password" }),
      };
    }
  }
};

Finally the profile handler, which is a protected route, gets the cookie from the headers, we parse it with the help of the cookie package and verify if the JSON Web Token is still valid and hasn't expired, if so, the user is authenticated.

module.exports.verifyCookie = (cookieHeader) => {
  const { token } = cookie.parse(cookieHeader);
  return jwt.verify(token, JWT_SECRET);
};

If the verifyCookie function is successful, it will return the userId from the token and we can use that to get the user's data from the database.

module.exports.profile = async (event) => {
  const cookieHeader = event.headers.Cookie;
  try {
    const decoded = verifyCookie(cookieHeader);
    const data = await dynamoDb
      .get({
        TableName: "users",
        Key: { userId: decoded.userId, sortKey: "profile" },
      })
      .promise();
    return {
      statusCode: 200,
      body: JSON.stringify({ success: true, name: data.Item.name }),
    };
  } catch (error) {
    return {
      statusCode: 401,
      body: JSON.stringify({ success: false, err: "not authorized" }),
    };
  }
};

Conclusion

That's it for now! I hope you found this post useful and it gave you an idea of how authentication in a serverless environment could work.

Here's also a link to the Github repo

Please let me know your thoughts in the comments below.

Get to know me better!
Twitter Github Website