DEV Community: Gustavo Caetano

Publish Vue components library/npm

Gustavo Caetano — Thu, 22 Aug 2024 19:42:45 +0000

This tutorial contains knowledge from: Link to the blog

The differences between these are corrections of possible errors and more informations about customization of the lib package.

Start Vue+Vite Template

Use npm create vite@latest on the terminal, the following message will be displayed:

Need to install the following packages:
create-vite@5.5.2
Ok to proceed? (y)

Answer with y, the configuration of your project will start:

> npx
> create-vite

? Project name:

Write your Project Name, then select Vue and Typescript:

Select a framework: Vue
Select a variant: TypeScript

If using Typescript, use the following command npm i --save-dev @types/node.

Library mode

To publish your library, let's use the library mode.
Change your vite.config.ts:

import { resolve } from 'path'
import { defineConfig } from 'vite'
import vue from '@vitejs/plugin-vue'

// https://vitejs.dev/config/
export default defineConfig({
  plugins: [vue()],
  build: {
    lib: {
      entry: resolve(__dirname, 'lib/main.ts'),
      name: 'InsertYourLibName', // Change this lib name, ex: 'MyLib'
      // the proper extensions will be added
      fileName: 'InsertFileName' // Change your file name, ex: 'my-lib'
    },
    rollupOptions: {
      // make sure to externalize deps that shouldn't be bundled
      // into your library
      external: ['vue'],
      output: {
        // Provide global variables to use in the UMD build
        // for externalized deps
        globals: {
          vue: 'Vue'
        }
      }
    }
  }
})

Create your components

First, create a lib folder.
This folder will contain all of your components and a file main.ts:

import Component1 from './Component1.vue'
import Component2 from './Component2.vue'
...

export { Component1, Component2, ... }

Import and export all the desired components.

Build component

Change the file package.json to:

{
  "name": "insert-the-lib-name", // Insert the lib name here
  "version": "1.0.0", // Remember to use the version to control
  "type": "module",
  "files": ["dist"],
  "main": "./dist/insert-the-lib-name.umd.cjs", // Insert the lib name here
  "module": "./dist/insert-the-lib-name.js", // lib name here
  "types": "./dist/main.d.ts", 
  "exports": {
    ".": {
      "import": "./dist/insert-the-lib-name.js", // lib name here
      "require": "./dist/insert-the-lib-name.umd.cjs", // lib name here
      "types": "./dist/main.d.ts"
    },
    "./style.css": "./dist/style.css" 
  },
  "scripts": {
    "dev": "vite",
    "build": "vite build && vue-tsc --emitDeclarationOnly", 
    "preview": "vite preview"
  },
  "dependencies": {
    "vue": "^3.2.37"
  },
  "devDependencies": {
    "@types/node": "^18.7.18",
    "@vitejs/plugin-vue": "^3.1.0",
    "typescript": "^4.6.4",
    "vite": "^3.1.0",
    "vue-tsc": "^0.40.4"
  }
}

After, change the tsconfig.json (if the file doens't exist, create it):

{
  "compilerOptions": {
    "target": "ESNext",
    "useDefineForClassFields": true,
    "module": "ESNext",
    "moduleResolution": "Node",
    "strict": true,
    "jsx": "preserve",
    "sourceMap": true,
    "allowSyntheticDefaultImports": true,
    "resolveJsonModule": true,
    "isolatedModules": true,
    "esModuleInterop": true,
    "lib": ["ESNext", "DOM"],
    "skipLibCheck": true,
    "outDir": "dist",
    "declaration": true
  },
  "include": ["lib/**/*.ts", "lib/**/*.d.ts", "lib/**/*.tsx", "lib/**/*.vue"],
  "references": [{ "path": "./tsconfig.node.json" }],
}

Now, update the tsconfig.node.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "lib": ["ES2023"],
    "module": "ESNext",
    "skipLibCheck": true,
    "composite": true,

    /* Bundler mode */
    "moduleResolution": "bundler",
    "isolatedModules": true,
    "moduleDetection": "force",

    /* Linting */
    "strict": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noFallthroughCasesInSwitch": true
  },
  "include": ["vite.config.ts"]
}

To customize your npm Readme, change your README.md file.

Run npm install again and to build the component run npm run build.

Publish

Remember to always update the version on package.json.
Check about semantic versioning here: Link to docs.

Remember to always run npm run build before publishing.

To publish, enter your npm account. If you don't have one, create it.
Run npm adduser and follow the instructions to login.

Finally, to publish your lib, run npm publish.

Go to your account on npm and check on Packages if you have successfully published your package.

Tutorial de utilização Storybook

Gustavo Caetano — Fri, 16 Aug 2024 18:17:17 +0000

Este é um tutorial de utilização. Para o tutorial de instalação, veja: https://dev.to/gustavoacaetano/tutorial-de-instalacao-do-storybook-com-tailwind-324l

Iniciar Storybook

Para iniciar o Storybook, execute o comando:

npm run storybook

Estrutura de arquivos

Após a instalação, os arquivos ficarão dentro da pasta src/stories:

Junto com os arquivos, terá uma pasta assets com todas as imagens utilizadas no arquivo Configure.mdx.

Para melhor organização, recomendo uma estrutura de:

stories/
├─ Bases/
|  ├─ ComponenteBase/
│  |  ├─ ComponenteBase.vue
│  |  ├─ ComponenteBase.stories.ts
│  |  ├─ ComponenteBase.css
├─ Complexos/
|  ├─ ComponenteComplexo/
│  |  ├─ ComponenteComplexo.vue
│  |  ├─ ComponenteComplexo.stories.ts
│  |  ├─ ComponenteComplexo.css

Porém, sinta-se livre para utilizar da forma que melhor se encaixa no seu projeto.

Arquivo de documentação (.mdx)

O arquivo Configure.mdx contém informações sobre o Storybook. Se deseja criar um arquivo semelhante para documentação, substitua o arquivo Configure.mdx por um arquivo NomeDoArquivo.mdx:

import { Meta } from "@storybook/blocks";

<Meta title="Título na sidebar" />

<div className="sb-container">
  <div className='sb-section-title'>
    # Titulo da página

    Esse Storybook contém os componentes utilizados no projeto NomeDoProjeto.
  </div>
</div>

<style>
  {`
  .sb-container {
    margin-bottom: 48px;
  }

  .sb-section-title {
    margin-bottom: 32px;
  }
  `}
</style>

Após, personalize o arquivo da forma que preferir.

Se estiver vendo este erro:

Clique na opção com o novo título na sidebar.

Sidebar do Storybook

A estrutura dos arquivos, por enquanto, impactará somente na forma de trabalhar na IDE. Para modificar a sidebar do Storybook existem diferentes formas.

Inicialmente, sua sidebar estará parecida com esta imagem:

Dentro do arquivo Componente.storie.ts, pode-se alterar a estrutura da sidebar através do title:

...
const meta = {
  title: 'Pasta1/Pasta2/Componente',
...

Exemplo:

const meta = {
  title: 'Componentes/Complexos/Header',

Para diferentes formas de alteração, veja o vídeo do canal da Chromatic:
https://www.youtube.com/watch?v=zrdcCSTGo4A

Desenvolvimento com Storybook

O objetivo do desenvolvimento com o Storybook é isolar componentes e trabalhar de forma individualizada para reuso.

Quando estiver desenvolvendo, o arquivo Componente.vue deve ser o componente do seu trabalho. O Storybook servirá para testar seu componente através do Componente.stories.ts.

Esse arquivo será composto da seguinte forma:

// IMPORTACOES
import type { Meta, StoryObj } from '@storybook/vue3';
import { fn } from '@storybook/test';
import Componente from './Componente.vue';

// METADATA PARA CONSTRUCAO DO COMPONENTE
const meta = {
  title: 'Componentes/Bases/Componente',
  component: Componente,
  tags: ['autodocs'],
  argTypes: {
    argumento: tipo,
    ...
  },
  args: {
    argumento: valor,
    ...
    // Para os eventos, adicione o fn() para monitorar
    // e apresentar o evento na aba 'Actions'
    onEventoComponente: fn()
  },
} satisfies Meta<typeof Componente>;
export default meta;

E no final do arquivo, ficarão os Stories, que são casos de uso do componente.
Utilize os argumentos do componente para criar os diferentes casos.

// CASOS DE USO
type Story = StoryObj<typeof meta>;
export const FirstStory: Story = {
  args: {
    argumento: valor,
    ...
  },
};

export const SecondStory: Story = {
  args: {
    argumento: valor,
    ...
  },
};

Para cada Story, pode-se acompanhar no Storybook o visual e relacionados de cada componente.

Os controles ajudam a realizar ajustes nos casos de uso por meio da interface. Essas mudanças podem ser salvas no código posteriormente:

Utilize o fn() no código dos eventos do componente para acompanhar se os eventos estão sendo disparados na aba Actions:

Expanda a Action para visualizar os parâmetros, isso será útil para ações específicas que podem aparecer em certos componentes:

Documentação de componentes

A documentação dos componentes também é feita por arquivos .mdx.

Arquivo Componente.mdx:

import { Meta, Story, Canvas } from '@storybook/blocks';
import * as ComponenteStories from './Componente.stories';

<Meta title="Componente" of={ComponenteStories} />

# Componente
Teste `MDX` para documentar o componente `Componente`. Para mais sobre a documentação de componentes: <br/>
https://storybook.js.org/addons/@storybook/addon-docs

<Canvas>
  <Story of={ComponenteStories} />
</Canvas>

Mais informações

Para mais informações e detalhes gerais, consulte a documentação oficial do Storybook:
https://storybook.js.org/docs

Veja também o canal da Chromatic no YouTube:
https://www.youtube.com/@chromaticui

Tutorial de instalação do Storybook com Tailwind

Gustavo Caetano — Wed, 19 Jun 2024 00:10:31 +0000

Instalação Storybook

Na pasta do seu projeto, execute o comando no terminal:

npx storybook@latest init

Você deverá ver o seguinte texto no terminal:

Need to install the following packages:
storybook@8.1.10
Ok to proceed? (y)

Responda com y.

O Storybook deve detectar se o seu projeto utiliza Vite ou Webpack:

Adding Storybook support to your "Vue 3" app 
• Detected Vite project. 
Setting builder to Vite.

Se isso não acontecer, selecione a ferramenta utilizada no seu projeto nas opções que aparecerão no terminal.

Instalação Tailwind

Na pasta do projeto, instale o tailwind e outras dependências:

npm install -D tailwindcss@latest postcss@latest autoprefixer@latest

Utilize o seguinte comando para gerar os arquivos tailwind.config.js e postcss.config.js:

npx tailwindcss init -p

Arquivo tailwind.config.js:

export default {
  content: [],
  theme: {
    extend: {},
  },
  plugins: [],
}

Altere o arquivo na segunda linha para:

content: ['./index.html', './src/**/*.{vue,js,ts,jsx,tsx}'],

OBS: Certifique-se de que o caminho './src/**/*.{vue,js,ts,jsx,tsx}' esteja de acordo com a sua estrutura de arquivos!

Arquivo postcss.config.js:

export default {
  plugins: {
    tailwindcss: {},
    autoprefixer: {},
  },
}

Crie o arquivo ./src/index.css e inclua o Tailwind base, components e utilities styles
Arquivo ./src/index.css:

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

Agora, importe o ./src/index.css no ./src/main.js:

import './index.css'

Integrando Tailwind e Storybook

Se estiver usando Webpack, execute o comando:

npx storybook@latest add @storybook/addon-styling-webpack

Para todos os casos (Vite ou Webpack), vá ao arquivo ./storybook/preview.js e adicione:

import '../src/index.css';

E, assim, seus stories estarão integrados com o Tailwind!

Fixtures do Cypress para testes

Gustavo Caetano — Fri, 07 Jun 2024 16:58:53 +0000

Conhecimentos prévios

Cypress, Cucumber, BDD

Veja a aplicação no Slave One:
https://dev.to/marcela_lage_094e814c6a4e/documentacao-dos-testes-do-sistema-slave-one-2kmb

Fixtures

As fixtures do Cypress são dados estáticos que podem ser utilizados pelos testes. O arquivo é em formato JSON.

Intercept

O intercept é um comando do Cypress que pode ser usado para capturar, vigiar ou modificar uma requisição.
Link da documentação

Testes com os dados da fixture

Inicialmente, deve-se criar os arquivos de fixture que terão os dados utilizados na página.

A estrutura do JSON deve ser a mesma da resposta da requisição.

Para encontrar qual requisição interceptar, execute seu teste Cypress e observe-se no passo a passo qual requisição retorna os dados que pretende substituir.

Após, deve-se capturar e alterar a resposta usando o intercept:

O intercept trocará a resposta da requisição https://localhost:3000/api/Function pela fixture do arquivo Function e o comando as permitirá que o Cypress acesse essa ação pelo wait para esperar que a mudança aconteça.

OBS: o intercept deve ser usado antes da requisição acontecer e o wait deve ser utilizado após. No exemplo, o clique de elements.functionPageBtn().click() precede a requisição.

Dessa forma, os dados das fixtures estarão sendo utilizados para aplicação. Para que funcione sem nenhum dado, utilize o intercept em todas as requisições, mesmo aquelas que não retornam dados para apresentar na tela.

Exemplos:

Nessa função, são feitas duas interceptações. A primeira, retorna um JSON vazio para que a página entenda que a ação de deletar foi concluída com sucesso.
FunctionDeleteComplete.json

FunctionAfterDelete.json

Resultado final: