Desenvolver uma biblioteca JavaScript pode ser um processo simples e eficiente quando se utiliza ferramentas modernas como o Vite. Este guia abordará como configurar e publicar sua própria biblioteca, desde a configuração inicial até o empacotamento e publicação no NPM.

Pré-requisitos

Antes de começarmos, certifique-se de ter:

  • Node.js instalado (versão 14 ou superior).
  • Gerenciador de pacotes como npm ou Yarn.
  • Familiaridade com JavaScript ou TypeScript.

1. Inicializando o Projeto

Crie uma pasta para sua biblioteca e inicialize um novo projeto Node.js:

mkdir minha-biblioteca
cd minha-biblioteca
npm init -y

Isso criará um arquivo package.json com as configurações básicas do seu projeto.

2. Instalando o Vite e Configurações Básicas

Instale o Vite e outras dependências necessárias:

npm install vite --save-dev
npm install typescript --save-dev

Em seguida, crie um arquivo de configuração do Vite na raiz do projeto:

// vite.config.ts
import { defineConfig } from 'vite';
import dts from 'vite-plugin-dts';

export default defineConfig({
  build: {
    lib: {
      entry: 'src/index.ts',
      name: 'MinhaBiblioteca',
      fileName: (format) => `minha-biblioteca.${format}.js`,
    },
    rollupOptions: {
      external: ['react'],
      output: {
        globals: {
          react: 'React',
        },
      },
    },
  },
  plugins: [dts()],
});

O que cada configuração faz?

  • entry: Define o arquivo principal da sua biblioteca.
  • external: Exclui dependências como react do pacote final.
  • plugins: Usa o vite-plugin-dts para gerar declarações TypeScript automaticamente.

3. Estrutura de Pastas e Arquivos

Organize seu projeto para manter a consistência e facilitar a manutenção:

minha-biblioteca/
├── src/
│   ├── components/
│   │   └── MeuComponente.tsx
│   ├── utils/
│   │   └── helpers.ts
│   └── index.ts
├── package.json
├── tsconfig.json
├── vite.config.ts
├── scripts/
│   └── generate-package-json.js
└── README.md

Exemplo de Código

src/index.ts

export * from './components/MeuComponente';
export * from './utils/helpers';

src/components/MeuComponente.tsx

import React from 'react';

type Props = {
  title: string;
};

export const MeuComponente: React.FC<Props> = ({ title }) => {
  return <h1>{title}</h1>;
};

4. Configuração do TypeScript

Adicione um arquivo tsconfig.json com a seguinte configuração:

{
  "compilerOptions": {
    "target": "ESNext",
    "module": "ESNext",
    "declaration": true,
    "declarationDir": "dist",
    "outDir": "dist",
    "strict": true,
    "jsx": "react-jsx",
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Isso garante que o TypeScript gerará arquivos .d.ts para sua biblioteca.

5. Gerando um package.json para a Build

Crie um script para gerar um arquivo package.json na pasta dist:

scripts/generate-package-json.js

import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'fs';
import { resolve } from 'path';

const packageJsonPath = resolve('./package.json');
const distPackageJsonPath = resolve('./dist/package.json');

const packageJson = JSON.parse(readFileSync(packageJsonPath, 'utf8'));

const { name, version, description, author, license, dependencies, peerDependencies } = packageJson;
const newPackageJson = {
  name,
  version,
  description,
  main: 'main.js',
  types: 'main.d.ts',
  author,
  license,
  dependencies,
  peerDependencies,
};

if (!existsSync(resolve('./dist'))) {
  mkdirSync(resolve('./dist'));
}

writeFileSync(distPackageJsonPath, JSON.stringify(newPackageJson, null, 2), 'utf8');

console.log('package.json gerado na pasta dist com sucesso.');

Adicione o script ao comando de build no package.json:

"scripts": {
  "build": "tsc -p ./tsconfig.build.json && vite build && node scripts/generate-package-json.js",
  "prepublishOnly": "npm run build"
}

O comando prepublishOnly garante que o pacote será construído antes de ser publicado.

6. Testando sua Biblioteca

Instale ferramentas de teste, como Jest ou Vitest:

npm install vitest --save-dev

Configure um arquivo de teste para validar os componentes e utilitários:

src/components/MeuComponente.test.tsx

import { render, screen } from '@testing-library/react';
import { MeuComponente } from './MeuComponente';

test('deve renderizar o título corretamente', () => {
  render(<MeuComponente title="Olá, mundo!" />);
  expect(screen.getByText('Olá, mundo!')).toBeInTheDocument();
});

Execute os testes:

npx vitest

7. Empacotando e Publicando

Publique sua biblioteca no NPM, navegue para a pasta de build do projeto e utilize o comando:

npm publish

Nota: Certifique-se de que a versão no package.json seja atualizada antes de cada publicação.

8. Boas Práticas

  • Versionamento Semântico: Use versões do tipo MAJOR.MINOR.PATCH para indicar mudanças.
  1. MAJOR: Quando alguma alteração deixe a API incompatível com códigos anteriores.
  2. MINOR: Quando você adiciona alterações que são compatíveis com versões anteriores.
  3. PATCH: Quando você faz correções e pequenos ajustes compatíveis com versões anteriores.
  • Documentação Clara: Inclua um README com instruções de instalação, uso e exemplos.
  • Testes Automatizados: Garanta a qualidade do código com testes robustos.

9. Conclusão

Criar uma biblioteca com Vite é uma maneira eficiente de compartilhar componentes e utilitários entre projetos. Com uma configuração robusta e boas práticas, você pode garantir que sua biblioteca seja fácil de usar e manter.