
# Cómo documentar mis componentes react con JSDoc

<Date date="01-16-2023" />

<GoogleAdsense />

## Introdución

Es necesario tener una buena documentación sobre nuestros componentes, para que otros desarrolladores puedan entender como funciona y como usarlo. En este articulo vamos a ver como podemos documentar nuestros componentes de react con JSDoc y como publicar la documentación en nuestro sitio estático.

Con unos sencillos pasos, la librería jsdoc y el uso de las buenas prácticas de programación cuando trabajemos con react, podremos tener una documentación de nuestros componentes de forma automática. Existen diferentes plugins para upgradear nuestro jsdoc y dar soporte a react, pero como React no deja de ser javascript y los componentes funciones la lib por defecto es más que suficiente.

El reporte que vamos generar no deja de ser un archivo html, por lo que podrás desplegarlo en cualquier sitio estático.

> Si utilizas typescript necesitarás instalar jsdoc-babel

## 1. Instalación

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```bash

yarn add jsdoc-babel -D

```

</CH.Code>

## 2. Configuración

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```json jsdoc.json
{
    "tags": {
        "allowUnknownTags": true,
        "dictionaries": ["jsdoc", "closure"]
    },
    "source": {
        "include": ["src/components/"],
        "includePattern": ".+\\.tsx$",
        "excludePattern": "(node_modules/|docs)"
    },
    "plugins": ["plugins/markdown", "node_modules/jsdoc-babel"],
    "templates": {
        "cleverLinks": false,
        "monospaceLinks": false
    },
    "babel": {
        "extensions": ["tsx"],
        "ignore": ["**/*.(test|spec).ts"],
        "babelrc": false,
        "presets": [["@babel/preset-env", { "targets": { "node": true } }], "@babel/preset-typescript"],
        "plugins": ["@babel/proposal-class-properties", "@babel/proposal-object-rest-spread"]
    },
    "opts": {
        "encoding": "utf8",
        "destination": "./public/docs/",
        "recurse": true,
        "verbose": true
    }
}
```

</CH.Code>

## 3. Customiza tu reporte

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```javascript custom-docs.js mark=13

import { readFile, writeFile } from 'fs';
import glob from 'glob';

glob('public/docs/**/*.?(html|css)', function (err, files) {
    if (err) {
        console.log('err', err);
        return;
    }

    files.forEach((path) => {
        readFile(path, 'utf8', (err, data) => {
            ...code
        });
    });
});


```

</CH.Code>

> Ahí deberías buscar el código que necesitas para modificar tu reporte y sobreescribirlo.

## 4. Genera tu reporte

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```bash

yarn jsdoc -c jsdoc.json

```

</CH.Code>

Para ver un ejemplo de salida puedes click arriba donde dice Docs o a través de este [enlace](https://docs.xabierlameiro.com 'Link to my docs')



# Filtro para posiciones, encuesta para comprobar compatibilidad

<Date date="03-07-2023" />

<GoogleAdsense slot="6618374506" horizontal />

## Motivación

Aunque parezca mentira, debido a la alta demanda de desarrolladores de todo tipo en el mercado por parte de las empresas, muchos recruiters y headhunters se han vuelto máquinas del copy paste. No sé la cifra o la cantidad diaria de mensajes que envían a todos los perfiles de su red que hacen "match" con la posición nueva que tienen disponible, pero apostaría que no son pocos. Y no es que no me guste que me envíen mensajes, pero me gustaría que me enviaran mensajes que realmente me interesen y que me hagan pensar que han visto mi perfil, mi código o alguno de mis trabajos y que realmente me quieren contratar por mis habilidades.

No suele ser así, muchos usan programas para automatizar el proceso de búsqueda de perfiles como [Hiretual](https://hiretual.com/ 'Hiretual') o [Jobvite](https://www.jobvite.com/ 'Jobvite'), envían mensajes a todos los usuarios "que hacen match" y en ocasiones esto no funciona muy bien. Ya que en tu perfil pone claramente desarrollador Frontend, tu experiencia dice lo mismo... pero, ellos tienen una posición Java con microservicios increíble para ti.

Otras veces se mete la pata y te envían un mensaje con el nombre de tu compañero de equipo:

<Image src="/coincidence.png" alt="Coincidencia" width="1024" height="726" layout="responsive" />

## La idea

Cuantas veces has tenido una llamada con preguntas como:

-   ¿ Por que buscas un cambio ?
-   ¿ Conoces los principios SOLID ?
-   ¿ Cuantos años dirías que has trabajo con React ? ¿ Y Typescript ?
-   ¿ Sabes lo que es la integración continua ?

> Para que despues te ofrezcan un salario inferior al que tienes, o que te pidan el CV para no volver a decirte nunca nada.

¿ How many times bro ?

**_La idea es filtrar tú antes que te filtren a ti._**

## Solución

10 simples preguntas sobre puntos que consideres importantes, requisitos, valores.. o básicamente lo que te de la gana y si se cumplen, el recruiter obtendrá información de contacto para poder entrar en detalle de todo el proceso.

Es un win win, ambos ahorramos tiempo, ¿ no ?

## Código

Con un componente container o página, un par de botones, radiobuttons y un array de objectos tienes más que suficiente, en mi caso:

Tengo mi página:

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```tsx survey.tsx
import Dialog from '@/components/Dialog';
import styles from '@/styles/survey.module.css';
import ControlButtons from '@/components/ControlButtons';
import Confetti from 'react-confetti';
import SEO from '@/components/SEO';
import useWindowResize from '@/hooks/useWidowResize';
import useSurvey from '@/hooks/useSurvey';
import NavigationArrows from '@/components/NavigationArrows';

const Survey = () => {
    const { width, height } = useWindowResize();
    const {
        questions,
        answers,
        surveySuccess,
        totalQuestions,
        currentQuestionNum,
        questionsDoneNum,
        handleNextQuestion,
        handlePreviousQuestion,
        handleAnswerOptionClick,
    } = useSurvey();

    return (
        <>
            <Confetti width={width} height={height} numberOfPieces={100} run={surveySuccess} />
            <SEO
                noimage={false}
                meta={{
                    title: 'Averigua si hago match con la posición en 1 minuto',
                    description: 'Click para continuar',
                    noindex: true,
                }}
            />
            <Dialog
                open
                modalMode
                withPadding
                header={
                    <div className={styles.header}>
                        <ControlButtons />
                        <span>
                            {currentQuestionNum > 0 && currentQuestionNum < 11 && (
                                <span>
                                    {currentQuestionNum} / {totalQuestions - 2}
                                </span>
                            )}
                        </span>
                    </div>
                }
                body={
                    // TODO: Move to a component
                    <div className={styles.container}>
                        {questions.map(
                            (question: any, index: number) =>
                                currentQuestionNum === index && (
                                    <div key={index} className={styles.question}>
                                        <div
                                            dangerouslySetInnerHTML={{ __html: question.questionHtml }}
                                            className={styles.questionHtml}
                                        />
                                        {question.answerOptions?.map((answerOption: any) => (
                                            <label htmlFor={answerOption.answerText} key={answerOption.answerText}>
                                                <input
                                                    onChange={(e) =>
                                                        handleAnswerOptionClick({
                                                            question: question.questionText,
                                                            answer: e.target.value,
                                                            isCorrect: answerOption.isCorrect,
                                                            questionNum: index,
                                                        })
                                                    }
                                                    type="radio"
                                                    id={answerOption.answerText}
                                                    name={String(index)}
                                                    value={answerOption.answerText}
                                                    checked={answers[index]?.answer === answerOption.answerText}
                                                />
                                                {answerOption.answerText}
                                            </label>
                                        ))}
                                    </div>
                                )
                        )}
                    </div>
                }
                footer={
                    <div className={styles.buttons}>
                        <NavigationArrows
                            hidden={currentQuestionNum < 1 || currentQuestionNum > 10}
                            disabledLeft={currentQuestionNum < 2}
                            disabledRight={questionsDoneNum < currentQuestionNum}
                            onClickLeft={handlePreviousQuestion}
                            onClickRight={handleNextQuestion}
                        />
                    </div>
                }
            />
        </>
    );
};

export default Survey;
```

</CH.Code>

Mi hook con lógica

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```ts useSurvey.ts
import { useRouter } from 'next/router';
import { useReducer, useEffect, useRef } from 'react';

const initialState = {
    currentQuestion: 0,
    questionsDone: 0,
    success: false,
    answers: [],
};

const reducer = (state: any, action: any) => {
    ...ya sabes como funciona un switch no?
};

const useSurvey = () => {
    const { query } = useRouter();
    const { name = '&#128075;' } = query;
    const emailRef = useRef<boolean>(false);

    const [state, dispatch] = useReducer(reducer, initialState);

    // Prepotencia here!
    const questions = [
        {
            questionText: '¿ Que llegó antes el huevo o la gallina ?',
            questionHtml: `<h2>¿ Que llegó antes el huevo o la gallina ?</h2>`,
            answerOptions: [{ answerText: 'Huevo', isCorrect: true, }, { answerText: 'Gallina', isCorrect: false }],
        },
    ];

    useEffect(() => {
        if (state.currentQuestion === questions.length - 1 && !emailRef.current) {
            (async () => {
                try {
                    await fetch('/api/email', {
                        method: 'POST',
                        headers: {
                            'Content-Type': 'application/json',
                        },
                        body: JSON.stringify({
                            subject: `Job survey from ${name} - ${new Date().toLocaleString()}`,
                            message: `
                                    <h1> ${name} </h1>
                                    <code> ${navigator.userAgent} </code>
                                    <ol>
                                        ${state.answers.map(
                                            (answer: any) =>
                                                `<li> ${answer.question} : ${answer.answer} - ${
                                                    answer.isCorrect ? '✅' : '🚫'
                                                } </li>`
                                        )}
                                    </ol>
                                    `.replace(/,/g, ''),
                        }),
                    });
                    emailRef.current = true;
                } catch (e) {
                    console.log(e);
                }
            })();
        }
    }, [state, name, questions.length]);

    const handlePreviousQuestion = () => {
        if (state.currentQuestion > 1) dispatch({ type: 'PREVIOUS_QUESTION' });
    };

    const handleNextQuestion = () => {
        if (state.currentQuestion != 0 && state.questionsDone >= state.currentQuestion)
            dispatch({ type: 'NEXT_QUESTION' });
    };

    const handleAnswerOptionClick = (payload: {
        question: string;
        answer: string;
        isCorrect: boolean;
        questionNum: number;
    }) => dispatch({ type: 'ADD_ANSWER', payload });

    return {
        questions,
        answers: state.answers,
        surveySuccess: state.success,
        currentQuestionNum: state.currentQuestion,
        questionsDoneNum: state.questionsDone,
        totalQuestions: questions.length,
        handleAnswerOptionClick,
        handleNextQuestion,
        handlePreviousQuestion,
    };
};

export default useSurvey;
```

</CH.Code>

Mi backend:

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```ts email.ts
import type { NextApiRequest, NextApiResponse } from 'next';
import nodemailer from 'nodemailer';

export default async function handler(req: NextApiRequest, res: NextApiResponse<any>) {
    const transporter = nodemailer.createTransport({
        service: process.env.EMAIL_HOST,
        auth: {
            user: process.env.EMAIL,
            pass: process.env.EMAIL_PASSWORD,
        },
    });

    const { subject, message } = req.body;

    const mailOptions = {
        from: process.env.EMAIL,
        to: process.env.EMAIL,
        subject: subject,
        html: message,
    };

    try {
        await transporter.sendMail(mailOptions);
        res.status(200).json({ success: true });
    } catch (error) {
        res.status(500).json({ success: error });
    }
}
```

</CH.Code>

## Resultado

<Image src="/survey-success.png" alt="Caso de éxito" width="544" height="452" />
<Image src="/survey-email.png" alt="Correo con las respuestas" width="822" height="491" />

Pruebalo tu mismo: [Enlace al resultado](https://xabierlameiro.com/survey?name=Lector/a 'Enlace a la encuesta')



# Como publicar el reporte de cobertura de testing en tu aplicación de React

<Date date="01-01-2023" />

<GoogleAdsense />

En este post vamos a ver como publicar el reporte de cobertura de testing en tu aplicación de React. Para ello vamos a utilizar:

-   [Jest](https://jestjs.io/ 'Enlace a jestjs.io')

> Una "alternativa" perfecta a SonarQube para pequeños proyectos.

No es común ni necesario publicar tu reporte de testing de tu aplicación, incluso habrá quien opine que es algo inprudente por que
puedes exponer información sensible de tu aplicación. Pero la idea principal de esto es que si tienes un proyecto open source y quieres
que la gente pueda contribuir, es una buena idea que puedan ver el reporte de testing para que sepan que tan bien esta cubierto tu proyecto o
por que quieres enseñar a la gente como hacer testing en de una aplicación.

Sin embargo, para tener un extra de seguridad, es tan sencillo como tenerlo en una ruta protegida con usuario y contraseña.

PD: Este ejemplo está desarrollado en una aplicación web hecha con **Nextjs** pero sirve para cualquier aplicación web que
use **jest**.

## 1. Ruta para el reporte

Lo primero que debemos hacer es asignar el outputDirectory de jest a una carpeta publica

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```javascript jest.config.js mark=4
const customJestConfig = {
    setupFilesAfterEnv: ['<rootDir>/jest.setup.js'],
    coveragePathIgnorePatterns: ['^.*\\.stories\\.[jt]sx?$'],
    coverageDirectory: 'public/coverage',
    testEnvironment: 'jest-environment-jsdom',
    coverageReporters: ['html'],
    collectCoverageFrom: ['src/components/**/*.tsx'],
    moduleNameMapper: {
        '^@/helpers(.*)$': '<rootDir>src/helpers/index.ts$1',
        '^@/layout(.*)$': '<rootDir>src/components/Layout/index.tsx$1',
        '^@/test$': '<rootDir>/jest.setup.js',
        '^@/components(.*)$': '<rootDir>src/components/$1',
        '^@/context(.*)$': '<rootDir>src/context/$1',
        '^@/hooks(.*)$': '<rootDir>src/hooks/$1',
        '^@/constants(.*)$': '<rootDir>src/constants/$1',
    },
};
```

</CH.Code>

## 2. Script para modificar el reporte

Este escript lo que hace es modificar la ruta de los archivos estáticos que el reporte necesita para funcionar como imágnes, css, javascript, etc.
Además se customizan algunos textos del reporte.

> La alternativa si usa la clase es usar la clase [CustomReporter](https://jestjs.io/docs/configuration 'Página de configuración de Jest') e implementar el método onRunComplete.

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```javascript custom-reporter.js
import { readFile, writeFile } from 'fs';
import glob from 'glob';

glob('public/coverage/**/*.?(html|css)', function (err, files) {
    if (err) {
        console.log('err', err);
        return;
    }

    files.forEach((path) => {
        readFile(path, 'utf8', (err, data) => {
            if (err) {
                console.log('err', err);
                return;
            }
            let replaced = data.replace(
                /Code coverage generated by\n\s*<a href="https:\/\/istanbul\.js\.org\/"/g,
                `Code coverage automatically generated by Xabier Lameiro on ${new Date().toLocaleDateString()}`
            );

            if (path === 'public/coverage/index.html') {
                replaced = replaced.replace(/src="/g, 'src="coverage/');
                replaced = replaced.replace(/href="/g, 'href="coverage/');
            }

            writeFile(path, replaced, 'utf-8', function (err, a) {
                if (err) {
                    console.log('err', err);
                    return;
                }
            });
        });
    });
});
```

</CH.Code>

## 3. Comando para generar el reporte cuando se genera el build

Para que el reporte se genere en la carpeta public cuando se termina la build, debemos agregar los siguientes comandos en el package.json

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```json package.json mark=5,9
{
    "scripts": {
        "dev": "next dev",
        "build": "next build",
        "postbuild": "npm run coverage",
        "start": "next start",
        "lint": "next lint",
        "test": "NODE_ENV=test jest",
        "coverage": "rm -rf public/coverage && NODE_ENV=test jest --coverage && node custom-reporter.js",
        "watch": "jest --watchAll",
        "test:clear": "jest --clearCache",
        "storybook": "storybook dev -p 6006",
        "build-storybook": "storybook build"
    }
}
```

</CH.Code>

## 4. Crear una redirección en el servidor/ plafatorma en la nube

En mi caso uso Vercel pero cualquier plataforma que uses, debes crear una redirección para que cuando se acceda a la ruta /coverage

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```javascript next.config.js mark=4,5
 rewrites: async () => {
        return [
            {
                source: '/:coverage',
                destination: '/:coverage/index.html',
            },
        ];
    },
```

</CH.Code>

> Aquí puedes ver el ejemplo de como se ve el reporte de testing de este blog [xabierlameiro.com/coverage](https://coverage.xabierlameiro.com/ 'Sección de coverage')



# Desplegar mi storybook es muy sencillo

<Date date="01-04-2023" />

<GoogleAdsense />

Una vez que hayas creado tus componentes en Storybook, puedes compartirlos de diferentes maneras. Puedes desplegar Storybook en Vercel, GitHub o Netlify o Heroku y compartir la URL con tu equipo y clientes potenciales.
También puede crear una versión estática de Storybook y desplegarla en un servidor web. Esto le permite tener una versión de Storybook que está siempre en línea y actualizada.

Storybook es fácil de configurar y gestionar. Necesitará Node.js y algunas dependencias de desarrollo instaladas para configurar su propio entorno. También puedes usar generator-storybook para empezar rápidamente a crear un archivo de configuración de Storybook.

Una vez que hayas configurado tu Storybook, puedes empezar a escribir historias para tus componentes. Una historia es esencialmente una breve explicación de cómo se utilizará su componente en la aplicación. Puede escribir historias para los componentes que ya ha
creado y también cualquier componente en el que esté trabajando. Storybook también te permite crear variaciones de tu componente, esto es útil para las pruebas A/B.

Desplegar componentes React con Storybook es una gran manera de mostrar tu trabajo y asegurar que tus componentes están libres de errores. Te permite crear guías de estilo vivas para tus componentes y proporciona un sandbox para probarlos.
Configurar Storybook puede parecer desalentador, pero es fácil si sigues la documentación. Una vez que lo tengas configurado, puedes empezar a crear historias y variaciones de tus componentes y compartirlas con tu equipo y clientes potenciales.

## 1. Comandos del libro de historias

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>
```javascript package.json
"scripts": {
    "storybook": "storybook dev -p 6006",
    "build-storybook": "storybook build"
}
```
</CH.Code>

## 2. Haz una historia de tus componentes

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```tsx Avatar.stories.tsx
import React from 'react';
import { ComponentStory, ComponentMeta } from '@storybook/react';
import Avatar from '.';

export default {
    /* 👇 The title prop is optional.
     * See https://storybook.js.org/docs/react/configure/overview#configure-story-loading
     * to learn how to generate automatic titles
     */
    title: 'Settings / Avatar',
    component: Avatar,
} as ComponentMeta<typeof Avatar>;

//👇 We create a “template” of how args map to rendering
const Template: ComponentStory<typeof Avatar> = (args) => <Avatar {...args} />;

// 👇 Each story then reuses that template
export const Primary = Template.bind({});

Primary.args = {
    name: 'Juan Carlos de Borbón',
    description: 'Rey emérito de España',
    img: '/avatar.png',
    alt: 'Quien bien se vive!',
};
```

</CH.Code>

## 3. Despliegue de Storybook

Las cosas más importantes son el comando build, el directorio de salida y el comando install. (yarn, npm o lo que sea) para las dependencias.

<CH.Code style={{maxWidth: 'max-content', margin: '20px 0'}}>

```bash

yard build-storybook

./storybook-static

yarn i || npm i || npx i

```

</CH.Code>

> Aquí puedes ver el ejemplo de mi storybook desplegado en un subdominio: [https://storybook.xabierlameiro.com](https://storybook.xabierlameiro.com 'Enlace a mi storybook desplegado')
