how-to-build-npm-package

Construa seu pacote/biblioteca NPM

De forma fácil e prática! Utilize Javascript / Typescript e React para criar funções, componentes, hooks e etc...

Sobre a aplicação   |    Configurando Ambiente   |    Construindo Pacote   |    Instalação Pacote - LOCAL   |   

Deploy NPM   |    Instalação Pacote - REMOTO   |   

Sobre a aplicação

---

Teve uma ideia de funcionalidade super interessante, quer colocar em prática e disponibilizar para a comunidade usar? A plataforma NPM te dá essa possibilidade. Neste repositório darei os passos para a construção do seu pacote/biblioteca para que possa criar suas Funções, Componentes,Hooks etc, e mostrar para o Mundo! Passo a passo de forma prática e clara.

---

Configurando Ambiente

1. git init

para inicializar o arquivo (.git) de versionamento GIT

git init

2. npm init

para inicializar o arquivo package.json

npm init

• package name: insira aqui o nome do seu projeto. ( todas letras minúsculas)

• version: a versão inicial é a 1.0.0 (pode deixar a que estiver)

• description: descreva resumidamente sobre o que é o seu projeto, do que se trata.

• entry point: nomear o arquivo principal, o arquivo que quando for feita a importação da sua bibilioteca os arquivos serão localizados nele. Pode nomear src/index.js (caso use Javascript) ou src/index.ts (caso use Typescript)

• test command: iremos configurar em outra etapa, deixe em branco.

• git repository: coloque aqui a URL do repositório criado aqui no GitHub para este projeto

• keywords: coloque aqui separado por virgulas, palavras chaves que tenha relação com seu projeto.

• author: insira seu nome, apelido…

• license: nome da licença que dá direito a cópia, reprodução, melhorias etc… Pode colocar MIT.

  • Arquivo package.json ficará assim, por exemplo:

  {
  "name": "how-to-build-npm-package",
  "version": "1.0.0",
  "description": "projeto feito para exemplificar a criação de pacotes/bibliotecas NPM.",
  "main": "index.ts",
  "scripts": {
  "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
  "type": "git",
  "url": "https://github.com/DIGOARTHUR/how-to-build-NPM-package.git"
  },
  "keywords": [
  "NPM",
  "Tutorial",
  "Building",
  "Package"
  ],
  "author": "@digoarthur",
  "license": "MIT",
  "bugs": {
  "url": "https://github.com/DIGOARTHUR/how-to-build-NPM-package/issues"
  },
  "homepage": "https://github.com/DIGOARTHUR/how-to-build-NPM-package#readme",
  }
  

3. Configurando arquivo package.json

Adicione as seguinte propriedades:

• main: Indica o arquivo principal que será utilizado na importação do pacote. Altere o caminho para src/index.ts ou index.js”, assim o import do pacote poderá ser feito apenas pelo o nome dele.

• types: insira o caminho ./dist/index.d.ts. O erro indicando algo sobre a tipagem irá desaparecer.

Acrescente outras propriedades mas agora nos scripts:

• scripts:

  • clean: insira o seguinte código abaixo, é um código bash que apagará a pasta dist no processo de build para que um novo seja criado.

  "clean": "rm -rf dist",
  

  • build: insira o seguinte código abaixo, é um comando que removerá o arquivo dist principal, rodará o typescript, irá mover os arquivos package.json README.md para pasta./dist.

  "build": "npm run clean && tsc && cp package.json README.md ./dist",
  

  • Arquivo package.json ficará assim, por exemplo:

  {
  "name": "how-to-build-npm-package",
  "version": "1.0.0",
  "description": "projeto feito para exemplificar a criação de pacotes/bibliotecas NPM.",
  "main": "/src/index.ts",
  "types": "./dist/index.d.ts",
  "scripts": {
  "clean": "rm -rf dist",
  "build": "npm run clean && tsc && cp package.json README.md ./dist",
  "test": "echo \"Error: no test specified\" && exit 1"
  },
  "repository": {
  "type": "git",
  "url": "git+https://github.com/DIGOARTHUR/how-to-build-NPM-package.git"
  },
  "keywords": [
  "NPM",
  "Tutorial",
  "Building",
  "Package"
  ],
  "author": "@digoarthur",
  "license": "MIT",
  "bugs": {
  "url": "https://github.com/DIGOARTHUR/how-to-build-NPM-package/issues"
  },
  "homepage": "https://github.com/DIGOARTHUR/how-to-build-NPM-package#readme",
  }
  

4. Instalando bibliotecas base

4.1 React

Para criação de Componentes será preciso instalar o React

yarn add -D react

4.2 Typescript

Instalação do Typescript, instale-o e nao se esqueça de instalar os @types React.

yarn add -D typescript

4.2.1 Inicializar o arquivo tsconfig.json

Arquivo responsável pela as configurações do Typescript.

npx tsc --init

Pode copiar e colar essa configurações no arquivo.

{
  "compilerOptions": {
    "strict": true,
    "jsx": "react",
    "declaration": true,
    "esModuleInterop": true,
    "outDir": "dist",
    "target": "es6",
    "module": "es6",
    "lib": ["es6", "dom", "es2017"],
    "moduleResolution": "node"
  },
  "include": ["src/**/*"]
}

4.3 Instalar tipagem React

Instalar a tipagem de funções React por estar utilizando Typescript

yarn add -D @types/react

Estrutura de arquivos/pastas

lib-project
	├── .git (oculto)
	├── node_modules	
	├── package.json
	└── tsconfig.json
 

Construindo Pacote

1. Crie uma pasta source src

As pastas e arquivos de construção de funcionalidades da biblioteca serão colocados aqui.

1.1 Crie as funcionalidades da biblioteca

Voce pode criar, por exemplo:

• Funções
• Componentes
• Hooks
• Etc…

1.2 Crie o arquivo _index.js_ ou _index.ts_, configurado no package.json na propriedade (main), dentro da pasta src.

1.2.1 Exporte aqui as Funções, Componentes, Hooks criados por você, para que seja possivel fazer o import no momento da instalação do seu pacote/biblioteca. Abaixo exemplo da biblioteca criada aqui neste repositório:

export {TableGenerator} from './Components/TableGenerator';
export { Division } from './Math/division/division';
export { Multiplication } from './Math/multiplication/multiplication';
export { Subtraction } from './Math/subtraction/subtraction';
export { Sum } from './Math/sum/sum';

2. Testes (Componentes, Funções, Hooks, etc...)

O teste é opcional mas, como boas práticas, é essecial introduzí-lo nos seus projetos. Aqui é aplicado o Jest. Este teste se tem muito contato direto na plataforma de resolução de algoritmos exercism.org.

2.1 Instalando o Jest e o @types

yarn add -D jest ts-jest @types/jest

2.1.1 Será criado um arquivo jest.config.js

{
module.exports = {
    preset: "ts-jest",
    testEnvironment: "node",
  };
}

2.2 Configurando arquivo package.json

Para rodar o teste será preciso fazer uma configuração na propriedade:

• scripts
  • teste:"jest"

	{
  "name": "how-to-build-npm-package",
  "version": "1.0.0",
  "description": "projeto feito para exemplificar a criação de pacotes/bibliotecas NPM.",
  "main": "/src/index.ts",
  "types": "./dist/index.d.ts",
  "scripts": {
    "clean": "rm -rf dist",
    "build": "npm run clean && tsc && cp package.json README.md ./dist",
    "test": "jest"
  },
  "repository": {
  ...
  ...

Estrutura de arquivos/pastas

lib-project
 ├── .git (oculto)
 ├── node_modules
 ├── `src`
 │    └── `Components`
 │    │   	├── TableGenerator.tsx
 │    │   	├── style.css
 │    │ 
 │    └── `Functions`
 │      │    ├── ...
 │      └── `Hooks`
 │      │    ├── ...
 │      └── `index.ts`
 │
 ├── package.json
 ├── tsconfig.json

4. Criando arquivo para teste

Aqui neste projeto foi criado um arquivo no mesmo local que a função. Padrão do nome: nomeDaFuncao.test.ts , um exemplo aqui, division.teste.ts. Importe a funcão no arquivo criado e então aplique o teste, escrevendo possibilidades do que realmente deve ocorrer caso seja aplicado.

Exemplo de teste:

import { Division } from './division';

test('division two numbers correctly', () => {
  const result = Division(4, 2);
  expect(result).toBe(2);
});

4.2 Rodando teste.

yarn test

Por exemplo

Build

O Build é muito importante após qualquer alteração no código, pois ele gerará os arquivos .js na pasta dist para que seja possivel a intepretação da linguagem Typescript.

Rodar este comando no Git Bash Here que emula um termninal Linux, para que aqueles comandos configurados no package.json possam rodar.

npm run build

Estrutura de arquivos/pastas

lib-project
 ├── .git (oculto)
 ├── `dist`
 ├── node_modules
 ├── src
 │    └── Components
 │    │   	├── TableGenerator.tsx
 │    │   	├── style.css
 │    │ 
 │    └── Functions
 │      │    ├── ...
 │      └── Hooks
 │      │    ├── ...
 │      └── index.ts
 │
 ├── package.json
 ├── tsconfig.json
 

Install Pacote - LOCAL

1. Publicação local

Ainda no Git Bash Here, rode o comando para disponibilizar o pacote de forma local, para que voce possa testá-lo já rondado um projeto React.

npx yalc publish

2. Instalação biblioteca local

Agora na aplicação React, rode o seguinte comando para que possa executar uma instalação local:

npx yalc add <nome da biblioteca>

3. Importe sua biblioteca

As Funções, Componentes, Hooks, etc… são importados daquele arquivo index.js ou index.ts. Aqui um exemplo da biblioteca deste repositório…

import {TableGenerator} from 'how-to-build-npm-package'

Deploy NPM REMOTO

1. Crie uma conta na plataforma NPM

2. Login NPM

No diretório do seu projeto pode ser um CMD, PowerShell, Gitbash e até o terminal do Vscode, rode seguinte comando:

npm login

Aperta ENTER e abrirá uma página de login do NPM, caso nao esteja logado.

3. Publicação Pacote remoto

npm publish

Install Pacote - REMOTO

Agora na aplicação React, rode o seguinte comando para que possa executar uma instalação da sua biblioteca:

yarn add <nome do pacote>

npm install <nome do pacote>

Por que?

Na época que surgiu a ideia de construir uma biblioteca fui atrás de vários tutorias, fontes e etc... Foi aí que nasceu o github-automated-repos. Fiz este repositório como um tutorial que explique da forma mais clara e direta possível, e ainda em Português. Espero que desenvolvam coisas maravilhosas e úteis para a comunidade. Abraços e Sucesso!

---

by: @digoarthur

sources:
freecodecamp.org , pauloe-me.medium , tunmise.medium , dev.to/femi_dev