
# Como documentar os meus compoñentes react con JSDoc

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

<GoogleAdsense />

## Introdución

É necesario ter unha boa documentación sobre os nosos compoñentes, para que outros desarrolladores poidan entender como funciona e como usalo. En leste articulo imos ver como podemos documentar os nosos compoñentes de react con JSDoc e como publicar a documentación no noso sitio estático.

Cuns sinxelos pasos, a librería jsdoc e o uso das boas prácticas de programación cando traballemos con react, poderemos ter unha documentación dos nosos compoñentes de forma automática. Existen diferentes plugins para upgradear o noso jsdoc e dar soporte a react, pero como React non deixa de ser javascript e as compoñentes funcións a lib por defecto é máis que suficiente.

O reporte que imos xerar non deixa de ser un arquivo html, polo que poderás despregalo en calquera sitio estático.

> Se 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 o teu 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>

> Aí deberías buscar o código que necesitas para modificar o teu reporte e sobreescribirlo.

## 4. Xera o teu reporte

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

```bash

yarn jsdoc -c jsdoc.json

```

</CH.Code>

Para ver un exemplo de saída podes click arriba onde di Docs ou a través deste [ligazón](https://docs.xabierlameiro.com 'Link to my docs')



# Filtro para posicións, enquisa para comprobar compatibilidade

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

<GoogleAdsense slot="6618374506" horizontal />

## Motivación

Aínda que pareza mentira, debido á alta demanda de desarrolladores de todo tipo no mercado por parte das empresas, moitos recruiters e headhunters volvéronse máquinas do copy paste. Non sei a cifra ou a cantidade diaria de mensaxes que envían a todos os perfís da súa rede que fan "match" coa posición nova que teñen dispoñible, pero apostaría que non son poucos. E non é que non me guste que me envíen mensaxes, pero gustaríame que me enviasen mensaxes que realmente me interesen e que me fagan pensar que viron o meu perfil, o meu código ou algún dos meus traballos e que realmente me queren contratar polas miñas habilidades.

Non adoita ser así, moitos usan programas para automatizar o proceso de procura de perfís como [Hiretual](https://hiretual.com/ 'Hiretual') ou [Jobvite](https://www.jobvite.com/ 'Jobvite'), envían mensaxes a todos os usuarios "que fan match" e en ocasións isto non funciona moi ben. Xa que no teu perfil pon claramente desarrollador Frontend, a túa experiencia di o mesmo... pero, eles teñen unha posición Xava con microservicios incrible para ti.

Outras veces métese a pata e envíanche unha mensaxe co nome do teu compañeiro de equipo:

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

## A idea

Cantas veces tiveches unha chamada con preguntas como:

-   Por que buscas un cambio ?
-   Coñeces os principios SOLID ?
-   Cuantos anos dirías que has traballo con React ? E Typescript ?
-   Sabes o que é a integración continua ?

> Para que despois ofrézanche un salario inferior ao que tes, ou que che pidan o CV para non volver dicirche nunca nada.

How many times bro ?

**_A idea é filtrar ti antes que che filtren a ti._**

## Solución

10 simples preguntas sobre puntos que consideres importantes, requisitos, valores.. ou basicamente o que che de a gana e se se cumpren, o recruiter obterá información de contacto para poder entrar en detalle de todo o proceso.

É un win win, ambos aforramos tempo, non ?

## Código

Cunha compoñente contedora ou páxina, un par de botóns, radiobuttons e un array de objectos tes máis que suficiente, no meu caso:

Teño a miña páxina:

<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>

Meu hook con loxica de negocio:

<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 chegou antes o ovo ou a galiña ?',
            questionHtml: `<h2>¿ Que chegou antes o ovo ou a galiña ?</h2>`,
            answerOptions: [{ answerText: 'Ovo', isCorrect: true, }, { answerText: 'Galiña', 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>

Meu 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 coas respostas" width="822" height="491" />

Proba ti mesmo: [Ligazón ao resultado](https://xabierlameiro.com/survey?name=Lector/a 'Ligazón á enquisa')



# Como publicar o informe de cobertura das probas na túa aplicación React

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

<GoogleAdsense />

Nesta publicación imos ver como publicar o informe de cobertura das probas na súa aplicación React. Para iso utilizaremos:

-   [Jest](https://jestjs.io/ 'Enlace a documentación de Jest')

> Unha "alternativa" perfecta de SonarQube para proxectos pequenos.

Non é habitual nin necesario publicar o teu informe de probas da túa aplicación, incluso haberá quen pense que é algo imprudente porque
pode expor información confidencial da súa aplicación. Pero a idea principal disto é que se tes un proxecto de código aberto e queres
para que a xente poida contribuír, é unha boa idea que poidan ver o informe das probas para que saiban o ben que está cuberto o seu proxecto ou
porque queres ensinarlle á xente a probar unha aplicación.

Non obstante, para ter unha seguridade adicional, é tan sinxelo como telo nun camiño protexido cun nome de usuario e contrasinal.

PD: Este exemplo desenvólvese nunha aplicación web feita con **Nextjs** pero funciona para calquera aplicación web que use
**jest**.

## 1. Ruta para o informe

O primeiro que debemos facer é asignar o jest outputDirectory a un cartafol público

<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 o informe

O que fai este script é modificar a ruta dos ficheiros estáticos que precisa o informe para funcionar como imaxes, css, javascript, etc.
Ademais, algúns textos dos informes están personalizados.

> A alternativa se usas clase é usar a clase [CustomReporter](https://jestjs.io/docs/configuration 'Páxina de configuración de Jest') e implementar o 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 xerar o informe cando se xera a compilación

Para que o informe se xere no cartafol público cando remate a compilación, debemos engadir os seguintes comandos no 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. Crea unha redirección no servidor/plataforma na nube

No meu caso eu uso Vercel pero sexa cal sexa a plataforma que use, debe crear unha redirección para que cando se acceda á 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í podes ver un exemplo de como é o informe de proba deste blog [xabierlameiro.com/coverage](https://coverage.xabierlameiro.com/ 'Sección de cobertura de probas')



# Mostrar o meu storybook é moi sinxelo

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

<GoogleAdsense />

Unha vez que creas os teus compoñentes do Storybook, podes compartilos de varias maneiras. Podes implementar Storybook en Vercel, GitHub ou Netlify ou Heroku e compartir o URL co teu equipo e clientes potenciais.
Tamén podes crear unha versión estática do Storybook e implementala nun servidor web. Isto permíteche ter unha versión do Storybook que está sempre en liña e actualizada.

Storybook é fácil de configurar e xestionar. Necesitarás Node.js e algunhas dependencias de desenvolvemento instaladas para configurar o teu propio ambiente. Tamén podes usar generator-storybook para comezar a crear rapidamente un ficheiro de configuración de Storybook.

Unha vez que configures o teu Storybook, podes comezar a escribir historias para os teus compoñentes. Unha historia é esencialmente unha breve explicación de como se usará o teu compoñente na aplicación. Podes escribir historias para os compoñentes que xa tes
creado e tamén calquera compoñente no que esteas a traballar. Storybook tamén che permite crear variacións do teu compoñente, isto é útil para as probas A/B.

Implementar compoñentes de React con Storybook é unha boa forma de mostrar o teu traballo e garantir que os teus compoñentes estean libres de erros. Permítelle crear guías de estilo en directo para os seus compoñentes e ofrece unha caixa de probas para probalos.
Configurar Storybook pode parecer desalentador, pero é doado se segues a documentación. Unha vez que o teñas configurado, podes comezar a crear historias e variacións dos teus compoñentes e compartilas co teu equipo e clientes potenciais.

## 1. Comandos do storybook

<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. Fai un historial dos teus compoñentes

<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. Implementación do libro de contos

As cousas máis importantes son o comando de compilación, o directorio de saída e o comando de instalación. (fío, npm ou o que sexa) para as 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í podes ver o exemplo do meu libro de contos despregado nun subdominio: [https://storybook.xabierlameiro.com](https://storybook.xabierlameiro.com 'Enlace a storybook.xabierlameiro.com')
