Forem: Eduardo Henrique Gris

My experience writing articles: motivation and benefits

Eduardo Henrique Gris — Sat, 30 Aug 2025 18:34:29 +0000

Introduction

Portuguese version: Minha experiência escrevendo artigos: motivação e benefícios
Normally, the articles I write focus on technical content related to React, but in this one I intend to do something different.
The idea is to share my experience with writing articles, covering motivation, benefits and when to write them.

Motivation

Many times while developing code, I came across new features and technologies that required me to study documentation and look up how to use them. Development articles were a great source of information in this context.
As I went deeper into different topics and libraries, I realized that just as I had searched for content that helped me, I could also contribute with what I learned, not keeping the knowledge only to myself, but sharing it with others.

Benefits of writing articles

Sharing knowledge with others:

Just as articles helped me during code development, the idea of writing articles also comes from wanting to contribute to other people’s learning and search for information.

Expanding your network with other developers:

Once you start contributing to others, you begin to create a new network of connections with people who were in some way impacted by what you wrote.

Improving communication:

There’s a difference between knowing something and being able to share it with others. As I kept writing articles, I gradually improved over time and also received suggestions that added value to my writing.
For example, one suggestion was to make the code snippets in the articles look better visually. Another was that, since I write in two languages (Portuguese and English), I should include a link in each article pointing to its version in the other language.

Personal learning:

This was something I didn’t initially expect to be a big benefit, but it turned out to be one of the most valuable aspects of writing technical content.
For instance, in many setup-related articles, I came across situations where I knew which libraries to add and how to configure the files, but not deeply why each of those steps was necessary. Writing a setup article pushed me to study the reasoning behind each config file and library, which not only helped me produce a more complete article but also expanded my own understanding.
Another specific example was when I planned to write an updated article on code standardization with eslint. While researching the differences from one version to another, I came across a new library called typescript-eslint. Since the article was about code standardization in React with Typescript, I decided to learn this new library using a personal project and only then write the article about it. In this way, the initial idea of writing an article led me to learn an new library.

When to write articles

In my opinion, there isn’t a "perfect" moment to start writing.
I’ve often heard phrases like, "I don’t have full mastery of the subject", but in a way, no one truly does. What you might consider "a small thing" to write about could be completely new or more specific for many people, who may not have had prior knowledge of it in a language or library.
Another common thought is, "I know the subject, but I don’t know how to explain it". Writing articles helps improve that skill. When I look back at my first articles, there are several points I would change today, but it was all part of the process, starting to write with less experience in order to produce better articles in the future and continue honing that ability.
This article is my first one with a less technical focus, and I might feel the same way in the future about things I could have written better here.

Conclusion

My main goal was to explain what my experience writing articles has been like, the motivation behind producing them, the associated benefits, and to share my opinion that there isn’t a "perfect" moment to start.
At first, there may be some hesitation in beginning to write articles, but over time you adapt and start enjoying the many benefits that come from writing, both for yourself and for the people who read your work.

Minha experiência escrevendo artigos: motivação e benefícios

Eduardo Henrique Gris — Sat, 30 Aug 2025 18:34:25 +0000

Introdução

English version: My experience writing articles: motivation and benefits
Normalmente os artigos que escrevo tem foco em conteúdos técnicos relacionados com React, mas nesse pretendo fazer algo diferente.
A ideia é mostrar como tem sido minha experiência escrevendo artigos, envolvendo motivação, benefícios e quando escrever eles.

Motivação

Em muitos momentos desenvolvendo código me deparei com novas features e tecnologias, que demandaram estudar documentação, buscar informações de como usar elas. Artigos de desenvolvimento foram uma ótima fonte de informação nesse contexto.
A medida que fui me aprofundando com diferentes temas, bibliotecas, pensei que assim como busquei conteúdos que me auxiliaram, poderia também contribuir com o que aprendi, não guardando só o aprendizado e conhecimento para mim, mas sim contribuindo com outras pessoas.

Benefícios em escrever artigos

Compartilhar conhecimento com outras pessoas:

Assim como artigos me ajudaram durante o desenvolvimento de código, a ideia de escrever artigos vem de colaborar com o aprendizado e busca de informação de outras pessoas também.

Aumentar rede de conexões com outros desenvolvedores:

Uma vez que você contribui com outras pessoas, você começa a criar uma nova rede de conexões, com pessoas que de alguma forma foram impactadas com o que está sendo escrito.

Melhorar a comunicação:

Tem uma diferença entre saber um conteúdo e passar ele para outras pessoas. A medida que fui escrevendo artigos, além de aos poucos ir melhorando com o passar do tempo, recebi sugestões que vieram agregar a escrita deles.
Citando dois exemplos, uma sugestão foi em como deixar os códigos dentro dos artigos com um melhor aspecto visual, outra foi de como eu escrevo em duas línguas (português e inglês), incluir em cada artigo o link para a versão no outro idioma.

Aprendizado próprio:

Isso foi de certa forma algo que não pensei que seria um benefício grande a princípio, mas é um dos maiores que senti escrevendo conteúdo técnico.
Citando alguns exemplos, em muitos dos artigos referentes a setup, me deparei em situações que sabia que libs adicionar, como escrever os arquivos de configuração, mas não a fundo o porquê de todos aqueles passos serem necessários. Sendo um artigo de setup me levou a estudar o porquê de cada parte adicionada nos arquivos de config e o porquê da adição de cada lib, isso além de permitir produzir um artigo mais robusto, contribuiu também com o meu conhecimento do assunto.
Outro exemplo mais específico, foi quando estava pensando em escrever um artigo de padronização de código com eslint, em uma versão mais atualizada em relação a um que já tinha escrito anteriormente. Ao estudar as mudanças que tinha de uma versão para outra, acabei me deparando com uma outra lib chamada typescript-eslint, e uma vez que o artigo envolvia padronização de código em React com Typescript, resolvi aprender essa nova lib usando um projeto pessoal, para depois escrever o artigo sobre ela. Aprendendo dessa forma uma nova lib em decorrência de uma ideia inicial de escrita de artigo.

Quando escrever artigos

Na minha opinião não tem um momento mais propício para começar a escrever.
Muitas vezes ouvi algumas frases como "não tenho domínio completo do assunto", isso é algo que de certa forma ninguém tem. O que você pode considerar "pouca coisa" para produzir um artigo, para muitas pessoas pode ser algo novo, ou algo mais específico que não conheciam de uma linguagem ou biblioteca.
Outra frase "sei o assunto, mas não sei explicar ele", a escrita dos artigos ajuda a aprimorar essa habilidade. Meus primeiros artigos eu dou uma olhada e tem vários pontos que alteraria hoje, mas tudo fez parte do processo, de no começo tentar redigir com menos experiência para produzir melhores artigos para frente e seguir aprimorando essa habilidade.
Esse artigo aqui é o primeiro com teor menos técnico que estou escrevendo, talvez aconteça a mesma percepção no futuro de coisas que poderia ter escrito melhor nele.

Conclusão

Minha ideia geral foi mais explicar como tem sido a experiência na escrita de artigos, a motivação de produzir eles, os benefícios associados e que na minha opinião não existe um momento mais propício para isso.
No início pode se ter um pouco mais de receio em começar a produzir artigos, mas com o tempo vai se adaptando e aproveitando de vários benefícios que vem da escrita deles, seja você ou as pessoas que vão ler eles.

React and typescript components lib, part 7: conclusion

Eduardo Henrique Gris — Mon, 28 Jul 2025 21:39:48 +0000

Introduction

Portuguese version: Biblioteca de componentes React e typescript, parte 7: encerramento

We've reached the final part of the series! The goal of this article is to wrap things up by explaining the motivation behind creating the series, where the topics covered came from and sharing some possible/suggested next steps for improvement.

Motivation

Throughout my time working in development, I had the opportunity to work on projects for different clients using React with Typescript. As I dove deeper, I came across several things that caught my attention like pre-commit hooks, code auto-generation with hygen, among others, which sparked my curiosity about how to configure each of them, define their rules and use them effectively. I was also curious about how to create a component lib and publish it to make it available to others.
With those goals in mind, I started a personal learning project called rjs-components, where I began by configuring the lib with rollup, making the component lib available and gradually adding libs I wanted to learn how to configure and use.
After spending some time developing the lib, I realized I didn’t want to keep what I learned to myself. Instead, I wanted to share it with others, hoping it might help them in their own learning journey as well. That idea sparked the beginning of this series, and now, here we are at its conclusion.

Possible/suggested improvements

Throughout the series, I covered almost everything I used in the component library I’ve been building for study purposes. However, as the number of components continues to grow and deeper changes are made to the codebase, it's worth paying attention to some areas that could be improved.

CHANGELOG.md documentation

Throughout the series, every change made in each version of the library was documented. However, there may be situations where it's not just about adding new features, as was the case in most of this series, but also about removing props, changing component behavior, or introducing other breaking changes.
Because of that, it's important to clearly communicate the type of change introduced in a new version. Below, I’ll share a suggestion based on an example from the study lib I mentioned in the motivation:

## 0.9.0

_May. 15, 2025_

### Breaking Changes

- remove textWeight Button property, but is possible to use textFontWeight
- remove textWeight IconButton property, but is possible to use textFontWeight
- remove textWeight Tag property, but is possible to use textFontWeight
- remove textWeight IconTag property, but is possible to use textFontWeight

### Major Changes

- update general Button default properties: sizes behavior, colors behavior, format behavior, border behavior

### General Changes

- update storybook and dependencies
- add focusColor props to Button
- add activeColor props to Button
- add disabledOpacity props to Button
- add border props to Button
- add hoverBorder props to Button
- add focusBorder props to Button
- add activeBorder props to Button
- update Button tests
- update Button docs

In the Breaking Changes section, it refers to modifications that can break the usage of components that worked in previous versions. For example, some props were removed from components, so if someone was using those props, they’ll need to switch to different ones in the new version to maintain the expected behavior.
The Major Changes section refers to significant updates that do not break the component’s usage but represent large changes that impact the default properties of the component.
The General Changes section includes updates that do not affect existing component usage but add new props to customize the components further.

Similar types between components

As more components are created in the lib, some will share a large number of types. Instead of defining those types separately within each component’s file, it’s possible to create a single file that contains types shared across multiple components. For example, in the study lib I mentioned earlier, there is a file called Common.types.ts which holds types that are common to more than one component. One such example is the relationship between the Button component and the Tag component:

Common.types.ts

// ...

export interface CommonButtonTagProps {
  text: string;
  textColor?: string;
  textFontWeight?: number;
  textFontSize?: string;
  textFontFamily?: string;
  backgroundColor?: string;
  format?: "square" | "semiRounded" | "rounded";
  borderRadius?: string;
  size?: "small" | "medium" | "large";
  padding?: string;
  border?: string;
  icon?: React.ReactNode;
  iconPlacement?: "right" | "left";
  spacing?: string;
}

export interface StyledCommonButtonTagProps {
  $textColor?: string;
  $textFontWeight?: number;
  $textFontSize?: string;
  $textFontFamily?: string;
  $backgroundColor?: string;
  $format?: "square" | "semiRounded" | "rounded";
  $borderRadius?: string;
  $size?: "small" | "medium" | "large";
  $padding?: string;
  $border?: string;
}

And within each component, these shared interface definitions are imported and then extended with the properties that are unique to that specific component.

Tag.tsx

// ...
import {
  CommonButtonTagProps,
  StyledCommonButtonTagProps,
} from "../Common.types";

export interface TagProps extends CommonButtonTagProps {
  type?: "default" | "success" | "alert" | "error";
}

export interface StyledTagProps extends StyledCommonButtonTagProps {
  $type?: "default" | "success" | "alert" | "error";
}

// ...

Button.tsx

// ...

import {
  CommonButtonTagProps,
  StyledCommonButtonTagProps,
} from "../Common.types";

export interface ButtonProps extends CommonButtonTagProps {
  type?: "primary" | "secondary";
  hoverColor?: string;
  focusColor?: string;
  activeColor?: string;
  disabled?: boolean;
  disabledOpacity?: number;
  hoverBorder?: string;
  focusBorder?: string;
  activeBorder?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
}

export interface StyledButtonProps extends StyledCommonButtonTagProps {
  $type?: "primary" | "secondary";
  $hoverColor?: string;
  $focusColor?: string;
  $activeColor?: string;
  $disabledOpacity?: number;
  $hoverBorder?: string;
  $focusBorder?: string;
  $activeBorder?: string;
}

// ...

husky beyond pre-commit

Besides using pre-commit, husky allows you to use other types of git hooks, such as pre-push, post-commit, and others. To do this, inside the .husky/_ folder, you move the specific git hook file you want to use out of the _ folder but keep it inside .husky.
For those who use commit conventions, one option is to configure a library like commitlint by moving the commit-msg file from .husky/_ to .husky and then setting that file to run commitlint. This way, every time a commit is made, it will validate whether the commit message follows the defined conventions and will allow or block the commit accordingly.

lib versioning

During the development of the lib in this series, we always updated the second version number with each change, going from 0.1.0 to 0.2.0, and so on.
The initial zero indicates that the lib is in an early stage of development, and its definitions may change at any time. It is not yet considered a stable release.
Once the library reaches a sufficient level of maturity and stability, the version is updated to 1.0.0, indicating that it is consolidated and ready for production use.
For a better understanding of semantic versioning, I highly recommend visiting https://semver.org/, which explains everything in detail.

Conclusion

The idea of this final article was to be brief, presenting the motivation behind the series and highlighting things to watch out for as the library grows. I want to thank everyone who followed along until now, I hope it has been helpful to you all.

Biblioteca de componentes React e typescript, parte 7: encerramento

Eduardo Henrique Gris — Mon, 28 Jul 2025 21:39:23 +0000

Introdução

English version: React and typescript components lib, part 7: conclusion

Chegamos na última parte da série! A ideia desse artigo é ser um encerramento, explicando a motivação da criação da série, de onde veio os assuntos que trouxe para a série e passando algumas evoluções possíveis/sugeridas.

Motivação

Durante o período que trabalho com desenvolvimento, tive bastante contato com projetos em diferentes clientes usando React com Typescript, me deparando com coisas que chamaram a minha atenção como pre-commit, autogeração de código com hygen, dentre outras, que me levantou a curiosidade de como configurar cada uma delas, como definir suas regras e como fazer o uso delas. Outra curiosidade que tinha era como se criava um lib de componentes e realizava a publicação dela, para disponibilizar para outras pessoas.
Dado esses pontos, criei um projeto pessoal de aprendizado rjs-components, no qual comecei configurando a lib com rollup, disponibilizando a lib de componentes e fui adicionando libs dentro dela que queria aprender a como configurar/usar.
Após um tempo que me aprofundei com o desenvolvimento da lib, me passou a ideia de não manter o que aprendi para mim, mas sim a compartilhar com outras pessoas, para ver se de certa forma auxiliava no aprendizado delas também. Dessa ideia veio o começo dessa série e agora chegamos no encerramento dela.

Evoluções possíveis/sugeridas

Durante a série abordei como conteúdo praticamente tudo que usei na lib que uso para estudo. Mas a medida que a quantidade de componentes vem crescendo e mudanças mais profundas acontecem com o código, vale a atenção em alguns pontos de melhoria.

Documentação do CHANGELOG.md

Durante a série sempre foi documentado a alteração realizada em cada versão disponibilizada da lib. Porém em alguns momentos pode ocorrer não só acréscimo de coisas novas como aconteceu nessa série, mas sim remoção de props, mudança de comportamento de componentes, dentre outras.
Para isso, se torna importante mostrar com maior clareza que tipo de mudança está ocorrendo na nova versão, vou passar uma sugestão com base em um exemplo da lib de estudo que citei na motivação:

## 0.9.0

_May. 15, 2025_

### Breaking Changes

- remove textWeight Button property, but is possible to use textFontWeight
- remove textWeight IconButton property, but is possible to use textFontWeight
- remove textWeight Tag property, but is possible to use textFontWeight
- remove textWeight IconTag property, but is possible to use textFontWeight

### Major Changes

- update general Button default properties: sizes behavior, colors behavior, format behavior, border behavior

### General Changes

- update storybook and dependencies
- add focusColor props to Button
- add activeColor props to Button
- add disabledOpacity props to Button
- add border props to Button
- add hoverBorder props to Button
- add focusBorder props to Button
- add activeBorder props to Button
- update Button tests
- update Button docs

Em Breaking Changes está citando mudanças que podem quebrar o uso dos componentes que funcionavam se usasse versões anteriores. Está citando que foi removida algumas props de componentes, então se alguém fazia uso delas, ao mudar para essa nova versão, precisa usar outras props para manter o comportamento esperado.
Em Major Changes está citando uma mudança que não quebraria o uso do componente, mas é uma mudança grande que impacta as propriedades padrão dele.
Em General Changes está citando mudanças que não impactam os componentes que já estão em uso, mas sim disponibilizam novas props para customizar eles.

types semelhantes entre componentes

A medida que mais componentes vão sendo criados na lib, alguns vão compartilhar grande quantidade dos types. Ao invés de criar separadamente dentro de cada arquivo deles uma definição de types, é possível criar um arquivo que contém os types que são semelhantes entre diferentes componentes. Um exemplo da lib que citei acima, é uma arquivo chamado Common.types.ts que possui types que são semelhantes entre mais de um componente. Um exemplo na lib é em relação ao Button component e Tag component:

Common.types.ts

// ...

export interface CommonButtonTagProps {
  text: string;
  textColor?: string;
  textFontWeight?: number;
  textFontSize?: string;
  textFontFamily?: string;
  backgroundColor?: string;
  format?: "square" | "semiRounded" | "rounded";
  borderRadius?: string;
  size?: "small" | "medium" | "large";
  padding?: string;
  border?: string;
  icon?: React.ReactNode;
  iconPlacement?: "right" | "left";
  spacing?: string;
}

export interface StyledCommonButtonTagProps {
  $textColor?: string;
  $textFontWeight?: number;
  $textFontSize?: string;
  $textFontFamily?: string;
  $backgroundColor?: string;
  $format?: "square" | "semiRounded" | "rounded";
  $borderRadius?: string;
  $size?: "small" | "medium" | "large";
  $padding?: string;
  $border?: string;
}

E dentro de cada componente é importado essas definições de interface e extendido elas com a propriedades que não são em comum entre os componentes.

Tag.tsx

// ...
import {
  CommonButtonTagProps,
  StyledCommonButtonTagProps,
} from "../Common.types";

export interface TagProps extends CommonButtonTagProps {
  type?: "default" | "success" | "alert" | "error";
}

export interface StyledTagProps extends StyledCommonButtonTagProps {
  $type?: "default" | "success" | "alert" | "error";
}

// ...

Button.tsx

// ...

import {
  CommonButtonTagProps,
  StyledCommonButtonTagProps,
} from "../Common.types";

export interface ButtonProps extends CommonButtonTagProps {
  type?: "primary" | "secondary";
  hoverColor?: string;
  focusColor?: string;
  activeColor?: string;
  disabled?: boolean;
  disabledOpacity?: number;
  hoverBorder?: string;
  focusBorder?: string;
  activeBorder?: string;
  onClick?: MouseEventHandler<HTMLButtonElement>;
}

export interface StyledButtonProps extends StyledCommonButtonTagProps {
  $type?: "primary" | "secondary";
  $hoverColor?: string;
  $focusColor?: string;
  $activeColor?: string;
  $disabledOpacity?: number;
  $hoverBorder?: string;
  $focusBorder?: string;
  $activeBorder?: string;
}

// ...

husky além de pre-commit

Além do uso de pre-commit, o husky permite usar outros tipos de git hooks, como pre-push, post-commit, dentre outros. Para isso seria dentro da pasta .husky/_ puxar o git hook que quer utilizar para fora de _, mas deixar ainda dentro de .husky.
Uma possibilidade para quem usa convenções de commit, seria configurar uma lib como por exemplo o commitlint, puxar o arquivo commit-msg de .husky/_ para .husky, e por fim definir dentro desse arquivo para rodar o commitlint. Dessa forma, toda vez que um commit for feito vai validar se está seguindo as convenções de commit definidas para permitir ou não seguir ele.

versionamento da lib

Durante o desenvolvimento da lib nesta série, sempre alteramos o segundo número da versão a cada mudança da lib, subindo de 0.1.0 para 0.2.0, e assim por diante.
O número zero no início indica que está em fase inicial de desenvolvimento, podendo mudar as definições dentro da lib a qualquer momento, ainda não sendo considerada uma versão estável.
Uma vez que a lib atinge um nível de maturidade e estabilidade suficiente, a versão é atualizada para 1.0.0, indicando que a lib está consolidada e pronta para uso em produção.
Para um entendimento melhor referente a versionamento semântico, recomendo bastante acessar https://semver.org/, que explica tudo em detalhes.

Conclusão

A ideia desse último artigo foi ser mais breve mesmo, apresentando a motivação da realização da série e coisas que podem ser observadas a medida que a lib cresce. Agradeço desde já quem acompanhou até aqui, espero que tenha sido útil para vocês.

React and typescript components lib, part 6: code autogeneration with Hygen

Eduardo Henrique Gris — Mon, 30 Jun 2025 22:08:20 +0000

Introduction

Portuguese version: Biblioteca de componentes React e typescript, parte 6: autogeração de código com Hygen

In the second-to-last part of the series, a new library called hygen will be added. By defining a generator with templates, Hygen allows you to auto-generate code with a simple terminal command. The idea is to create a component generator (to generate the base of a new component), since all components follow a certain folder and file naming structure. Moreover, there’s also a consistent writing pattern, whether for the component definition itself, its documentation or its tests.
This way, the generator handles the responsibility of setting up the skeleton for new components, while the developer can focus solely on defining the component's actual behavior.
The goal is to demonstrate the practical application of this in the component library. For a more in-depth reference on how hygen works, here's an article I previously wrote on the topic: Reducing manual work in React with Hygen.

Setup

First, the hygen library will be added:

yarn add hygen --dev

Next, the initial setup of the library will be done by running the following command in the terminal:

npx hygen init self

This command will generate a _templates folder at the root of the project, which enables hygen to run.

General Component Analysis

Before creating the component generator, let's take a general look at how components are defined within the app.

Based on the image above, each component is currently defined inside a folder named after the component itself and consists of five files:

{component_name}.tsx: the component definition
{component_name}.test.tsx: the component's test definition
{component_name}.stories.tsx: the scenarios that will appear in the component's documentation
{component_name}.mdx: the component's documentation
index.ts: defines the export of the component within its own folder

In addition to the internal files inside the component's folder, there's also a central index.ts file located in the src/components directory. This file defines the exports for each component that will be made available by the library.
Therefore, the generator will need to have a template for each of the files listed above.

Component generator

Once we’ve analyzed what defines the components in the library, we can now move forward with creating the component generator.
To create a new generator, run the following command in the terminal:

npx hygen generator new component

I chose to name the generator component to make its purpose clear. After running the command above, a component/new folder will automatically be created inside the _templates directory. This is where we’ll define the templates.
Inside _templates/component/new, there will already be a sample file called hello.ejs.t, which we’ll remove since it won’t be used when running the generator.
Once the generator is created, it's time to define the templates that will serve as the base for autogenerating code.

Templates

For defining the templates, I will use the files from the Text component as a base.

First template: the component itself

For the first template, the Text.tsx file will be used as the base:

import React from "react";
import styled from "styled-components";

export interface TextProps {
  children: React.ReactNode;
  color?: string;
  weight?: "normal" | "bold";
  fontWeight?: number;
  fontSize?: string;
  fontFamily?: string;
}

export interface StyledTextProps {
  $color?: string;
  $weight?: "normal" | "bold";
  $fontWeight?: number;
  $fontSize?: string;
  $fontFamily?: string;
}

export const StyledText = styled.span<StyledTextProps>`
  ${(props) => props.$color && `color: ${props.$color};`}
  ${(props) => props.$fontSize && `font-size: ${props.$fontSize};`}
  font-weight: ${(props) =>
    props.$fontWeight
      ? props.$fontWeight
      : props.$weight
        ? props.$weight
        : "normal"};
  ${(props) => props.$fontFamily && `font-family: ${props.$fontFamily};`}
`;

const Text = ({
  children,
  color = "#000",
  weight = "normal",
  fontWeight,
  fontSize = "16px",
  fontFamily,
}: TextProps) => (
  <StyledText
    $color={color}
    $weight={weight}
    $fontWeight={fontWeight}
    $fontSize={fontSize}
    $fontFamily={fontFamily}
  >
    {children}
  </StyledText>
);

export default Text;

From it, we can notice that what the components will have in common are the imports, the definition of the component’s types named {component name}Props, the styled-components types named Styled{component name}Props, the CSS properties defined with styled-components named Styled{component name}, and finally, the component’s definition and its default export.
With these points in mind, inside the _templates/component/new folder, a file named component.ejs.t will be created, which will correspond to the creation of the component’s skeleton itself:

---
to: src/components/<%=name%>/<%=name%>.tsx
---
import React from "react";
import styled from "styled-components";

export interface <%=name%>Props {
}

export interface Styled<%=name%>Props {
}

export const Styled<%=name%> = styled.<%=html%><Styled<%=name%>Props>`
`;

const <%=name%> = ({
}: <%=name%>Props) => (
  <Styled<%=name%>
  >
  </Styled<%=name%>>
);

export default <%=name%>;

<%=name%> and <%=html%> correspond to dynamic values that will be passed when running the generator, replacing those placeholders in the code above with, respectively, the component’s name and the html element it represents.
The to: field defines where the autogenerated file based on this template will be created. Below it is the code that will be generated inside the file.
This template includes the necessary imports and the skeleton that defines a component within the app, following the points outlined above.

Second template: component tests

For the second template, the Text.test.tsx file will be used as the base:

import React from "react";
import "@testing-library/jest-dom";
import "jest-styled-components";
import { render, screen } from "@testing-library/react";

import Text from "./Text";

describe("<Text />", () => {
  it("should render component with default properties", () => {
    render(<Text>Text</Text>);

    const element = screen.getByText("Text");

    expect(element).toBeInTheDocument();
    expect(element).toHaveStyleRule("color", "#000");
    expect(element).toHaveStyleRule("font-size", "16px");
    expect(element).toHaveStyleRule("font-weight", "normal");
  });

  it("should render component with custom color", () => {
    render(<Text color="#fff">Text</Text>);

    expect(screen.getByText("Text")).toHaveStyleRule("color", "#fff");
  });

  it("should render component with bold weight", () => {
    render(<Text weight="bold">Text</Text>);

    expect(screen.getByText("Text")).toHaveStyleRule("font-weight", "bold");
  });

  it("should render component with custom weight", () => {
    render(<Text fontWeight={500}>Text</Text>);

    expect(screen.getByText("Text")).toHaveStyleRule("font-weight", "500");
  });

  it("should render component with custom font size", () => {
    render(<Text fontSize="20px">Text</Text>);

    expect(screen.getByText("Text")).toHaveStyleRule("font-size", "20px");
  });

  it("should render component with custom font family", () => {
    render(<Text fontFamily="TimesNewRoman">Text</Text>);

    expect(screen.getByText("Text")).toHaveStyleRule(
      "font-family",
      "TimesNewRoman",
    );
  });
});

From it, we can notice that what the components will have in common are the imports, the describe block with the component’s name, and the first test checking the component’s default props.
With these points in mind, inside the _templates/component/new folder, a file named test.ejs.t will be created, which will correspond to the creation of the test skeleton itself:

---
to: src/components/<%=name%>/<%=name%>.test.tsx
---
import React from "react";
import "@testing-library/jest-dom";
import "jest-styled-components";
import { render, screen } from "@testing-library/react";

import <%=name%> from "./<%=name%>";

describe("<<%=name%> />", () => {
  it("should render component with default properties", () => {
  });
});

This template includes the necessary imports and the skeleton that defines the test file within the app, based on the points outlined above.

Third template: documentation scenarios

For the third template, the Text.stories.tsx file will be used as the base:

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Text from "./Text";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof Text> = {
  title: "Text",
  component: Text,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Text>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
    </StorybookContainer>
  ),
};

export const PredefinedFontWeight: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} weight="bold">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const Color: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} color="#800080">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const CustomFontWeight: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontWeight={900}>
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const FontSize: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontSize="30px">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const FontFamily: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontFamily="Arial">
        Text
      </Text>
    </StorybookContainer>
  ),
};

From it, we can observe that what the components will have in common are the imports, the meta definition and the type Story with the component’s name, and the first scenario featuring the component’s default story.
With these points in mind, inside the _templates/component/new folder, a file named stories.ejs.t will be created, which will correspond to the creation of the documentation scenarios skeleton itself:

---
to: src/components/<%=name%>/<%=name%>.stories.tsx
---
import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import <%=name%> from "./<%=name%>";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof <%=name%>> = {
  title: "<%=name%>",
  component: <%=name%>,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof <%=name%>>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <<%=name%> {...args} />
    </StorybookContainer>
  ),
};

This template includes the necessary imports and the skeleton that defines the documentation scenarios file within the app, based on the points outlined above.

Fourth template: component documentation

For the fourth template, the Text.mdx file will be used as the base:

import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./Text.stories";

<Meta of={Stories} />

# Text

Text base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

### Font Weight

There are two font weight predefined properties: normal(default) and bold.

<Canvas of={Stories.PredefinedFontWeight} withToolbar />

## Custom properties

### Color

Text color can be modified.

<Canvas of={Stories.Color} withToolbar />

### Font Weight

Text font weight can be modified.

<Canvas of={Stories.CustomFontWeight} withToolbar />

### Font Size

Text font size can be modified.

<Canvas of={Stories.FontSize} withToolbar />

### Font Family

Text font family can be modified.

<Canvas of={Stories.FontFamily} withToolbar />

From it, we can see that what the components will have in common are the imports, the Meta definition, an initial description with the component’s name, the Canvas and Controls displaying the component’s default scenario, a section for Predefined Properties and a section for Custom Properties.
With these points in mind, inside the _templates/component/new folder, a file named doc.ejs.t will be created, which will correspond to the creation of the component’s documentation skeleton:

---
to: src/components/<%=name%>/<%=name%>.mdx
---
import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./<%=name%>.stories";

<Meta of={Stories} />

# <%=name%>

<%=name%> base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

## Custom properties

This template includes the necessary imports and the skeleton that defines the component’s documentation within the app, based on the points outlined above.

Fifth template: component export inside its folder

For the fifth template, the index.ts file inside the src/components/Text folder will be used as the base:

export { default } from "./Text";

Inside the _templates/component/new folder, a file named componentIndex.ejs.t will be created, which will correspond to the creation of the component’s export inside its own folder:

---
to: src/components/<%=name%>/index.ts
---
export { default } from "./<%=name%>";

This template contains the export of the component inside its own folder.

Sixth template: component export to make it available for library users

For the sixth template, instead of basing it on an existing file, a line will be added to an existing file within the app — specifically, the index.ts file inside the src/components folder:

export { default as Tag } from "./Tag";
export { default as Text } from "./Text";

Inside the _templates/component/new folder, a file named index.ejs.t will be created, which will correspond to adding the export of the new component within the existing file:

---
inject: true
to: src/components/index.ts
at_line: 0
---
export { default as <%=name%> } from "./<%=name%>";

This template already has two differences compared to the other template files. inject: true means that a new file will not be created; instead, code will be injected into an existing file. at_line: 0 specifies that the code will be added at the very first line.

Once all the templates are defined, a script to run the generator will be added inside the package.json:

"scripts": {
  //...
  "create-component": "hygen component new"

It defines the execution of the component generator using hygen.

Example of use

To test the generator's functionality, run the following command in the terminal:

yarn create-component Button --html button

In this command, the component generator is being executed. It will replace every occurrence of <%= name %> with Button and <%= html %> with button.
When executed in the terminal, it will indicate that five files were generated and that code was injected into an existing file:

The structure of the new Button component will look like this:

Button.tsx

import React from "react";
import styled from "styled-components";

export interface ButtonProps {
}

export interface StyledButtonProps {
}

export const StyledButton = styled.button<StyledButtonProps>`
`;

const Button = ({
}: ButtonProps) => (
  <StyledButton
  >
  </StyledButton>
);

export default Button;

Button.test.tsx

import React from "react";
import "@testing-library/jest-dom";
import "jest-styled-components";
import { render, screen } from "@testing-library/react";

import Button from "./Button";

describe("<Button />", () => {
  it("should render component with default properties", () => {
  });
});

Button.stories.tsx

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Button from "./Button";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof Button> = {
  title: "Button",
  component: Button,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Button>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Button {...args} />
    </StorybookContainer>
  ),
};

Button.mdx

import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./Button.stories";

<Meta of={Stories} />

# Button

Button base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

## Custom properties

index.ts (interno a pasta src/components/Button)

export { default } from "./Button";

index.ts (interno a pasta src/components)

export { default as Button } from "./Button";
export { default as Tag } from "./Tag";
export { default as Text } from "./Text";

Automatically generating all the files that serve as the base for defining a component in this way, with the exports also defined.

package.json

The version inside package.json will be changed to 0.6.0, since a new version of the library will be released:

{
  "name": "react-example-lib",
  "version": "0.6.0",
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/griseduardo/react-example-lib.git"
  },
  "scripts": {
    "build": "rollup -c --bundleConfigAsCjs",
    "lint-src": "eslint src",
    "lint-src-fix": "eslint src --fix",
    "lint-fix": "eslint --fix",
    "format-src": "prettier src --check",
    "format-src-fix": "prettier src --write",
    "format-fix": "prettier --write",
    "test": "jest",
    "prepare": "husky",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "create-component": "hygen component new"
  },
  "lint-staged": {
    "src/components/**/*.{ts,tsx}": [
      "yarn lint-fix",
      "yarn format-fix"
    ],
    "src/components/**/*.tsx": "yarn test --findRelatedTests --bail"
  },
  "devDependencies": {
    "@babel/core": "^7.26.10",
    "@babel/preset-env": "^7.26.9",
    "@babel/preset-react": "^7.26.3",
    "@babel/preset-typescript": "^7.26.0",
    "@eslint/js": "^9.19.0",
    "@rollup/plugin-commonjs": "^28.0.2",
    "@rollup/plugin-node-resolve": "^16.0.0",
    "@rollup/plugin-terser": "^0.4.4",
    "@rollup/plugin-typescript": "11.1.6",
    "@storybook/addon-essentials": "^8.6.12",
    "@storybook/addon-interactions": "^8.6.12",
    "@storybook/addon-onboarding": "^8.6.12",
    "@storybook/blocks": "^8.6.12",
    "@storybook/builder-vite": "^8.6.12",
    "@storybook/react": "^8.6.12",
    "@storybook/react-vite": "^8.6.12",
    "@storybook/test": "^8.6.12",
    "@testing-library/dom": "^10.4.0",
    "@testing-library/jest-dom": "^6.6.3",
    "@testing-library/react": "^16.2.0",
    "@types/jest": "^29.5.14",
    "@types/react": "^19.0.10",
    "@types/react-dom": "^19.0.4",
    "chromatic": "^12.0.0",
    "eslint": "^9.19.0",
    "eslint-plugin-react": "^7.37.4",
    "eslint-plugin-storybook": "^0.12.0",
    "husky": "^9.1.7",
    "hygen": "^6.2.11",
    "jest": "^29.7.0",
    "jest-environment-jsdom": "^29.7.0",
    "jest-styled-components": "^7.2.0",
    "lint-staged": "^15.5.0",
    "prettier": "^3.4.2",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "rollup": "^4.30.1",
    "rollup-plugin-dts": "^6.1.1",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "storybook": "^8.6.12",
    "styled-components": "^6.1.14",
    "typescript": "^5.7.3",
    "typescript-eslint": "^8.23.0",
    "vite": "^6.3.5"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "styled-components": "^6.1.14"
  },
  "eslintConfig": {
    "extends": [
      "plugin:storybook/recommended"
    ]
  }
}

CHANGELOG file

Since a new version will be released, the CHANGELOG.md will be updated with what has been changed:

## 0.6.0

_Jun. 30, 2025_

- add hygen
- add component generator

## 0.5.0

_May. 29, 2025_

- change Tag and Text default behavior
- add storybook
- add Tag and Text storybook docs

## 0.4.0

_Abr. 29, 2025_

- setup husky and lint-staged
- define pre-commit actions

## 0.3.0

_Mar. 24, 2025_

- setup jest and testing-library
- add components tests

## 0.2.0

_Fev. 24, 2025_

- setup typescript-eslint and prettier
- add custom rules

## 0.1.0

_Jan. 29, 2025_

- initial config

Folders structure

The folder structure will be as follows:

Publication of a new version

I decided to delete the Button folder and remove the Button export from index.ts (inside the src/components folder), since it was used only to illustrate the usage of hygen but the component itself was not worked on.
It is necessary to check if the rollup build runs successfully before publishing. For that, run yarn build in the terminal, as defined in package.json.
If it runs successfully, proceed to publish the new version of the library with: npm publish --access public

Conclusion

The idea of this article was to create a component generator within the library, based on template definitions, with the goal of speeding up the creation of new components. The generator is responsible for automatically generating the skeleton of a new component.Here is the repository on github and the library on npmjs with the new modifications.

Biblioteca de componentes React e typescript, parte 6: autogeração de código com Hygen

Eduardo Henrique Gris — Mon, 30 Jun 2025 22:08:02 +0000

Introdução

English version: React and typescript components lib, part 6: code autogeneration with Hygen

Na penúltima parte da série, será adicionada uma nova lib chamada hygen, a qual a partir da definição de um gerador com templates, permite autogerar código com um simples comando no terminal. A ideia vai ser criar um gerador de componente (para gerar a base de um novo componente), dado que todos seguem um certo padrão de estrutura de pastas e nomes de arquivos, além disso, devido a possuir também um padrão de escrita seja da definição do componente em si, da documentação ou dos testes.
Dessa forma o autogerador fica com a preocupação de definir o esqueleto dos novos componentes, enquanto o desenvolvedor se preocupa somente com a definição do comportamento do componente em si.
A ideia é mostrar a parte prática da aplicação na lib de componentes, para uma referência mais aprofundada de como funciona o hygen segue um artigo que escrevi anteriormente sobre o assunto: Reduzindo trabalho manual em React com Hygen

Setup

Primeiro será adicionada a lib do hygen:

yarn add hygen --dev

Após, será realizada a configuração inicial da lib executando no terminal:

npx hygen init self

Esse comando irá gerar a pasta _templates na raiz do projeto, que vai permitir executar o hygen.

Análise geral componente

Antes de criar o gerador de componente, vamos analisar de forma geral como são definidos os componentes dentro da app.

Pela imagem acima, hoje cada componente é definido dentro de uma pasta com o nome dele e em cinco arquivos:

{nome_do_componente}.tsx: definição do componente
{nome_do_componente}.test.tsx: definição dos testes do componente
{nome_do_componente}.stories.tsx: definição dos cenários que vão parecer na documentação do componente
{nome_do_componente}.mdx: definição da documentação do componente
index.ts: definição do export do componente dentro da pasta dele

Além dos arquivos internos da pasta com o nome do componente, dentro da pasta src/components, no arquivo index.ts é definido o export de cada componente que será disponibilizado pela lib.
Logo o gerador vai ter que ter um template para cada arquivo comentado acima.

Gerador de componentes

Uma vez feita a análise do que define os componentes da lib, agora seguiremos com a criação do gerador de componente.
Para criar um novo gerador será executado no terminal:

npx hygen generator new component

Resolvi definir o nome de gerador de component para deixar claro o contexto dele. Após executar o comando acima vai ser criado automaticamente uma pasta component/new dentro da pasta _templates. Dentro da pasta _templates/component/new vai ser onde iremos definir os templates, dentro dela já tem um arquivo hello.ejs.t de exemplo, que iremos remover pois não iremos utilizar ao executar o gerador.
Uma vez que criamos o gerador, agora é hora de definir os templates
que ele vai usar como base para autogerar código.

Templates

Para definição dos templates, vou usar como base os arquivos do componente Text.

Primeiro template: componente em si

Para o primeiro template, vai ser levado como base o arquivo Text.tsx:

import React from "react";
import styled from "styled-components";

export interface TextProps {
  children: React.ReactNode;
  color?: string;
  weight?: "normal" | "bold";
  fontWeight?: number;
  fontSize?: string;
  fontFamily?: string;
}

export interface StyledTextProps {
  $color?: string;
  $weight?: "normal" | "bold";
  $fontWeight?: number;
  $fontSize?: string;
  $fontFamily?: string;
}

export const StyledText = styled.span<StyledTextProps>`
  ${(props) => props.$color && `color: ${props.$color};`}
  ${(props) => props.$fontSize && `font-size: ${props.$fontSize};`}
  font-weight: ${(props) =>
    props.$fontWeight
      ? props.$fontWeight
      : props.$weight
        ? props.$weight
        : "normal"};
  ${(props) => props.$fontFamily && `font-family: ${props.$fontFamily};`}
`;

const Text = ({
  children,
  color = "#000",
  weight = "normal",
  fontWeight,
  fontSize = "16px",
  fontFamily,
}: TextProps) => (
  <StyledText
    $color={color}
    $weight={weight}
    $fontWeight={fontWeight}
    $fontSize={fontSize}
    $fontFamily={fontFamily}
  >
    {children}
  </StyledText>
);

export default Text;

Dele pode se notar que o que vai ter em comum entre os componentes vai ser os imports, definição de types do componente com nome {nome do componente}Props, definição de types do styled-components com nome Styled{nome do componente}Props, definição de propriedades css com styled-components com nome Styled{nome do componente} e no fim a definição e export default do componente.
Tendo em vista esses pontos, dentro da pasta _templates/component/new vai ser criado o arquivo component.ejs.t, que vai corresponder a criação do esqueleto do componente em si:

---
to: src/components/<%=name%>/<%=name%>.tsx
---
import React from "react";
import styled from "styled-components";

export interface <%=name%>Props {
}

export interface Styled<%=name%>Props {
}

export const Styled<%=name%> = styled.<%=html%><Styled<%=name%>Props>`
`;

const <%=name%> = ({
}: <%=name%>Props) => (
  <Styled<%=name%>
  >
  </Styled<%=name%>>
);

export default <%=name%>;

<%=name%> e <%=html%> correspondem a valores dinâmicos que vão ser passados ao executar o gerador, para substituir no código acima, correspondendo respectivamente ao nome do componente e ao elemento html que ele corresponde.
Em to: é definido onde o arquivo autogerado a partir desse template vai ser criado. Abaixo dele, o código que vai ser gerado dentro do arquivo.
Esse template traz os imports necessários e o esqueleto que define um componente dentro da app, dado os pontos que foram enumerados acima.

Segundo template: testes do componente

Para o segundo template, vai ser levado como base o arquivo Text.test.tsx:

import React from "react";
import "@testing-library/jest-dom";
import "jest-styled-components";
import { render, screen } from "@testing-library/react";

import Text from "./Text";

describe("<Text />", () => {
  it("should render component with default properties", () => {
    render(<Text>Text</Text>);

    const element = screen.getByText("Text");

    expect(element).toBeInTheDocument();
    expect(element).toHaveStyleRule("color", "#000");
    expect(element).toHaveStyleRule("font-size", "16px");
    expect(element).toHaveStyleRule("font-weight", "normal");
  });

  it("should render component with custom color", () => {
    render(<Text color="#fff">Text</Text>);

    expect(screen.getByText("Text")).toHaveStyleRule("color", "#fff");
  });

  it("should render component with bold weight", () => {
    render(<Text weight="bold">Text</Text>);

    expect(screen.getByText("Text")).toHaveStyleRule("font-weight", "bold");
  });

  it("should render component with custom weight", () => {
    render(<Text fontWeight={500}>Text</Text>);

    expect(screen.getByText("Text")).toHaveStyleRule("font-weight", "500");
  });

  it("should render component with custom font size", () => {
    render(<Text fontSize="20px">Text</Text>);

    expect(screen.getByText("Text")).toHaveStyleRule("font-size", "20px");
  });

  it("should render component with custom font family", () => {
    render(<Text fontFamily="TimesNewRoman">Text</Text>);

    expect(screen.getByText("Text")).toHaveStyleRule(
      "font-family",
      "TimesNewRoman",
    );
  });
});

Dele pode se notar que o que vai ter em comum entre os componentes vai ser os imports, o describe com o nome do componente, o primeiro teste com a análise das propriedades default do componente.
Tendo em vista esses pontos, dentro da pasta _templates/component/new vai ser criado o arquivo test.ejs.t, que vai corresponder a criação do esqueleto do teste em si:

---
to: src/components/<%=name%>/<%=name%>.test.tsx
---
import React from "react";
import "@testing-library/jest-dom";
import "jest-styled-components";
import { render, screen } from "@testing-library/react";

import <%=name%> from "./<%=name%>";

describe("<<%=name%> />", () => {
  it("should render component with default properties", () => {
  });
});

Esse template traz os imports necessários e o esqueleto que define o arquivo de teste dentro da app, dado os pontos que foram enumerados acima.

Terceiro template: cenários de documentação

Para o terceiro template, vai ser levado como base o arquivo Text.stories.tsx:

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Text from "./Text";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof Text> = {
  title: "Text",
  component: Text,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Text>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
    </StorybookContainer>
  ),
};

export const PredefinedFontWeight: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} weight="bold">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const Color: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} color="#800080">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const CustomFontWeight: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontWeight={900}>
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const FontSize: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontSize="30px">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const FontFamily: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontFamily="Arial">
        Text
      </Text>
    </StorybookContainer>
  ),
};

Dele pode se notar que o que vai ter em comum entre os componentes vai ser os imports, a definição de meta e type Story com o nome do componente, e o primeiro cenário com o cenário default do componente.
Tendo em vista esses pontos, dentro da pasta _templates/component/new vai ser criado o arquivo stories.ejs.t, que vai corresponder a criação do esqueleto dos cenários de documentação em si:

---
to: src/components/<%=name%>/<%=name%>.stories.tsx
---
import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import <%=name%> from "./<%=name%>";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof <%=name%>> = {
  title: "<%=name%>",
  component: <%=name%>,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof <%=name%>>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <<%=name%> {...args} />
    </StorybookContainer>
  ),
};

Esse template traz os imports necessários e o esqueleto que define o arquivo de cenários de documentação dentro da app, dado os pontos que foram enumerados acima.

Quarto template: documentação do componente

Para o quarto template, vai ser levado como base o arquivo Text.mdx:

import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./Text.stories";

<Meta of={Stories} />

# Text

Text base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

### Font Weight

There are two font weight predefined properties: normal(default) and bold.

<Canvas of={Stories.PredefinedFontWeight} withToolbar />

## Custom properties

### Color

Text color can be modified.

<Canvas of={Stories.Color} withToolbar />

### Font Weight

Text font weight can be modified.

<Canvas of={Stories.CustomFontWeight} withToolbar />

### Font Size

Text font size can be modified.

<Canvas of={Stories.FontSize} withToolbar />

### Font Family

Text font family can be modified.

<Canvas of={Stories.FontFamily} withToolbar />

Dele pode se notar que o que vai ter em comum entre os componentes vai ser os imports, a definição de Meta, descrição inicial com nome do componente, Canvas e Controls com cenário default do compoenente, seção de Predefined properties e seção de Custom properties.
Tendo em vista esses pontos, dentro da pasta _templates/component/new vai ser criado o arquivo doc.ejs.t, que vai corresponder a criação do esqueleto da documentação do componente:

---
to: src/components/<%=name%>/<%=name%>.mdx
---
import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./<%=name%>.stories";

<Meta of={Stories} />

# <%=name%>

<%=name%> base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

## Custom properties

Esse template traz os imports necessários e o esqueleto que define a documentação do componente dentro da app, dado os pontos que foram enumerados acima.

Quinto template: export do componente dentro da pasta dele

Para o quinto template, vai ser levado como base o arquivo index.ts dentro da pasta src/components/Text:

export { default } from "./Text";

Dentro da pasta _templates/component/new vai ser criado o arquivo componentIndex.ejs.t, que vai corresponder a criação do export do componente interno a sua pasta:

---
to: src/components/<%=name%>/index.ts
---
export { default } from "./<%=name%>";

Esse template traz o export do componente interno a pasta dele.

Sexto template: export do componente que vai disponibilizar ele para quem adicionar a lib

Para o sexto template, não vai ser considerado um arquivo como base, mas sim vai ser adicionado uma linha a um arquivo já existente dentro da app, que corresponde ao index.ts dentro da pasta src/components:

export { default as Tag } from "./Tag";
export { default as Text } from "./Text";

Dentro da pasta _templates/component/new vai ser criado o arquivo index.ejs.t, que vai corresponder a adição do export do novo componente dentro do arquivo já existente:

---
inject: true
to: src/components/index.ts
at_line: 0
---
export { default as <%=name%> } from "./<%=name%>";

Nele já se tem duas coisas diferentes em relação aos outros arquivos de template. inject: true diz que não vai ser gerado um novo arquivo, mas sim vai ser feita injeção de código dentro de um existente, at_line: 0 diz que vai ser adicionado o código na primeira linha.

Uma vez definido todos os templates, dentro de package.json vai ser definido o script para executar o gerador:

"scripts": {
  //...
  "create-component": "hygen component new"

Nele se define a execução do gerador component usando o hygen.

Exemplo de uso

Para testar o funcionamento do gerador, vai ser executado no terminal:

yarn create-component Button --html button

Nesse comando está se executando o gerador de componente e passando para onde tiver <%=name%> substituir por Button e onde tiver <%=html%> substituir por button.
Ao executar no terminal, ele vai informar que foram gerados cinco arquivos e que teve injeção de código em um arquivo já existente:

Ficando a estrutura do novo componente Button da seguinte forma:

Button.tsx

import React from "react";
import styled from "styled-components";

export interface ButtonProps {
}

export interface StyledButtonProps {
}

export const StyledButton = styled.button<StyledButtonProps>`
`;

const Button = ({
}: ButtonProps) => (
  <StyledButton
  >
  </StyledButton>
);

export default Button;

Button.test.tsx

import React from "react";
import "@testing-library/jest-dom";
import "jest-styled-components";
import { render, screen } from "@testing-library/react";

import Button from "./Button";

describe("<Button />", () => {
  it("should render component with default properties", () => {
  });
});

Button.stories.tsx

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Button from "./Button";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof Button> = {
  title: "Button",
  component: Button,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Button>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Button {...args} />
    </StorybookContainer>
  ),
};

Button.mdx

import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./Button.stories";

<Meta of={Stories} />

# Button

Button base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

## Custom properties

index.ts (interno a pasta src/components/Button)

export { default } from "./Button";

index.ts (interno a pasta src/components)

export { default as Button } from "./Button";
export { default as Tag } from "./Tag";
export { default as Text } from "./Text";

Autogerando dessa forma todos os arquivos que servem de base para a definição de um componente, com os exports definidos também.

package.json

Será mudada a versão dentro de package.json para 0.6.0, uma vez que uma nova versão da lib será disponibilizada:

{
  "name": "react-example-lib",
  "version": "0.6.0",
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/griseduardo/react-example-lib.git"
  },
  "scripts": {
    "build": "rollup -c --bundleConfigAsCjs",
    "lint-src": "eslint src",
    "lint-src-fix": "eslint src --fix",
    "lint-fix": "eslint --fix",
    "format-src": "prettier src --check",
    "format-src-fix": "prettier src --write",
    "format-fix": "prettier --write",
    "test": "jest",
    "prepare": "husky",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build",
    "create-component": "hygen component new"
  },
  "lint-staged": {
    "src/components/**/*.{ts,tsx}": [
      "yarn lint-fix",
      "yarn format-fix"
    ],
    "src/components/**/*.tsx": "yarn test --findRelatedTests --bail"
  },
  "devDependencies": {
    "@babel/core": "^7.26.10",
    "@babel/preset-env": "^7.26.9",
    "@babel/preset-react": "^7.26.3",
    "@babel/preset-typescript": "^7.26.0",
    "@eslint/js": "^9.19.0",
    "@rollup/plugin-commonjs": "^28.0.2",
    "@rollup/plugin-node-resolve": "^16.0.0",
    "@rollup/plugin-terser": "^0.4.4",
    "@rollup/plugin-typescript": "11.1.6",
    "@storybook/addon-essentials": "^8.6.12",
    "@storybook/addon-interactions": "^8.6.12",
    "@storybook/addon-onboarding": "^8.6.12",
    "@storybook/blocks": "^8.6.12",
    "@storybook/builder-vite": "^8.6.12",
    "@storybook/react": "^8.6.12",
    "@storybook/react-vite": "^8.6.12",
    "@storybook/test": "^8.6.12",
    "@testing-library/dom": "^10.4.0",
    "@testing-library/jest-dom": "^6.6.3",
    "@testing-library/react": "^16.2.0",
    "@types/jest": "^29.5.14",
    "@types/react": "^19.0.10",
    "@types/react-dom": "^19.0.4",
    "chromatic": "^12.0.0",
    "eslint": "^9.19.0",
    "eslint-plugin-react": "^7.37.4",
    "eslint-plugin-storybook": "^0.12.0",
    "husky": "^9.1.7",
    "hygen": "^6.2.11",
    "jest": "^29.7.0",
    "jest-environment-jsdom": "^29.7.0",
    "jest-styled-components": "^7.2.0",
    "lint-staged": "^15.5.0",
    "prettier": "^3.4.2",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "rollup": "^4.30.1",
    "rollup-plugin-dts": "^6.1.1",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "storybook": "^8.6.12",
    "styled-components": "^6.1.14",
    "typescript": "^5.7.3",
    "typescript-eslint": "^8.23.0",
    "vite": "^6.3.5"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "styled-components": "^6.1.14"
  },
  "eslintConfig": {
    "extends": [
      "plugin:storybook/recommended"
    ]
  }
}

Arquivo CHANGELOG

Como uma nova versão será disponibilizada, será adicionado em CHANGELOG.md sobre o que foi modificado:

## 0.6.0

_Jun. 30, 2025_

- add hygen
- add component generator

## 0.5.0

_May. 29, 2025_

- change Tag and Text default behavior
- add storybook
- add Tag and Text storybook docs

## 0.4.0

_Abr. 29, 2025_

- setup husky and lint-staged
- define pre-commit actions

## 0.3.0

_Mar. 24, 2025_

- setup jest and testing-library
- add components tests

## 0.2.0

_Fev. 24, 2025_

- setup typescript-eslint and prettier
- add custom rules

## 0.1.0

_Jan. 29, 2025_

- initial config

Estrutura de pastas

A estrutura de pastas ficará da seguinte forma:

Publicação nova versão

Resolvi apagar a pasta Button e remover o export do Button dentro de index.ts (da pasta src/components), uma vez que foi usado para exemplificação do uso do hygen mas não trabalhado o componente em si.
É preciso ver se a execução do rollup ocorre com sucesso antes da publicação. Para isso será executado o yarn build no terminal, que foi definido em package.json.
Executando com sucesso, é realizar a publicação da nova versão da lib: npm publish --access public

Conclusão

A ideia desse artigo foi criar um gerador de componentes dentro da lib, a partir da definição de templates, com o objetivo de agilizar a criação de novos componentes, sendo o gerador responsável pela autogeração do esqueleto de um novo componente.
Segue o repositório no github e a lib no npmjs com as novas modificações.

React and typescript components lib, part 5: documentation of components using storybook

Eduardo Henrique Gris — Thu, 29 May 2025 21:44:14 +0000

Introduction

Portuguese version: Biblioteca de componentes React e typescript, parte 5: documentação de componentes com storybook

In part five, the documentation of the components using storybook will be added, with the aim of demonstrating how the components work and the different possible customizations for them. The idea is to show the practical part of adding storybook in this article and how to perform the documentation. For a reference on how the library works, here is the article I previously wrote as a reference: Documentation of components in React with TypeScript using Storybook (version 8).

Setup

First, the setup will be done with the initial storybook configurations by running the command in the terminal: npx storybook init.
This command will detect the project dependencies and present three steps:

indicate which version of storybook will be added
ask if the project uses webpack or vite
ask if storybook will be used for documentation or testing

Regarding the first point, just proceed. For the second point, the project uses rollup, so in practice, neither option applies directly, but since storybook has no direct integration with rollup, the vite option will be chosen, which will be used to run storybook. For the last question, specify that storybook will be used for documentation.
After finishing the process, libraries that allow running storybook will be automatically added.
At the time of writing this article, it generated the following versions:

"@storybook/addon-essentials": "^8.6.12",
"@storybook/addon-interactions": "^8.6.12",
"@storybook/addon-onboarding": "^8.6.12",
"@storybook/blocks": "^8.6.12",
"@storybook/react": "^8.6.12",
"@storybook/react-vite": "^8.6.12",
"@storybook/test": "^8.6.12",
"eslint-plugin-storybook": "^0.12.0",
"storybook": "^8.6.12",

And in the package.json, two scripts will be automatically added:

"scripts": {
  "storybook": "storybook dev -p 6006",
  "build-storybook": "storybook build"
},

The first script runs storybook locally, and the second builds the storybook.

It will also generate a .storybook folder with two configured files that allow storybook to run: main.ts and preview.ts.
Additionally, a stories folder will be created, which contains some example documentation. Since we won't be using it, this folder will be removed.

With that, storybook is already successfully configured in case the app uses vite. However, since it uses rollup, it will be necessary to add two libraries to allow it to run successfully:

yarn add vite @storybook/builder-vite --dev

At the time of writing this article, the following versions were generated:

"@storybook/builder-vite": "^8.6.12",
"vite": "^6.3.5",

Components modifications

Before continuing with the documentation, the library components will be adapted to define default properties and make adjustments.
Starting with Tag.tsx:

Definition of default props values and removal of textWeight (since there is already a property that allows customizable control of the text's font weight: textFontWeight):

// ...
const Tag = ({
  text = "Tag",
  type = "default",
  textColor = "#fff",
  textFontWeight = 600,
  textFontSize,
  textFontFamily,
  backgroundColor,
  format = "semiRounded",
  borderRadius,
  size = "medium",
  padding,
}: TagProps) => {

Adjustment of the component's type definitions, since textWeight is no longer a props in the component, and the default format is now semiRounded:

// ...
export interface TagProps {
  type?: "default" | "success" | "alert" | "error";
  text: string;
  textColor?: string;
  textFontWeight?: number;
  textFontSize?: string;
  textFontFamily?: string;
  backgroundColor?: string;
  format?: "square" | "semiRounded" | "rounded";
  borderRadius?: string;
  size?: "small" | "medium" | "large";
  padding?: string;
}

export interface StyledTagProps {
  $type?: "default" | "success" | "alert" | "error";
  $textColor?: string;
  $textFontWeight?: number;
  $textFontSize?: string;
  $textFontFamily?: string;
  $backgroundColor?: string;
  $format?: "square" | "semiRounded" | "rounded";
  $borderRadius?: string;
  $size?: "small" | "medium" | "large";
  $padding?: string;
}

Adjustment in the property definitions using styled-components to more clearly take into account the small size, the default type and the square format:

// ...
export const StyledTag = styled.div<StyledTagProps>`
  border: none;
  padding: ${(props) =>
    props.$padding
      ? props.$padding
      : props.$size === "large"
        ? "15px 20px"
        : props.$size === "medium"
          ? "10px 12px"
          : props.$size === "small" && "7px"};
  background-color: ${(props) =>
    props.$backgroundColor
      ? props.$backgroundColor
      : props.$type === "error"
        ? "#e97451"
        : props.$type === "alert"
          ? "#f8de7e"
          : props.$type === "success"
            ? "#50c878"
            : props.$type === "default" && "#d3d3d3"};
  pointer-events: none;
  border-radius: ${(props) =>
    props.$borderRadius
      ? props.$borderRadius
      : props.$format === "rounded"
        ? "30px"
        : props.$format === "semiRounded"
          ? "5px"
          : props.$format === "square" && "0"};
  width: fit-content;
`;

Adjustment in the component's rendering, setting the text font size based on the textFontSize props or the size props:

// ...
}: TagProps) => {
  const fontSize = textFontSize
    ? textFontSize
    : size === "large"
      ? "18px"
      : size === "small"
        ? "14px"
        : "16px";

  return (
    <StyledTag
      data-testid="tag"
      $type={type}
      $backgroundColor={backgroundColor}
      $format={format}
      $borderRadius={borderRadius}
      $size={size}
      $padding={padding}
    >
      <Text
        color={textColor}
        fontWeight={textFontWeight}
        fontSize={fontSize}
        fontFamily={textFontFamily}
      >
        {text}
      </Text>
    </StyledTag>
  );
};

Since the default properties of the Tag component were changed, it will be necessary to update its test file Tag.test.tsx:

Adjustment of the expect statements in the first test to validate the default properties:

it("should render component with default properties", () => {
  render(<Tag text="Tag" />);

  const element = screen.getByTestId("tag");

  expect(element).toBeInTheDocument();
  expect(element).toHaveStyleRule("background-color", "#d3d3d3");
  expect(element).toHaveStyleRule("border-radius", "0");
  expect(element).toHaveStyleRule("padding", "7px");    
  expect(within(element).getByText("Tag")).toHaveStyleRule("color", "#fff");
});

Removal of the test should render component with bold text font weight, since the props it relied on was removed.

Now regarding Text.tsx:

Definition of default prop values:

// ...
const Text = ({
  children,
  color="#000",
  weight="normal",
  fontWeight,
  fontSize="16px",
  fontFamily,
}: TextProps) => (

Adjustment in the property definitions using styled-components, so that in some cases the property is only set if the related props is provided:

// ...
export const StyledText = styled.span<StyledTextProps>`
  ${(props) => props.$color && `color: ${props.$color};`}
  ${(props) => props.$fontSize && `font-size: ${props.$fontSize};`}
  font-weight: ${(props) =>
    props.$fontWeight
      ? props.$fontWeight
      : props.$weight
        ? props.$weight
        : "normal"};
  ${(props) => props.$fontFamily && `font-family: ${props.$fontFamily};`}
`;

Components documentation

For the component documentation, two types of files will be created for each component:

stories: where the customization scenarios to be shown in the documentation will be defined
mdx: the component documentation, where the texts will be written and the scenarios from the stories file will be embedded

Before moving on to the documentation, a component will be created to centralize the components rendered in the documentation and add a small space between them. A folder named StorybookContainer will be created inside src/components:

file StorybookContainer.tsx:

import React from "react";
import styled from "styled-components";

export interface StorybookContainerProps {
  children: React.ReactNode;
}

export const StyledStorybookContainer = styled.div`
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 10px;
`;

const StorybookContainer = ({ children }: StorybookContainerProps) => (
  <StyledStorybookContainer>
    {children}
  </StyledStorybookContainer>
);

export default StorybookContainer;

file index.ts:

export { default } from "./StorybookContainer";

Now, we can start documenting the Tag component by creating the following file inside the folder src/components/Tag:

Tag.stories.tsx

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Tag from "./Tag";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof Tag> = {
  title: "Tag",
  component: Tag,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Tag>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
    </StorybookContainer>
  ),
};

export const PredefinedType: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} type="success" />
      <Tag {...args} type="alert" />
      <Tag {...args} type="error" />
    </StorybookContainer>
  ),
};

export const PredefinedFormat: Story = {
  args: {
    format: "square",
  },
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} format="semiRounded" />
      <Tag {...args} format="rounded" />
    </StorybookContainer>
  ),
};

export const PredefinedSize: Story = {
  args: {
    size: "small",
  },
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} size="medium" />
      <Tag {...args} size="large" />
    </StorybookContainer>
  ),
};

export const Text: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} text="Example" />
    </StorybookContainer>
  ),
};

export const BackgroundColor: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} backgroundColor="#3b82f6" />
    </StorybookContainer>
  ),
};

export const CustomFormat: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} borderRadius="15px 2px" />
    </StorybookContainer>
  ),
};

export const CustomSize: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} padding="20px 40px" />
    </StorybookContainer>
  ),
};

export const TextColor: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} textColor="#000" />
    </StorybookContainer>
  ),
};

export const TextFontWeight: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} textFontWeight={100} />
    </StorybookContainer>
  ),
};

export const TextFontFamily: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} textFontFamily="Arial" />
    </StorybookContainer>
  ),
};

export const TextFontSize: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} textFontSize="20px" />
    </StorybookContainer>
  ),
};

In it, under Meta, the component being documented is defined, along with the title that will appear in storybook’s sidebar menu. Each export const defines a scenario that will be included in the documentation. Citing two example scenarios, the first Default will render the component with its default props. The second PredefinedType will show how the component behaves with variations of the type props.

Tag.mdx

import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./Tag.stories";

<Meta of={Stories} />

# Tag

Tag base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

### Type

There are four type predefined properties: default, success, alert and error.

<Canvas of={Stories.PredefinedType} withToolbar />

### Format

There are three format predefined properties: square, semiRounded (default) and rounded.

<Canvas of={Stories.PredefinedFormat} withToolbar />

### Size

There are three size predefined properties: small, medium (default) and large.

<Canvas of={Stories.PredefinedSize} withToolbar />

## Custom properties

### Text

Tag text can be modified.

<Canvas of={Stories.Text} withToolbar />

### Background Color

Tag background color can be modified.

<Canvas of={Stories.BackgroundColor} withToolbar />

### Format

Tag format can be modified by border radius definition.

<Canvas of={Stories.CustomFormat} withToolbar />

### Size

Tag size can be modified by padding definition.

<Canvas of={Stories.CustomSize} withToolbar />

### Text Color

Tag text color can be modified.

<Canvas of={Stories.TextColor} withToolbar />

### Text Font Weight

Tag text font weight can be modified.

<Canvas of={Stories.TextFontWeight} withToolbar />

### Text Font Family

Tag text font family can be modified.

<Canvas of={Stories.TextFontFamily} withToolbar />

### Text Font Size

Tag text font size can be modified.

<Canvas of={Stories.TextFontSize} withToolbar />

In the file above, <Canvas of={Stories.Default} withToolbar /> renders the component using its Default scenario. Just below, <Controls of={Stories.Default} /> displays a table with all the component’s props available for customization. By adjusting these props, it's possible to see in real time how they impact the component above the table.
In Predefined properties, scenarios are shown where, based on modified props, the app itself defines the associated css.
In Custom properties, scenarios are shown where the modified props directly affect the defined css.

Running storybook locally with yarn storybook:

Now, the documentation for the Text component will be created, by adding the following file inside the folder src/components/Text:

Text.stories.tsx

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Text from "./Text";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof Text> = {
  title: "Text",
  component: Text,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Text>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
    </StorybookContainer>
  ),
};

export const PredefinedFontWeight: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} weight="bold">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const Color: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} color="#800080">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const CustomFontWeight: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontWeight={900}>
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const FontSize: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontSize="30px">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const FontFamily: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontFamily="Arial">
        Text
      </Text>
    </StorybookContainer>
  ),
};

Text.mdx

import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./Text.stories";

<Meta of={Stories} />

# Text

Text base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

### Font Weight

There are two font weight predefined properties: normal(default) and bold.

<Canvas of={Stories.PredefinedFontWeight} withToolbar />

## Custom properties

### Color

Text color can be modified.

<Canvas of={Stories.Color} withToolbar />

### Font Weight

Text font weight can be modified.

<Canvas of={Stories.CustomFontWeight} withToolbar />

### Font Size

Text font size can be modified.

<Canvas of={Stories.FontSize} withToolbar />

### Font Family

Text font family can be modified.

<Canvas of={Stories.FontFamily} withToolbar />

It will look as follows:

Deploy storybook

Now we have both components documented and storybook running successfully locally. But the goal is not for the documentation to be used only by those developing the library - it should be available to showcase the components the library offers to those considering adding it. To achieve this, chromatic will be used to deploy the documentation and make it accessible, that is a publishing service made by the storybook maintainers. First, the library will be added:

yarn add chromatic --dev

At the time of writing this article, it generated the following version:

"chromatic": "^12.0.0",

Now, follow these steps to deploy:

Go to the sign-up page
Select Connect with GitHub (assuming your repository is hosted there)
After signing up, choose Choose GitHub repo
Select the repository for your library from your github account.
Copy and save the command shown under Publish your Storybook. At this point, you can’t proceed without running this command in the terminal, but before that, let's build storybook
In the terminal, run yarn build-storybook
Then, in the terminal, run the command provided by chromatic (every time you need to deploy, this exact command must be executed after building)

Once the process completes successfully, the terminal will confirm that storybook was published and will display a url under View your Storybook at "url".
By visiting this url, you’ll be able to see the component documentation.

README.md

Now that storybook has been published, the url where it is hosted will be added to the app's README (I’ll include my generated URL here, in your case, you should insert yours in that spot):

.gitignore file

In the .gitignore file, the storybook-static folder will be added to be ignored, since it is generated when running yarn build-storybook:

dist
node_modules

*storybook.log
storybook-static

package.json

The version inside package.json will be changed to 0.5.0, since a new version of the library will be released:

{
  "name": "react-example-lib",
  "version": "0.5.0",
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/griseduardo/react-example-lib.git"
  },
  "scripts": {
    "build": "rollup -c --bundleConfigAsCjs",
    "lint-src": "eslint src",
    "lint-src-fix": "eslint src --fix",
    "lint-fix": "eslint --fix",
    "format-src": "prettier src --check",
    "format-src-fix": "prettier src --write",
    "format-fix": "prettier --write",
    "test": "jest",
    "prepare": "husky",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  },
  "lint-staged": {
    "src/components/**/*.{ts,tsx}": [
      "yarn lint-fix",
      "yarn format-fix"
    ],
    "src/components/**/*.tsx": "yarn test --findRelatedTests --bail"
  },
  "devDependencies": {
    "@babel/core": "^7.26.10",
    "@babel/preset-env": "^7.26.9",
    "@babel/preset-react": "^7.26.3",
    "@babel/preset-typescript": "^7.26.0",
    "@eslint/js": "^9.19.0",
    "@rollup/plugin-commonjs": "^28.0.2",
    "@rollup/plugin-node-resolve": "^16.0.0",
    "@rollup/plugin-terser": "^0.4.4",
    "@rollup/plugin-typescript": "11.1.6",
    "@storybook/addon-essentials": "^8.6.12",
    "@storybook/addon-interactions": "^8.6.12",
    "@storybook/addon-onboarding": "^8.6.12",
    "@storybook/blocks": "^8.6.12",
    "@storybook/builder-vite": "^8.6.12",
    "@storybook/react": "^8.6.12",
    "@storybook/react-vite": "^8.6.12",
    "@storybook/test": "^8.6.12",
    "@testing-library/dom": "^10.4.0",
    "@testing-library/jest-dom": "^6.6.3",
    "@testing-library/react": "^16.2.0",
    "@types/jest": "^29.5.14",
    "@types/react": "^19.0.10",
    "@types/react-dom": "^19.0.4",
    "chromatic": "^12.0.0",
    "eslint": "^9.19.0",
    "eslint-plugin-react": "^7.37.4",
    "eslint-plugin-storybook": "^0.12.0",
    "husky": "^9.1.7",
    "jest": "^29.7.0",
    "jest-environment-jsdom": "^29.7.0",
    "jest-styled-components": "^7.2.0",
    "lint-staged": "^15.5.0",
    "prettier": "^3.4.2",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "rollup": "^4.30.1",
    "rollup-plugin-dts": "^6.1.1",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "storybook": "^8.6.12",
    "styled-components": "^6.1.14",
    "typescript": "^5.7.3",
    "typescript-eslint": "^8.23.0",
    "vite": "^6.3.5"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "styled-components": "^6.1.14"
  },
  "eslintConfig": {
    "extends": [
      "plugin:storybook/recommended"
    ]
  }
}

CHANGELOG file

Since a new version will be released, the CHANGELOG.md will be updated with what has been changed:

## 0.5.0

_May. 29, 2025_

- change Tag and Text default behavior
- add storybook
- add Tag and Text storybook docs

## 0.4.0

_Abr. 29, 2025_

- setup husky and lint-staged
- define pre-commit actions

## 0.3.0

_Mar. 24, 2025_

- setup jest and testing-library
- add components tests

## 0.2.0

_Fev. 24, 2025_

- setup typescript-eslint and prettier
- add custom rules

## 0.1.0

_Jan. 29, 2025_

- initial config

Folders structure

The folder structure will be as follows:

Publication of a new version

The first step is to check if the rollup build runs successfully. To do this, run yarn build in the terminal, as defined in package.json. If the build is successful, proceed to publish the new version of the library with: npm publish --access public

Conclusion

The purpose of this article was to set up storybook, create documentation for the components in the app and deploy it, since documentation is important to showcase the components the library provides. Here is the repository on github and the library on npmjs with the new modifications.

Biblioteca de componentes React e typescript, parte 5: documentação de componentes com storybook

Eduardo Henrique Gris — Thu, 29 May 2025 21:43:50 +0000

Introdução

English version: React and typescript components lib, part 5: documentation of components using storybook

Na parte cinco, será adicionada a documentação dos componentes usando storybook, com o objetivo de mostrar a partir dela como funciona os componentes e as diferentes customizações possíveis para eles. A ideia é mostrar a parte prática da adição do storybook nesse artigo e como realizar a documentação, para uma referência de como funciona a lib segue o artigo que escrevi anteriormente de referência: Documentação de componentes em React com Typescript usando Storybook (versão 8).

Setup

Primeiro será realizado o setup com as configurações inicias do storybook, a partir da execução no terminal: npx storybook init.
Esse comando vai detectar as dependências do projeto e apresentar três passos:

informar qual versão do storybook vai ser adicionada
perguntar se o projeto usa webpack ou vite
perguntar se vai usar o storybook para documentação ou teste

Quanto ao primeiro ponto é só prosseguir. Do segundo ponto, o projeto usa rollup, então não seria na prática nenhuma das duas opções, mas como o storybook não tem integração direta com rollup, será escolhida a opção vite, que vai ser utilizado para rodar o storybook. Da última pergunta, é informar que vai ser usado para documentação.
Ao finalizar o processo vão ser adicionadas automaticamente libs que permitirão executar o storybook.
No momento desse artigo gerou as seguintes versões:

"@storybook/addon-essentials": "^8.6.12",
"@storybook/addon-interactions": "^8.6.12",
"@storybook/addon-onboarding": "^8.6.12",
"@storybook/blocks": "^8.6.12",
"@storybook/react": "^8.6.12",
"@storybook/react-vite": "^8.6.12",
"@storybook/test": "^8.6.12",
"eslint-plugin-storybook": "^0.12.0",
"storybook": "^8.6.12",

E em package.json serão adicionados automaticamente dois scripts:

"scripts": {
  "storybook": "storybook dev -p 6006",
  "build-storybook": "storybook build"
},

O primeiro executa o storybook localmente, o segundo faz o build do storybook.

E vai gerar uma pasta .storybook, com dois arquivos configurados para permitir a execução do storybook: main.ts e preview.ts.
Além de uma pasta stories, que possui alguns exemplos de documentação prontos, mas como não vamos utilizar vai ser removida essa pasta.

Dessa forma estava já configurado com sucesso o storybook caso a app utilizasse o vite. Mas como utiliza rollup vai ser necessária adicionar duas libs para permitir a execução com sucesso:

yarn add vite @storybook/builder-vite --dev

No momento desse artigo gerou as seguintes versões:

"@storybook/builder-vite": "^8.6.12",
"vite": "^6.3.5"

Modificação componentes

Antes de seguir com a documentação, vai ser adaptado os componentes da lib para definição das propriedades default e ajustes.
Começando pelo Tag.tsx:

Definição dos valores de props default e remoção de textWeight (pois já tem uma propriedade que permite mexer de forma customizável com o font weight do texto: textFontWeight):

// ...
const Tag = ({
  text = "Tag",
  type = "default",
  textColor = "#fff",
  textFontWeight = 600,
  textFontSize,
  textFontFamily,
  backgroundColor,
  format = "semiRounded",
  borderRadius,
  size = "medium",
  padding,
}: TagProps) => {

Ajuste da definição de types do componente, uma vez que textWeight não é mais uma props presente no componente e que o format default agora é semiRounded:

// ...
export interface TagProps {
  type?: "default" | "success" | "alert" | "error";
  text: string;
  textColor?: string;
  textFontWeight?: number;
  textFontSize?: string;
  textFontFamily?: string;
  backgroundColor?: string;
  format?: "square" | "semiRounded" | "rounded";
  borderRadius?: string;
  size?: "small" | "medium" | "large";
  padding?: string;
}

export interface StyledTagProps {
  $type?: "default" | "success" | "alert" | "error";
  $textColor?: string;
  $textFontWeight?: number;
  $textFontSize?: string;
  $textFontFamily?: string;
  $backgroundColor?: string;
  $format?: "square" | "semiRounded" | "rounded";
  $borderRadius?: string;
  $size?: "small" | "medium" | "large";
  $padding?: string;
}

Ajuste na definição de propriedades a partir do styled-components para levar em consideração de forma mais clara o size small, o type default e o format square:

// ...
export const StyledTag = styled.div<StyledTagProps>`
  border: none;
  padding: ${(props) =>
    props.$padding
      ? props.$padding
      : props.$size === "large"
        ? "15px 20px"
        : props.$size === "medium"
          ? "10px 12px"
          : props.$size === "small" && "7px"};
  background-color: ${(props) =>
    props.$backgroundColor
      ? props.$backgroundColor
      : props.$type === "error"
        ? "#e97451"
        : props.$type === "alert"
          ? "#f8de7e"
          : props.$type === "success"
            ? "#50c878"
            : props.$type === "default" && "#d3d3d3"};
  pointer-events: none;
  border-radius: ${(props) =>
    props.$borderRadius
      ? props.$borderRadius
      : props.$format === "rounded"
        ? "30px"
        : props.$format === "semiRounded"
          ? "5px"
          : props.$format === "square" && "0"};
  width: fit-content;
`;

Ajuste na renderização do componente, definindo o font size do texto com base na props textFontSize ou size:

// ...
}: TagProps) => {
  const fontSize = textFontSize
    ? textFontSize
    : size === "large"
      ? "18px"
      : size === "small"
        ? "14px"
        : "16px";

  return (
    <StyledTag
      data-testid="tag"
      $type={type}
      $backgroundColor={backgroundColor}
      $format={format}
      $borderRadius={borderRadius}
      $size={size}
      $padding={padding}
    >
      <Text
        color={textColor}
        fontWeight={textFontWeight}
        fontSize={fontSize}
        fontFamily={textFontFamily}
      >
        {text}
      </Text>
    </StyledTag>
  );
};

Como foi mexida nas propriedades default do componente de Tag, vai ser necessário mexer no arquivo de teste dele Tag.test.tsx:

Ajuste dos expect do primeiro teste para validar as propriedades default:

it("should render component with default properties", () => {
  render(<Tag text="Tag" />);

  const element = screen.getByTestId("tag");

  expect(element).toBeInTheDocument();
  expect(element).toHaveStyleRule("background-color", "#d3d3d3");
  expect(element).toHaveStyleRule("border-radius", "0");
  expect(element).toHaveStyleRule("padding", "7px");    
  expect(within(element).getByText("Tag")).toHaveStyleRule("color", "#fff");
});

Remoção do teste should render component with bold text font weight, uma vez que a props que ele considerava foi removida.

Agora referente a Text.tsx:

Definição dos valores de props default:

// ...
const Text = ({
  children,
  color="#000",
  weight="normal",
  fontWeight,
  fontSize="16px",
  fontFamily,
}: TextProps) => (

Ajuste na definição de propriedades a partir do styled-components, para em algumas situações só definir a propriedade se chegar a props relacionada:

// ...
export const StyledText = styled.span<StyledTextProps>`
  ${(props) => props.$color && `color: ${props.$color};`}
  ${(props) => props.$fontSize && `font-size: ${props.$fontSize};`}
  font-weight: ${(props) =>
    props.$fontWeight
      ? props.$fontWeight
      : props.$weight
        ? props.$weight
        : "normal"};
  ${(props) => props.$fontFamily && `font-family: ${props.$fontFamily};`}
`;

Documentação dos componentes

Para a documentação dos componentes, vão ser criados dois tipos de arquivos para cada um deles:

stories: onde será definido os cenários de customização a serem mostrados na documentação
mdx: a documentação do componente, onde vão ser definidos os textos e incorporado os cenários presentes no arquivo de stories

Antes de partir para a documentação, será criado um componente responsável por centralizar os componentes renderizados na documentação e colocar um pequeno espaço entre eles, criando uma pasta StorybookContainer dentro de src/components:

arquivo StorybookContainer.tsx:

import React from "react";
import styled from "styled-components";

export interface StorybookContainerProps {
  children: React.ReactNode;
}

export const StyledStorybookContainer = styled.div`
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 10px;
`;

const StorybookContainer = ({ children }: StorybookContainerProps) => (
  <StyledStorybookContainer>
    {children}
  </StyledStorybookContainer>
);

export default StorybookContainer;

arquivo index.ts:

export { default } from "./StorybookContainer";

Agora, podemos começar com a documentação do componente de Tag, criando dentro da pasta src/components/Tag:

Tag.stories.tsx

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Tag from "./Tag";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof Tag> = {
  title: "Tag",
  component: Tag,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Tag>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
    </StorybookContainer>
  ),
};

export const PredefinedType: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} type="success" />
      <Tag {...args} type="alert" />
      <Tag {...args} type="error" />
    </StorybookContainer>
  ),
};

export const PredefinedFormat: Story = {
  args: {
    format: "square",
  },
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} format="semiRounded" />
      <Tag {...args} format="rounded" />
    </StorybookContainer>
  ),
};

export const PredefinedSize: Story = {
  args: {
    size: "small",
  },
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} size="medium" />
      <Tag {...args} size="large" />
    </StorybookContainer>
  ),
};

export const Text: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} text="Example" />
    </StorybookContainer>
  ),
};

export const BackgroundColor: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} backgroundColor="#3b82f6" />
    </StorybookContainer>
  ),
};

export const CustomFormat: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} borderRadius="15px 2px" />
    </StorybookContainer>
  ),
};

export const CustomSize: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} padding="20px 40px" />
    </StorybookContainer>
  ),
};

export const TextColor: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} textColor="#000" />
    </StorybookContainer>
  ),
};

export const TextFontWeight: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} textFontWeight={100} />
    </StorybookContainer>
  ),
};

export const TextFontFamily: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} textFontFamily="Arial" />
    </StorybookContainer>
  ),
};

export const TextFontSize: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} textFontSize="20px" />
    </StorybookContainer>
  ),
};

Nele em Meta é definido o componente que está sendo documentado e o título que vai aparecer no menu lateral do storybook. Em cada export const é definido um cenário que estará presente na documentação. Citando dois exemplos de cenário, o primeiro Default vai trazer o componente com as propriedades default dele, o segundo PredefinedType vai mostrar como o componente se comporta com a variação da props type.

Tag.mdx

import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./Tag.stories";

<Meta of={Stories} />

# Tag

Tag base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

### Type

There are four type predefined properties: default, success, alert and error.

<Canvas of={Stories.PredefinedType} withToolbar />

### Format

There are three format predefined properties: square, semiRounded (default) and rounded.

<Canvas of={Stories.PredefinedFormat} withToolbar />

### Size

There are three size predefined properties: small, medium (default) and large.

<Canvas of={Stories.PredefinedSize} withToolbar />

## Custom properties

### Text

Tag text can be modified.

<Canvas of={Stories.Text} withToolbar />

### Background Color

Tag background color can be modified.

<Canvas of={Stories.BackgroundColor} withToolbar />

### Format

Tag format can be modified by border radius definition.

<Canvas of={Stories.CustomFormat} withToolbar />

### Size

Tag size can be modified by padding definition.

<Canvas of={Stories.CustomSize} withToolbar />

### Text Color

Tag text color can be modified.

<Canvas of={Stories.TextColor} withToolbar />

### Text Font Weight

Tag text font weight can be modified.

<Canvas of={Stories.TextFontWeight} withToolbar />

### Text Font Family

Tag text font family can be modified.

<Canvas of={Stories.TextFontFamily} withToolbar />

### Text Font Size

Tag text font size can be modified.

<Canvas of={Stories.TextFontSize} withToolbar />

No arquivo acima, em <Canvas of={Stories.Default} withToolbar /> é renderizado o componente com o cenário Default dele. Logo abaixo em <Controls of={Stories.Default} /> é renderizada uma tabela com todas as props do componente disponíveis para customização, permitindo que ao mexer nessas props seja possível ver em tempo real o impacto no componente acima da tabela.
Em Predefined properties são mostrados os cenários em que, com base nas props modificadas, a própria app define o css associado.
Em Custom properties são mostrados os cenários em que as props modificadas impactam diretamente no css definido.

Rodando localmente o storybook com yarn storybook:

Agora, será realizada a documentação do componente de Text, criando dentro da pasta src/components/Text:

Text.stories.tsx

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Text from "./Text";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof Text> = {
  title: "Text",
  component: Text,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Text>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
    </StorybookContainer>
  ),
};

export const PredefinedFontWeight: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} weight="bold">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const Color: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} color="#800080">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const CustomFontWeight: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontWeight={900}>
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const FontSize: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontSize="30px">
        Text
      </Text>
    </StorybookContainer>
  ),
};

export const FontFamily: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Text {...args}>Text</Text>
      <Text {...args} fontFamily="Arial">
        Text
      </Text>
    </StorybookContainer>
  ),
};

Text.mdx

import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./Text.stories";

<Meta of={Stories} />

# Text

Text base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

### Font Weight

There are two font weight predefined properties: normal(default) and bold.

<Canvas of={Stories.PredefinedFontWeight} withToolbar />

## Custom properties

### Color

Text color can be modified.

<Canvas of={Stories.Color} withToolbar />

### Font Weight

Text font weight can be modified.

<Canvas of={Stories.CustomFontWeight} withToolbar />

### Font Size

Text font size can be modified.

<Canvas of={Stories.FontSize} withToolbar />

### Font Family

Text font family can be modified.

<Canvas of={Stories.FontFamily} withToolbar />

Ficando da seguinte forma:

Deploy storybook

Agora temos os dois componentes documentados e rodando com sucesso o storybook localmente. Mas a ideia não é a documentação ser para uso de quem está desenvolvendo a lib, mas sim estar disponível para mostrar os componentes que a lib oferece para quem está pensando em adicionar ela. Para isso vai ser usado o chromatic para fazer o deploy da documentação e disponibilizar ela, que é um serviço de publicação criado pelos responsáveis do storybook.
Primeiro será adicionada a lib:

yarn add chromatic --dev

No momento desse artigo gerou a seguinte versão:

"chromatic": "^12.0.0",

Agora será necessário seguir os seguintes passos para realizar o deploy:

Acessar página de cadastro
Selecionar Connect with GitHub para acessar (assumindo que seu repositório está lá)
Depois do cadastro, selecionar Choose GitHub repo
Selecionar o repositório da lib presente no seu github
Copiar e guardar o comando presente em Publish your Storybook, nesse ponto não dá para seguir sem executar no terminal o comando, mas antes vamos fazer o build do storybook
No terminal executar yarn build-storybook
Depois no terminal executar o comando passado na página do chromatic (toda vez que precisar fazer o deploy, esse exato comando precisará ser executado depois do build)

Por fim executando com sucesso, vai avisar no terminal que o storybook foi publicado com sucesso e passado a url onde é possível acessar ele em View your Storybook at "url".
Acessando a url vai ser possível ver a documentação dos componentes.

README.md

Agora que o storybook foi publicado, no README da app vai ser passada a url em que ele se encontra (aqui vou colocar a minha url gerada, no seu caso seria colocar a sua lá):

Arquivo .gitignore

No arquivo .gitignore será colocado para ignorar a pasta storybook-static, que é gerada quando se executa o yarn build-storybook:

dist
node_modules

*storybook.log
storybook-static

package.json

Será mudada a versão dentro de package.json para 0.5.0, uma vez que uma nova versão da lib será disponibilizada:

{
  "name": "react-example-lib",
  "version": "0.5.0",
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/griseduardo/react-example-lib.git"
  },
  "scripts": {
    "build": "rollup -c --bundleConfigAsCjs",
    "lint-src": "eslint src",
    "lint-src-fix": "eslint src --fix",
    "lint-fix": "eslint --fix",
    "format-src": "prettier src --check",
    "format-src-fix": "prettier src --write",
    "format-fix": "prettier --write",
    "test": "jest",
    "prepare": "husky",
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
  },
  "lint-staged": {
    "src/components/**/*.{ts,tsx}": [
      "yarn lint-fix",
      "yarn format-fix"
    ],
    "src/components/**/*.tsx": "yarn test --findRelatedTests --bail"
  },
  "devDependencies": {
    "@babel/core": "^7.26.10",
    "@babel/preset-env": "^7.26.9",
    "@babel/preset-react": "^7.26.3",
    "@babel/preset-typescript": "^7.26.0",
    "@eslint/js": "^9.19.0",
    "@rollup/plugin-commonjs": "^28.0.2",
    "@rollup/plugin-node-resolve": "^16.0.0",
    "@rollup/plugin-terser": "^0.4.4",
    "@rollup/plugin-typescript": "11.1.6",
    "@storybook/addon-essentials": "^8.6.12",
    "@storybook/addon-interactions": "^8.6.12",
    "@storybook/addon-onboarding": "^8.6.12",
    "@storybook/blocks": "^8.6.12",
    "@storybook/builder-vite": "^8.6.12",
    "@storybook/react": "^8.6.12",
    "@storybook/react-vite": "^8.6.12",
    "@storybook/test": "^8.6.12",
    "@testing-library/dom": "^10.4.0",
    "@testing-library/jest-dom": "^6.6.3",
    "@testing-library/react": "^16.2.0",
    "@types/jest": "^29.5.14",
    "@types/react": "^19.0.10",
    "@types/react-dom": "^19.0.4",
    "chromatic": "^12.0.0",
    "eslint": "^9.19.0",
    "eslint-plugin-react": "^7.37.4",
    "eslint-plugin-storybook": "^0.12.0",
    "husky": "^9.1.7",
    "jest": "^29.7.0",
    "jest-environment-jsdom": "^29.7.0",
    "jest-styled-components": "^7.2.0",
    "lint-staged": "^15.5.0",
    "prettier": "^3.4.2",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "rollup": "^4.30.1",
    "rollup-plugin-dts": "^6.1.1",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "storybook": "^8.6.12",
    "styled-components": "^6.1.14",
    "typescript": "^5.7.3",
    "typescript-eslint": "^8.23.0",
    "vite": "^6.3.5"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "styled-components": "^6.1.14"
  },
  "eslintConfig": {
    "extends": [
      "plugin:storybook/recommended"
    ]
  }
}

Arquivo CHANGELOG

Como uma nova versão será disponibilizada, será adicionado em CHANGELOG.md sobre o que foi modificado:

## 0.5.0

_May. 29, 2025_

- change Tag and Text default behavior
- add storybook
- add Tag and Text storybook docs

## 0.4.0

_Abr. 29, 2025_

- setup husky and lint-staged
- define pre-commit actions

## 0.3.0

_Mar. 24, 2025_

- setup jest and testing-library
- add components tests

## 0.2.0

_Fev. 24, 2025_

- setup typescript-eslint and prettier
- add custom rules

## 0.1.0

_Jan. 29, 2025_

- initial config

Estrutura de pastas

A estrutura de pastas ficará da seguinte forma:

Publicação nova versão

Primeiro passo a ser realizado é ver se a execução do rollup ocorre com sucesso. Para isso será executado o yarn build no terminal, que foi definido em package.json.
Executando com sucesso, é realizar a publicação da nova versão da lib: npm publish --access public

Conclusão

A ideia desse artigo foi fazer o setup do storybook, criar a documentação dos componentes presentes na app e fazer o deploy dela, uma vez que a documentação é importante para mostrar os componentes que a lib está disponibilizando.
Segue o repositório no github e a lib no npmjs com as novas modificações.

Documentation of components in React with TypeScript using Storybook (version 8)

Eduardo Henrique Gris — Fri, 16 May 2025 21:30:21 +0000

Introduction

Portuguese version: Documentação de componentes em React com Typescript usando Storybook (versão 8)

Previously, I wrote an article about components documentation using storybook when the version was below 8. Due to some changes introduced in version 8 and my deeper understanding of the library, I’m now writing an updated version in this article.
Storybook is a lib that allows, among other things, the documentation of components in isolation, parallel to the application.
In this article, I will present a way to customize component documentation. I hope this will help bring visibility to some of the options available when using this library. The following steps will be followed:

setup: storybook configuration
stories: definition of the main scenarios for the components to be documented
mdx: documentation of the components, incorporating the customizations defined in the stories
example: an example of component documentation will be presented

Each component will have its own mdx and stories file.

Setup

To add storybook to a React application with the initial configurations, you need to run the following command in the terminal: npx storybook init.
This command will detect the project’s dependencies and may ask some questions during the process. Some examples:

whether you're using webpack or vite in the project
whether it's for documentation or testing

In this case, choose the option that corresponds to your project, and for documentation, specify that when prompted.
Note: some libraries use rollup instead of vite or webpack. In a library I use for learning, which uses rollup, I chose the vite option and it works fine, but you need to add two additional libraries:

yarn add vite @storybook/builder-vite --dev

Stories

For each component, a *.stories.tsx file will be created, where the most important customization scenarios to be documented will be defined, following this structure:

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Component from "./Component";

const meta: Meta<typeof Component> = {
  title: "Component",
  component: Component,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Component>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <Component {...args} />
  ),
};

export const Scenario1: Story = {
  args: {},
  render: (args) => (
    <>
      <Component {...args} />
      <Component {...args} props1="option1" />
      <Component {...args} props1="option2" />
    </>
  ),
};

// Scenario2
// Scenario3

From the imports of @storybook/react:

Meta: define the metadata for the component to be documented. In this case, the component itself is passed in component, and the title that will appear in the sidebar is specified in title
StoryObj: allows you to define the customization scenarios of the component to be displayed in the documentation, corresponding to the definitions of Default, Scenario1, Scenario2... mentioned above

For each defined scenario, an entry will be created in the sidebar, within the "folder" named according to the title defined in the Meta, with the following structure:

Component
- Default
- Scenario 1
- Scenario 2
- Scenario 3

In Default, the component is rendered with its default properties.
In the args: {} of Scenario1 above, no props were passed in, with the goal of showing the component’s base behavior on its initial render using default values.
In the two other renderings inside Scenario1, the props1 prop is varied. The purpose of this scenario is to demonstrate in the documentation what happens to the component when this prop changes.

MDX

It will be the component documentation, where the scenarios present in the *.stories.tsx file will be included, and texts will be defined to explain the main functionalities of the component, following this structure:

import { Canvas, Controls, Meta, Story } from '@storybook/blocks';
import * as Stories from './Component.stories';

<Meta of={Stories} />

# Component

Component description.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

### Scenario 1

Description of the use of props1.

<Canvas of={Stories.Scenario1} withToolbar />

## Custom properties

// ### Scenario 2

// ### Scenario 3

It's a file that mixes markdown with javaScript. From the imports of @storybook/blocks:

Canvas: this will create a box where the components from the scenario defined in the *.stories file will be displayed. It includes an option called Show code that reveals the code to use the displayed component:

Controls: will display a table with the name of all the props available for the component, their descriptions (including the types of the props), whether they have a default value, and a section where you can modify the component's props to see the changes in real time. Putting it all together:

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

This sets up Controls to affect the component coming from Stories.Default. And above, that component is rendered using <Canvas of={Stories.Default} withToolbar />, so with each prop change, you’ll be able to see how the component gets customized in real time:

Meta: defines where the associated stories file for the documentation is located, coming from the import import * as Stories from './Component.stories';

Example

I will present a simple example of documentation based on what has been provided above. Starting with the creation of a component defined in Tag.tsx:

import React from "react";
import styled from "styled-components";

export interface TagProps {
  text?: string;
  backgroundColor?: string;
  type?: "default" | "success" | "alert" | "error";
}

export interface StyledTagProps {
  $backgroundColor?: string;
  $type?: "default" | "success" | "alert" | "error";
}

export const StyledTag = styled.div<StyledTagProps>`
  border: none;
  padding: 10px 12px;
  background-color: ${(props) =>
    props.$backgroundColor
      ? props.$backgroundColor
      : props.$type === "error"
        ? "#e97451"
        : props.$type === "alert"
          ? "#f8de7e"
          : props.$type === "success"
            ? "#50c878"
            : props.$type === "default"
            && "#d3d3d3"};
  pointer-events: none;
  border-radius: 5px;
  width: fit-content;
`;

const Tag = ({
  text="Tag",
  backgroundColor,
  type="default",
}: TagProps) => (
  <StyledTag
    $type={type}
    $backgroundColor={backgroundColor}
  >
    <span>{text}</span>
  </StyledTag>
);

export default Tag;

It is a Tag component with a predefined type property, meaning that the app itself defines the associated css based on the given type. The possible values are default, error, alert and success.
It also has a customizable backgroundColor property, allowing users to choose any color they want.
In the example, the css is defined using a lib called styled-components, but the documentation is indifferent to how the css is defined. Types are defined for both the component's props and the related to styled component.

Now, a specific component for documentation, StorybookContainer, will be created. This component will be responsible for centering the scenario components inside the Canvas of the mdx file, with a small spacement between them. In the file StorybookContainer.tsx:

import React from "react";
import styled from "styled-components";

export interface StorybookContainerProps {
  children: React.ReactNode;
}

export const StyledStorybookContainer = styled.div`
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 10px;
`;

const StorybookContainer = ({ children }: StorybookContainerProps) => (
  <StyledStorybookContainer>
    {children}
  </StyledStorybookContainer>
);

export default StorybookContainer;

The file Tag.stories.tsx will be created with the Default and two scenarios to be presented in the documentation:

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Tag from "./Tag";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof Tag> = {
  title: "Tag",
  component: Tag,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Tag>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
    </StorybookContainer>
  ),
};

export const PredefinedType: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} type="success" />
      <Tag {...args} type="alert" />
      <Tag {...args} type="error" />
    </StorybookContainer>
  ),
};

export const BackgroundColor: Story = {
  args: {
    backgroundColor: "#d3d3d3",
  },
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} backgroundColor="#89cff0" />
      <Tag {...args} backgroundColor="#f0aa89" />
    </StorybookContainer>
  ),
};

Two scenarios were defined in the file to show how the component changes with variations in the type props (which is a predefined property in the app) and how the component changes with variations in the backgroundColor props (which is customizable, as the user can specify any color they want to use).

Finally, the documentation file for the Tag component, Tag.mdx, will be created, where the two scenarios defined in the stories file will be displayed:

import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./Tag.stories";

<Meta of={Stories} />

# Tag

Tag base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

### Type

There are four predefined types: default, success, alert and error.

<Canvas of={Stories.PredefinedType} withToolbar />

## Custom properties

### Background Color

Tag background color can be modified.

<Canvas of={Stories.BackgroundColor} withToolbar />

This is where the component being displayed will be described, along with a table that allows you to control its props, thanks to the inclusion of <Controls />, which appears just above. A customization scenario will be shown by varying the type prop (a predefined property), and another scenario will be shown by varying the backgroundColor prop (a customizable property).

Finally, run yarn storybook in the terminal.
The sidebar will look like this:

And the documentation will look like this:

Conclusion

The idea of this article was to introduce a component documentation lib that allows customizing documentation using an mdx file in various ways, utilizing the blocks provided by the lib. A way for writing this documentation file was presented, but given the many possibilities offered by the lib, I will include some links in the references for those who want to delve deeper into the subject.

References

Stories File
Blocks
Controls Block
Canvas Block
Meta Block
Stories Block
MDX File

Documentação de componentes em React com Typescript usando Storybook (versão 8)

Eduardo Henrique Gris — Fri, 16 May 2025 21:30:13 +0000

Introdução

English version: Documentation of components in React with TypeScript using Storybook (version 8)

Anteriormente escrevi em um artigo sobre a documentação de componentes usando storybook, quando a versão estava abaixo da 8. Devido a algumas mudanças que vieram com essa versão e ter me aprofundado mais com a lib, estou escrevendo uma versão atualizada nesse artigo.
Storybook é uma ferramenta que permite, dentre outras coisas, documentar componentes de forma isolada paralelamente à aplicação.
Nesse artigo, vou apresentar uma forma de customização da documentação de componentes, que espero que auxilie a dar visibilidade a algumas opções dentre várias disponíveis usando essa lib. Será seguido as seguintes etapas:

setup: configuração do storybook
stories: definição dos principais cenários dos componentes a serem documentados
mdx: documentação dos componentes, trazendo as customizações definidas nos stories
exemplo: vai ser apresentado um exemplo de documentação de um componente

Cada componente terá seu próprio arquivo mdx e de stories.

Setup

Para adicionar o storybook em uma aplicação com React, com as configurações iniciais, é necessário executar no terminal: npx storybook init.
Esse comando vai detectar as dependências do projeto e pode apresentar algumas perguntas durante o processo. Alguns exemplos:

se está usando webpack ou vite no projeto
se é para documentação ou testes

No caso seria escolher a que corresponde ao seu projeto e no contexto de documentação, informar isso quando perguntar.
Observação: algumas libs usam o rollup ao invés de vite e webpack, em uma lib que uso para estudo, que usa rollup, escolhi a opção do vite e funciona bem, mas precisa adicionar duas novas libs:

yarn add vite @storybook/builder-vite --dev

Stories

Para cada componente vai ser definido um arquivo *.stories.tsx, onde será definido os cenários de customização mais importantes a serem documentados, seguindo a seguinte estrutura:

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Component from "./Component";

const meta: Meta<typeof Component> = {
  title: "Component",
  component: Component,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Component>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <Component {...args} />
  ),
};

export const Scenario1: Story = {
  args: {},
  render: (args) => (
    <>
      <Component {...args} />
      <Component {...args} props1="option1" />
      <Component {...args} props1="option2" />
    </>
  ),
};

// Scenario2
// Scenario3

Dos imports do @storybook/react:

Meta: define a metadata do componente a ser documentado, nesse caso está se passando o componente em si em component e o título que vai parecer no menu lateral em title
StoryObj: permite definir os cenários de customização do componente a serem exibidos na documentação, que corresponde as definições de Default, Scenario1, Scenario2... acima

Para cada cenário definido, vai ser criado uma entrada no menu lateral, dentro da "pasta" com o nome definido no title de Meta, com a seguinte estrutura:

Component
- Default
- Scenario1
- Scenario2
- Scenario3

Em Default é renderizado o componente com as propriedades default dele.
Em args: {} do Scenario1 acima não foi passado nenhuma props, com o objetivo de trazer na primeira renderização do componente uma base com o comportamento default dele.
Já nas duas outras renderizações do Scenario1 é variada a props props1, onde o objetivo desse cenário é mostrar na documentação o que acontece com o componente ao mudar essa props.

MDX

Vai ser a documentação do componente, onde vai ser trazido os cenários presentes no arquivo de *.stories.tsx e definido textos para explicar as principais funcionalidades do componente, seguindo a seguinte estrutura:

import { Canvas, Controls, Meta, Story } from '@storybook/blocks';
import * as Stories from './Component.stories';

<Meta of={Stories} />

# Component

Descrição do Component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

### Scenario 1

Descrição do uso da props1.

<Canvas of={Stories.Scenario1} withToolbar />

## Custom properties

// ### Scenario 2

// ### Scenario 3

É um arquivo mix de markdown com javascript.
Dos imports do @storybook/blocks:

Canvas: vai criar uma caixa onde os componentes do cenário a ser puxado do arquivo *.stories estarão presentes, que possui uma opção chamada Show code que mostra o código para usar o componente mostrado:

Controls: vai trazer uma tabela com o nome de todas as props disponíveis pelo componente, a descrição delas (trazendo os types das props), se tem um valor default e um lugar onde pode ser mexida as props do componente para visualizar as mudanças que acontecem. Colocando em conjunto:

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

Está se definindo que o Controls vai impactar o componente que vem de Stories.Default e acima está se trazendo ele <Canvas of={Stories.Default} withToolbar />, então a cada mudança de props vai dar para ver como o componente vai sendo customizado:

Meta: define onde está o arquivo de stories associado a documentação, que vem do import import * as Stories from './Component.stories';

Exemplo

Vou apresentar um exemplo simples de documentação partindo do que foi passado acima.
Começando pela criação de um componente definido em Tag.tsx:

import React from "react";
import styled from "styled-components";

export interface TagProps {
  text?: string;
  backgroundColor?: string;
  type?: "default" | "success" | "alert" | "error";
}

export interface StyledTagProps {
  $backgroundColor?: string;
  $type?: "default" | "success" | "alert" | "error";
}

export const StyledTag = styled.div<StyledTagProps>`
  border: none;
  padding: 10px 12px;
  background-color: ${(props) =>
    props.$backgroundColor
      ? props.$backgroundColor
      : props.$type === "error"
        ? "#e97451"
        : props.$type === "alert"
          ? "#f8de7e"
          : props.$type === "success"
            ? "#50c878"
            : props.$type === "default"
            && "#d3d3d3"};
  pointer-events: none;
  border-radius: 5px;
  width: fit-content;
`;

const Tag = ({
  text="Tag",
  backgroundColor,
  type="default",
}: TagProps) => (
  <StyledTag
    $type={type}
    $backgroundColor={backgroundColor}
  >
    <span>{text}</span>
  </StyledTag>
);

export default Tag;

É um componente de Tag que tem uma propriedade predefinida type, ou seja, a própria app define o css associado de acordo com o type passado. Podendo ser default, error, alert e success.
E uma propriedade customizável backgroundColor, ou seja, customizável por quem está usando o componente, podendo escolher a cor que desejar.
No exemplo estou definindo o css a partir de uma lib chamada styled-components, mas a documentação é indiferente a forma que o css é definido.
E é definido os Types tanto das props do componente em si, quanto a referente ao styled component.

Agora será criado um componente específico para documentação StorybookContainer, que será responsável em centralizar dentro do Canvas do arquivo mdx, os componentes do cenário a ser mostrado, com um pequeno espaçamento entre eles. No arquivo StorybookContainer.tsx:

import React from "react";
import styled from "styled-components";

export interface StorybookContainerProps {
  children: React.ReactNode;
}

export const StyledStorybookContainer = styled.div`
  display: flex;
  align-items: center;
  justify-content: center;
  gap: 10px;
`;

const StorybookContainer = ({ children }: StorybookContainerProps) => (
  <StyledStorybookContainer>
    {children}
  </StyledStorybookContainer>
);

export default StorybookContainer;

Vai ser criado o arquivo Tag.stories.tsx com o Default e os dois cenários a serem apresentados na documentação:

import React from "react";
import type { Meta, StoryObj } from "@storybook/react";
import Tag from "./Tag";
import StorybookContainer from "../StorybookContainer/StorybookContainer";

const meta: Meta<typeof Tag> = {
  title: "Tag",
  component: Tag,
  argTypes: {},
};

export default meta;

type Story = StoryObj<typeof Tag>;

export const Default: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
    </StorybookContainer>
  ),
};

export const PredefinedType: Story = {
  args: {},
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} type="success" />
      <Tag {...args} type="alert" />
      <Tag {...args} type="error" />
    </StorybookContainer>
  ),
};

export const BackgroundColor: Story = {
  args: {
    backgroundColor: "#d3d3d3",
  },
  render: (args) => (
    <StorybookContainer>
      <Tag {...args} />
      <Tag {...args} backgroundColor="#89cff0" />
      <Tag {...args} backgroundColor="#f0aa89" />
    </StorybookContainer>
  ),
};

Foram definidos dois cenários no arquivo, para mostrar como o componente muda com a variação da props type (que é uma propriedade pre-definida na app) e como o componente muda com a variação da props backgroundColor (que é uma propriedade customizável, pois o usuário pode passar a cor que quiser usar).

Por fim vai ser criado o arquivo da documentação do componente Tag.mdx, onde vai ser mostrada os dois cenários definidos no arquivo de stories:

import { Canvas, Controls, Meta } from "@storybook/blocks";
import * as Stories from "./Tag.stories";

<Meta of={Stories} />

# Tag

Tag base component.

<Canvas of={Stories.Default} withToolbar />

<Controls of={Stories.Default} />

## Predefined properties

### Type

There are four predefined types: default, success, alert and error.

<Canvas of={Stories.PredefinedType} withToolbar />

## Custom properties

### Background Color

Tag background color can be modified.

<Canvas of={Stories.BackgroundColor} withToolbar />

Onde vai estar descrito o componente que está sendo mostrado, com uma tabela permitindo controlar as prop do componente logo acima dela devido a inclusão do <Controls />, onde vai ser mostrado um cenário de customização usando a variação da props type (propriedade pre-definida) e vai ser mostrado um cenário usando a variação da props backgroundColor (propriedade customizável).

Por fim, é executar no terminal yarn storybook.
Ficando o menu lateral da seguinte forma:

E a documentação da seguinte forma:

Conclusão

A ideia desse artigo foi apresentar uma ferramenta de documentação de componentes que permite customizar a documentação usando um arquivo mdx de diversas formas, a partir de blocks que a lib fornece. Foi apresentado um modo de escrita desse arquivo de documentação, mas dado a várias possibilidades que a lib fornece, vou colocar nas referências alguns links para quem quiser se aprofundar mais no assunto.

Referências

Stories File
Blocks
Controls Block
Canvas Block
Meta Block
Stories Block
MDX File

React and typescript components lib, part 4: pre-commit with Husky and lint-staged

Eduardo Henrique Gris — Tue, 29 Apr 2025 22:55:46 +0000

Introduction

Portuguese version: Biblioteca de componentes React e typescript, parte 4: pré-commit com Husky e lint-staged

In part four, pre-commit actions will be added to the application using two libraries: Husky and lint-staged. The goal is to demonstrate the practical implementation of these tools in this article. As a reference, here is the article Husky and lint-staged for pre-commit in React, which was the first one I wrote on dev.to.

Libs

Husky: is the library that allows pre-commit actions to be executed
lint-staged: is the library that defines which pre-commit actions will be executed and applied specifically to the files staged in git — that is, the files that have been added using git add

Pre-commit action

Pre-commit actions are executed after running git commit in the terminal, but right before the commit is actually finalized.
For the application, three pre-commit actions will be defined:

Format the files staged in git according to the linting rules, right before the commit is finalized
Format the files staged in git according to the prettier rules, right before the commit is finalized
Run the tests related to the modified components that have been staged, to validate that they are passing, right before the commit is finalized

Setup Husky

Adding Husky:

yarn add husky --dev

At the time of writing this article, the following version was generated:

"husky": "^9.1.7"

To configure it, run the following command in the terminal:

npx husky init

This will generate a .husky folder at the root of the project. Inside it, there will be a _ folder containing all available git hooks, although they are not yet configured to run in the project. Outside of the _ folder, there will be a pre-commit file with an initial action already defined. However, since it doesn’t match the application's needs, this file will be modified.
In addition to generating the folder mentioned above, a command will also be added to package.json to install Husky inside the app:

"scripts": {
  //...
  "prepare": "husky"
},

Setup lint-staged

Adding lint-staged:

yarn add lint-staged --dev

At the time of writing this article, the following version was generated:

"lint-staged": "^15.5.0"

To configure Husky to run pre-commit actions together with lint-staged, it is necessary to modify the file inside the .husky folder:

pre-commit

npx --no-install lint-staged

Pre-commit actions

Currently, the app has three commands related to the actions to be added to the pre-commit:

package.json

//...
"scripts": {
  //...
  "lint-src-fix": "eslint src --fix",
  "format-src-fix": "prettier src --write",
  "test": "jest"
}

By setting up these actions to run, the pre-commit will work successfully: the files staged in git will be updated right before the commit is finalized. However, the downside is that it will run the command on all files in src, even though the pre-commit is supposed to impact only the files that are staged in git.
To make the pre-commit actions more efficient, two new scripts will be created:

package.json

//...
"scripts": {
  //...
  "lint-fix": "eslint --fix",
  "format-fix": "prettier --write"
}

If you try to run these commands directly in the terminal, they won't work successfully because they require a file or folder path to be passed, like:

yarn lint-fix {path to folder or file}
yarn format-fix {path to folder or file}

However, when these commands are run with lint-staged, it detects the files that are staged in git and successfully applies the commands to them.

To define the pre-commit actions to be executed through Husky with lint-staged, you need to add the following to package.json:

  "lint-staged": {
    "yarn lint-fix",
    "yarn format-fix",
    "yarn test --findRelatedTests --bail"
  },

For the tests, two additional options are passed:

--findRelatedTests: runs the tests for the files that are staged in git as well as the ones related to them. By "related," I mean that if you modify and git add a component file like Component.tsx without touching its corresponding test file Component.test.tsx, this command will still know which test is associated with the component and validate it.
--bail: stops running tests immediately after the first failure, aborting the commit process

Now, the pre-commit actions are more efficient, acting only on the files staged in git. But we can make it even more specific by targeting file extensions for each action.
For code formatting and linting, the goal is to apply the rules only to typeScript files .ts and .tsx inside the components folder. For running tests, we will target only .tsx files.
Thus, for lint-staged to not only consider the files staged in git but also apply actions based on the file types we want, the configuration will look like this:

  "lint-staged": {
    "src/components/**/*.{ts,tsx}": [
      "yarn lint-fix",
      "yarn format-fix"
    ],
    "src/components/**/*.tsx": "yarn test --findRelatedTests --bail"
  },

package.json

Currently, the package.json looks like this:

{
  "name": "react-example-lib",
  "version": "0.3.0",
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/griseduardo/react-example-lib.git"
  },
  "scripts": {
    "build": "rollup -c --bundleConfigAsCjs",
    "lint-src": "eslint src",
    "lint-src-fix": "eslint src --fix",
    "lint-fix": "eslint --fix",
    "format-src": "prettier src --check",
    "format-src-fix": "prettier src --write",
    "format-fix": "prettier --write",
    "test": "jest",
    "prepare": "husky"
  },
  "lint-staged": {
    "src/components/**/*.{ts,tsx}": [
      "yarn lint-fix",
      "yarn format-fix"
    ],
    "src/components/**/*.tsx": "yarn test --findRelatedTests --bail"
  },
  "devDependencies": {
    "@babel/core": "^7.26.10",
    "@babel/preset-env": "^7.26.9",
    "@babel/preset-react": "^7.26.3",
    "@babel/preset-typescript": "^7.26.0",
    "@eslint/js": "^9.19.0",
    "@rollup/plugin-commonjs": "^28.0.2",
    "@rollup/plugin-node-resolve": "^16.0.0",
    "@rollup/plugin-terser": "^0.4.4",
    "@rollup/plugin-typescript": "11.1.6",
    "@testing-library/dom": "^10.4.0",
    "@testing-library/jest-dom": "^6.6.3",
    "@testing-library/react": "^16.2.0",
    "@types/jest": "^29.5.14",
    "@types/react": "^19.0.10",
    "@types/react-dom": "^19.0.4",
    "eslint": "^9.19.0",
    "eslint-plugin-react": "^7.37.4",
    "husky": "^9.1.7",
    "jest": "^29.7.0",
    "jest-environment-jsdom": "^29.7.0",
    "jest-styled-components": "^7.2.0",
    "lint-staged": "^15.5.0",
    "prettier": "^3.4.2",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "rollup": "^4.30.1",
    "rollup-plugin-dts": "^6.1.1",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "styled-components": "^6.1.14",
    "typescript": "^5.7.3",
    "typescript-eslint": "^8.23.0"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "styled-components": "^6.1.14"
  }
}

The version will be updated to 0.4.0, since a new version of the library will be released:

{
  "name": "react-example-lib",
  "version": "0.4.0",
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/griseduardo/react-example-lib.git"
  },
  "scripts": {
    "build": "rollup -c --bundleConfigAsCjs",
    "lint-src": "eslint src",
    "lint-src-fix": "eslint src --fix",
    "lint-fix": "eslint --fix",
    "format-src": "prettier src --check",
    "format-src-fix": "prettier src --write",
    "format-fix": "prettier --write",
    "test": "jest",
    "prepare": "husky"
  },
  "lint-staged": {
    "src/components/**/*.{ts,tsx}": [
      "yarn lint-fix",
      "yarn format-fix"
    ],
    "src/components/**/*.tsx": "yarn test --findRelatedTests --bail"
  },
  "devDependencies": {
    "@babel/core": "^7.26.10",
    "@babel/preset-env": "^7.26.9",
    "@babel/preset-react": "^7.26.3",
    "@babel/preset-typescript": "^7.26.0",
    "@eslint/js": "^9.19.0",
    "@rollup/plugin-commonjs": "^28.0.2",
    "@rollup/plugin-node-resolve": "^16.0.0",
    "@rollup/plugin-terser": "^0.4.4",
    "@rollup/plugin-typescript": "11.1.6",
    "@testing-library/dom": "^10.4.0",
    "@testing-library/jest-dom": "^6.6.3",
    "@testing-library/react": "^16.2.0",
    "@types/jest": "^29.5.14",
    "@types/react": "^19.0.10",
    "@types/react-dom": "^19.0.4",
    "eslint": "^9.19.0",
    "eslint-plugin-react": "^7.37.4",
    "husky": "^9.1.7",
    "jest": "^29.7.0",
    "jest-environment-jsdom": "^29.7.0",
    "jest-styled-components": "^7.2.0",
    "lint-staged": "^15.5.0",
    "prettier": "^3.4.2",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "rollup": "^4.30.1",
    "rollup-plugin-dts": "^6.1.1",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "styled-components": "^6.1.14",
    "typescript": "^5.7.3",
    "typescript-eslint": "^8.23.0"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "styled-components": "^6.1.14"
  }
}

CHANGELOG file

Currently, the CHANGELOG.md looks like this:

## 0.3.0

_Mar. 24, 2025_

- setup jest and testing-library
- add components tests

## 0.2.0

_Fev. 24, 2025_

- setup typescript-eslint and prettier
- add custom rules

## 0.1.0

_Jan. 29, 2025_

- initial config

Since a new version will be released, the changes will be added to the file:

## 0.4.0

_Abr. 29, 2025_

- setup husky and lint-staged
- define pre-commit actions

## 0.3.0

_Mar. 24, 2025_

- setup jest and testing-library
- add components tests

## 0.2.0

_Fev. 24, 2025_

- setup typescript-eslint and prettier
- add custom rules

## 0.1.0

_Jan. 29, 2025_

- initial config

Folder structure

The folder structure is currently as follows. In addition to the modification of some files, the .husky folder with the pre-commit file was also added:

Publication of a new version

Conclusion

The goal of this article was to setup Husky and lint-staged to define pre-commit rules for the application. The objective is to ensure that code changes adhere to lint and prettier standardization rules, and validate that the tests continue to pass before finalizing the commit. Here is the repository on github and the library on npmjs with the new modifications.

Biblioteca de componentes React e typescript, parte 4: pré-commit com Husky e lint-staged

Eduardo Henrique Gris — Tue, 29 Apr 2025 22:55:15 +0000

Introdução

English version: React and typescript components lib, part 4: pre-commit with Husky and lint-staged

Na parte quatro, será adicionada ações de pre-commit na aplicação a partir do uso de duas libs, Husky e lint-staged. O objetivo é mostrar a parte prática da adição delas nesse artigo, para uma referência segue o artigo Husky e lint-staged para pré-commit em React, que foi o primeiro que escrevi em dev.to.

Libs

Husky: é a lib que vai permitir executar ações pre-commit
lint-staged: é a lib que vai definir as ações pre-commit serem executadas e aplicadas nos arquivos em stage do git, ou seja, que foi dado o git add neles

Ações pre-commit

As ações pre-commit são executadas após se executar o git commit no terminal, mas logo antes do commit ser finalizado de fato.
Para a aplicação serão definidas três ações pre-commit:

Formatar os arquivos adicionados na stage do git, seguindo as regras de lint definidas para ela, logo antes do commit ser finalizado
Formatar os arquivos adicionados na stage do git, seguindo as regras de prettier definidas para ela, logo antes do commit ser finalizado
Executar os testes relacionados aos componentes alterados que foram adicionados no git, para validar se estão passando, logo antes do commit ser finalizado

Setup Husky

Adição do Husky:

yarn add husky --dev

No momento desse artigo gerou a seguinte versão:

"husky": "^9.1.7"

Para fazer a configuração, rodar no terminal:

npx husky init

Ele vai gerar na raiz do projeto uma pasta .husky, dentro dela terá uma pasta _ com todos os git hooks disponíveis mas que não estão definidos para executar dentro do projeto. E fora da pasta _ um arquivo pre-commit, com uma ação inicial definida para executar dentro dele, mas como não corresponde a comandos da app o arquivo vai ser modificado.
Além de gerar a pasta comentada acima, também irá gerar um comando que instala o Husky dentro da app em package.json:

"scripts": {
  //...
  "prepare": "husky"
},

Setup lint-staged

Adição do lint-staged:

yarn add lint-staged --dev

No momento desse artigo gerou a seguinte versão:

"lint-staged": "^15.5.0"

Para configurar o Husky para executar as ações pre-commit em conjunto com lint-staged é necessário modificar o arquivo dentro da pasta .husky:

pre-commit

npx --no-install lint-staged

Ações pre-commit

No momento a app está com três comandos referentes as ações a serem adicionadas no pre-commit:

package.json

//...
"scripts": {
  //...
  "lint-src-fix": "eslint src --fix",
  "format-src-fix": "prettier src --write",
  "test": "jest"
}

Colocando essas ações para serem executadas, o pre-commit funcionará com sucesso, os arquivos adicionados na stage do git serão atualizados logo antes do commit ser finalizado, mas o lado ruim é que executará o comando para todos o arquivos de src, sendo que o pre-commit em si só irá impactar os arquivos que estão na stage do git.
Então para tornar as ações pre-commit mais performáticas serão criados dois novos scripts:

package.json

//...
"scripts": {
  //...
  "lint-fix": "eslint --fix",
  "format-fix": "prettier --write"
}

Se tentar executar diretamente os comandos no terminal, eles não serão executados com sucesso, pois dependem de ser passado o arquivo ou a pasta a ser executado no estilo:

yarn lint-fix {caminho da pasta ou arquivo}
yarn format-fix {caminho da pasta ou arquivo}

Só que quando são colocados para serem executados com lint-staged, é observado os arquivos que estão na stage do git e executado o comando neles com sucesso.

Para definir as ações pre-commit a serem executadas a partir do Husky com lint-staged, é necessário adicionar em package.json:

  "lint-staged": {
    "yarn lint-fix",
    "yarn format-fix",
    "yarn test --findRelatedTests --bail"
  },

No caso dos testes estamos passando duas coisas a mais:

--findRelatedTests: vai executar os testes dos arquivos que foram adicionados na stage do git e os relacionados a eles. Quando digo relacionado, quero dizer que ao modificar e dar git add em um arquivo de componente Component.tsx e não ter modificado o arquivo de teste Component.test.tsx, esse comando sabe qual o teste associado ao componente e mesmo sem estar o arquivo de teste adicinado em stage do git, vai validar os testes
--bail: caso tenha teste quebrando vai encerrar com falha a execução dos testes, abortando o commit

Agora as ações pre-commit estão mais performáticas para agirem diretamente com base nos arquivos adicionados na stage do git. Mas podemos deixar ainda mais específico para as extensões de arquivo que cada ação vai ser executada.
No caso de padronização de código em relação as regras de lint e prettier, a ideia é executar nos arquivos dentro da pasta de componentes com extensão typescript .ts e .tsx. No caso dos testes seriam os arquivos especificamente de componentes e testes .tsx. Dessa forma, para fazer o lint-staged levar em consideração alés dos arquivos adicionados na stage do git, mas também os que se quer que atue as ações pre-commit, ficará da seguinte forma:

  "lint-staged": {
    "src/components/**/*.{ts,tsx}": [
      "yarn lint-fix",
      "yarn format-fix"
    ],
    "src/components/**/*.tsx": "yarn test --findRelatedTests --bail"
  },

package.json

No momento o package.json está da forma abaixo:

{
  "name": "react-example-lib",
  "version": "0.3.0",
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/griseduardo/react-example-lib.git"
  },
  "scripts": {
    "build": "rollup -c --bundleConfigAsCjs",
    "lint-src": "eslint src",
    "lint-src-fix": "eslint src --fix",
    "lint-fix": "eslint --fix",
    "format-src": "prettier src --check",
    "format-src-fix": "prettier src --write",
    "format-fix": "prettier --write",
    "test": "jest",
    "prepare": "husky"
  },
  "lint-staged": {
    "src/components/**/*.{ts,tsx}": [
      "yarn lint-fix",
      "yarn format-fix"
    ],
    "src/components/**/*.tsx": "yarn test --findRelatedTests --bail"
  },
  "devDependencies": {
    "@babel/core": "^7.26.10",
    "@babel/preset-env": "^7.26.9",
    "@babel/preset-react": "^7.26.3",
    "@babel/preset-typescript": "^7.26.0",
    "@eslint/js": "^9.19.0",
    "@rollup/plugin-commonjs": "^28.0.2",
    "@rollup/plugin-node-resolve": "^16.0.0",
    "@rollup/plugin-terser": "^0.4.4",
    "@rollup/plugin-typescript": "11.1.6",
    "@testing-library/dom": "^10.4.0",
    "@testing-library/jest-dom": "^6.6.3",
    "@testing-library/react": "^16.2.0",
    "@types/jest": "^29.5.14",
    "@types/react": "^19.0.10",
    "@types/react-dom": "^19.0.4",
    "eslint": "^9.19.0",
    "eslint-plugin-react": "^7.37.4",
    "husky": "^9.1.7",
    "jest": "^29.7.0",
    "jest-environment-jsdom": "^29.7.0",
    "jest-styled-components": "^7.2.0",
    "lint-staged": "^15.5.0",
    "prettier": "^3.4.2",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "rollup": "^4.30.1",
    "rollup-plugin-dts": "^6.1.1",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "styled-components": "^6.1.14",
    "typescript": "^5.7.3",
    "typescript-eslint": "^8.23.0"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "styled-components": "^6.1.14"
  }
}

Será mudada a versão para 0.4.0, uma vez que uma nova versão da lib será disponibilizada:

{
  "name": "react-example-lib",
  "version": "0.4.0",
  "main": "dist/cjs/index.js",
  "module": "dist/esm/index.js",
  "types": "dist/index.d.ts",
  "files": [
    "dist"
  ],
  "license": "MIT",
  "repository": {
    "type": "git",
    "url": "https://github.com/griseduardo/react-example-lib.git"
  },
  "scripts": {
    "build": "rollup -c --bundleConfigAsCjs",
    "lint-src": "eslint src",
    "lint-src-fix": "eslint src --fix",
    "lint-fix": "eslint --fix",
    "format-src": "prettier src --check",
    "format-src-fix": "prettier src --write",
    "format-fix": "prettier --write",
    "test": "jest",
    "prepare": "husky"
  },
  "lint-staged": {
    "src/components/**/*.{ts,tsx}": [
      "yarn lint-fix",
      "yarn format-fix"
    ],
    "src/components/**/*.tsx": "yarn test --findRelatedTests --bail"
  },
  "devDependencies": {
    "@babel/core": "^7.26.10",
    "@babel/preset-env": "^7.26.9",
    "@babel/preset-react": "^7.26.3",
    "@babel/preset-typescript": "^7.26.0",
    "@eslint/js": "^9.19.0",
    "@rollup/plugin-commonjs": "^28.0.2",
    "@rollup/plugin-node-resolve": "^16.0.0",
    "@rollup/plugin-terser": "^0.4.4",
    "@rollup/plugin-typescript": "11.1.6",
    "@testing-library/dom": "^10.4.0",
    "@testing-library/jest-dom": "^6.6.3",
    "@testing-library/react": "^16.2.0",
    "@types/jest": "^29.5.14",
    "@types/react": "^19.0.10",
    "@types/react-dom": "^19.0.4",
    "eslint": "^9.19.0",
    "eslint-plugin-react": "^7.37.4",
    "husky": "^9.1.7",
    "jest": "^29.7.0",
    "jest-environment-jsdom": "^29.7.0",
    "jest-styled-components": "^7.2.0",
    "lint-staged": "^15.5.0",
    "prettier": "^3.4.2",
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "rollup": "^4.30.1",
    "rollup-plugin-dts": "^6.1.1",
    "rollup-plugin-peer-deps-external": "^2.2.4",
    "styled-components": "^6.1.14",
    "typescript": "^5.7.3",
    "typescript-eslint": "^8.23.0"
  },
  "peerDependencies": {
    "react": "^19.0.0",
    "react-dom": "^19.0.0",
    "styled-components": "^6.1.14"
  }
}

Arquivo CHANGELOG

No momento o CHANGELOG.md está da forma abaixo:

## 0.3.0

_Mar. 24, 2025_

- setup jest and testing-library
- add components tests

## 0.2.0

_Fev. 24, 2025_

- setup typescript-eslint and prettier
- add custom rules

## 0.1.0

_Jan. 29, 2025_

- initial config

Como uma nova versão será disponibilizada, será adicionado sobre o que foi modificado no arquivo:

## 0.4.0

_Abr. 29, 2025_

- setup husky and lint-staged
- define pre-commit actions

## 0.3.0

_Mar. 24, 2025_

- setup jest and testing-library
- add components tests

## 0.2.0

_Fev. 24, 2025_

- setup typescript-eslint and prettier
- add custom rules

## 0.1.0

_Jan. 29, 2025_

- initial config

Estrutura de pastas

A estrutura de pastas está da seguinte forma, sendo que além da modificação de alguns arquivos, foi adicionada a pasta do .husky com o arquivo pre-commit:

Publicação nova versão

Conclusão

A ideia desse artigo foi fazer o setup do Husky e lint-staged para definir regras de pre-commit para a aplicação. O objetivo é garantir que as alterações feitas no código sigam as regras de padronização de lint e prettier, e validar que o testes continuam passando antes de finalizar o commit.
Segue o repositório no github e a lib no npmjs com as novas modificações.