Arquivo package.json e Configuração do Projeto - Node.js

Arquivo package.json

Para facilitar a gestão de configurações e pacotes de uma aplicação no npm, utilizamos o arquivo de configuração package.json. Como vimos anteriormente, o npm cria automaticamente este arquivo (caso não exista) ao instalar um pacote. Se um novo pacote é adicionado ou um pacote já instalado é removido, o npm atualiza o arquivo package.json adequadamente. Contudo, a importância do arquivo package.json também reside no fato de que nós, como desenvolvedores de aplicações, podemos definir manualmente seu conteúdo e gerenciar a configuração do projeto através deste arquivo.

Vamos pegar o arquivo package.json criado anteriormente (ou criar um novo do zero) e definir o seguinte conteúdo:

Aqui, temos três seções definidas:

• name: o nome do projeto. Pode ser qualquer nome. Neste caso, o nome do projeto é "helloapp".

• version: a versão do projeto. Começaremos com a versão 1.0.0.

• dependencies: a seção de dependências. Aqui listamos os pacotes que pretendemos usar e que serão instalados no projeto. As dependências são especificadas como um objeto onde cada propriedade representa o nome do pacote e o valor representa sua versão. Neste exemplo, estamos instalando dois pacotes: "lodash" na versão "4.17.21" e "express" na versão "^4.18.2". Lodash é uma biblioteca para manipulação de dados, especialmente arrays, enquanto express é um framework web leve para facilitar a criação de aplicações web.

  Além disso, as dependências podem ser listadas na seção devDependencies. No entanto, geralmente colocamos na seção devDependencies os pacotes usados durante o desenvolvimento da aplicação, enquanto na seção dependencies ficam os pacotes utilizados durante a execução da aplicação.

Vale destacar que o arquivo package.json pode incluir muitas outras seções. A documentação oficial apresenta todas as seções básicas. Aqui estão algumas das principais, que não foram mencionadas acima:

• description: descrição do pacote.

• main: arquivo principal, aquele onde o código da aplicação começa.

• keywords: array de palavras-chave. Estas palavras podem ser usadas nas buscas no repositório npm.

• homepage: endereço da página inicial do projeto.

• license: licença do pacote.

• author: autor do pacote. Se houver vários autores, indica-se o principal. As informações do autor incluem nome, podendo também incluir email e endereço da página inicial.

• contributors: array contendo outros autores (caso haja mais de um).

• repository: repositório do código-fonte do projeto.

• os: sistemas operacionais suportados.

Agora, vamos instalar os pacotes. Para isso, no terminal, navegue até a pasta do projeto e execute o comando:

c:\app> npm install

Após a instalação, o npm fornecerá um resumo básico dos pacotes instalados. Vale notar que alguns pacotes podem utilizar módulos obsoletos com vulnerabilidades, e o npm apresentará informações sobre tais módulos durante a instalação.

added 63 packages, and audited 64 packages in 4s

11 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Depois disso, os pacotes serão instalados na pasta node_modules e poderemos utilizar suas funcionalidades na aplicação. Vamos definir uma simples aplicação web usando o Express (para simplificar, não usaremos o Lodash, mas um exemplo pode ser encontrado no tema anterior). Para isso, criaremos o arquivo app.js na pasta do projeto com o seguinte código:

const express = require("express"); // obtendo o módulo express
  // criando a aplicação express
  const app = express();
   
  // definindo um handler para a rota "/"
  app.get("/", function(_, response) {
      response.setHeader('Content-Type', 'text/html; charset=utf-8');
      response.end("Hello Programício!");
  });
  // iniciando a escuta de conexões na porta 3000
  app.listen(3000, function() {
      console.log("Servidor iniciado em http://localhost:3000");
  });

A primeira linha carrega o módulo express instalado, e a segunda cria um objeto da aplicação. No Express, podemos associar o tratamento de requisições a determinadas rotas. Por exemplo, a rota / representa a página inicial ou rota raiz. Para tratar a requisição, chamamos a função app.get(). O primeiro parâmetro é a rota, e o segundo é a função que tratará a requisição naquela rota. Assim, ao receber uma requisição na rota raiz /, a aplicação enviará como resposta a string "Hello Programício!".

Para que o servidor comece a escutar conexões, chamamos o método app.listen(), passando o número da porta. O segundo parâmetro desse método é uma função que é executada após o servidor iniciar, no caso, simplesmente exibimos uma mensagem de diagnóstico no console.

Vamos rodar a aplicação com o comando node app.js:

c:\app> node app.js
Servidor iniciado em http://localhost:3000

E, no navegador, vamos acessar o endereço http://localhost:3000/:

SemVer (Versionamento Semântico)

Ao definir a versão de um pacote, utiliza-se o versionamento semântico. O número da versão geralmente segue o formato "major.minor.patch". Se um bug é encontrado e corrigido na aplicação ou pacote, incrementa-se o número "patch". Se uma nova funcionalidade compatível com a versão anterior é adicionada, incrementa-se o número "minor". Se grandes mudanças incompatíveis com a versão anterior são introduzidas, incrementa-se o número "major". Assim, ao olhar para diferentes versões de pacotes, podemos inferir a extensão das mudanças. Por exemplo, considere a versão usada anteriormente do lodash, "4.17.21":

• major: 4

• minor: 17

• patch: 21

No exemplo com o express, a versão do pacote continha o símbolo de acento circunflexo: "^4.18.2". O símbolo ^ permite selecionar qualquer patch dentro da versão major especificada. Assim, ao instalar o pacote no projeto com o comando npm install, será instalada a última versão disponível a partir de 4.18.2. Isso significa qualquer versão disponível no intervalo de 4.18.2 até 5.0.0 (>=4.18.2 e < 5.0.0). Se a última versão disponível for 4.27.8, essa versão será usada.

Também pode-se usar o símbolo ~ como indicador de versão. Ele permite selecionar qualquer patch dentro da versão minor especificada. Por exemplo, a notação "~4.18.2" significa qualquer versão disponível no intervalo de 4.18.2 até 4.19.0 (>=4.18.2 e < 4.19.0).

Alterando e Removendo Pacotes

No decorrer do desenvolvimento de um projeto, pode ser necessário instalar uma versão diferente de um pacote. Por exemplo, uma nova versão de uma biblioteca pode ser lançada e desejamos utilizá-la em nosso projeto no lugar da versão antiga. Ou uma nova versão instalada pode conter bugs ou ser incompatível com outros componentes da aplicação, então optamos por usar uma versão mais antiga. Nesse caso, basta alterar a versão do pacote no arquivo package.json e executar novamente o comando npm install. Este comando removerá a versão antiga do pacote da pasta node_modules e instalará a nova versão.

Se precisarmos remover um pacote, podemos simplesmente excluí-lo da seção dependencies ou devDependencies. Por exemplo, se decidirmos que o pacote "lodash" não é mais necessário, removemos a definição desse pacote do arquivo package.json:

{
  "name": "helloapp",
  "version": "1.0.0",
  "dependencies": {
    "express": "^4.18.2"
  }
}

Depois, executamos o comando npm install no terminal, e o npm apresentará um resumo da remoção do pacote:

c:\app> npm install

removed 1 package, and audited 63 packages in 2s

11 packages are looking for funding
  run `npm fund` for details

found 0 vulnerabilities

Podemos remover todos os pacotes do package.json, e o comando npm install eliminará todos os pacotes instalados. Também é possível adicionar novos pacotes e remover outros simultaneamente.

Podemos combinar com a instalação ou remoção manual de pacotes com o comando npm install ou npm uninstall. Por exemplo, para desinstalar o express, executamos comando:

npm uninstall express

Nesse caso, o npm removerá o pacote express da pasta node_modules, e o arquivo package.json será atualizado automaticamente.

Criando automaticamente o arquivo package.json

O gerenciador de pacotes npm permite criar automaticamente o arquivo package.json com um conjunto básico de configurações. Se ainda não houver um arquivo package.json no projeto, podemos criá-lo executando o comando

c:\app> npm init

O utilitário guiará o usuário na criação do arquivo package.json. Ele cobre apenas os itens mais comuns e tenta adivinhar valores padrão sensatos.

This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sensible defaults.

See `npm help init` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg>` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
package name: (app) helloapp
version: (1.0.0) 
description: 
entry point: (app.js) 
test command: 
git repository: 
keywords: 
author: 
license: (ISC) 
About to write to c:\app\package.json:

{
  "name": "helloapp",
  "version": "1.0.0",
  "description": "",
  "main": "app.js",
  "devDependencies": {},
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

Is this OK? (yes) yes

Durante o processo de criação, o terminal solicitará uma série de informações sobre as configurações, como o nome do projeto, sua versão e outros parâmetros. Podemos simplesmente pressionar Enter sem inserir valores, utilizando os padrões sugeridos. No final, para concluir a criação do arquivo, digitamos "yes". O resultado será a criação do arquivo package.json com o seguinte conteúdo:

{
  "name": "helloapp",
  "version": "1.0.0",
  "description": "",
  "main": "app.js",
  "devDependencies": {},
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

Comandos npm

O npm permite definir comandos no arquivo package.json que executam ações específicas. Por exemplo, definimos o seguinte arquivo app.js:

{
  "name": "helloapp",
  "version": "1.0.0",
  "scripts": {
    "start": "node app.js",
    "dev": "node app.js Tom 26",
    "test": "echo \"Hello www.programicio.com\" && exit 1"
  }
}

Aqui, adicionamos a seção scripts, que define três comandos. Em geral, podemos ter diversos comandos de acordo com os objetivos e necessidades do desenvolvedor.

O primeiro comando é chamado start. Ele essencialmente executa o comando node app.js, que executa o código no arquivo app.js.

O segundo comando é chamado dev. Ele também executa o mesmo arquivo, mas passa dois parâmetros adicionais.

O terceiro comando é chamado test. Ele executa o comando interno echo, que exibe a string "Hello www.programicio.com". Usando o símbolo &&, podemos executar outro comando: neste caso, o comando exit, que encerra a execução.

Os nomes dos comandos podem ser arbitrários. No entanto, há nomes reservados para comandos, como start, test, run e alguns outros. Por exemplo, o primeiro comando no arquivo package.json acima se chama start. Para executar esses comandos no terminal, usamos o comando:

npm [nome_do_comando]

Por exemplo, para executar o comando start:

c:\app> npm start

Para executar o comando test:

c:\app> npm test

Os comandos com outros nomes, como dev no arquivo package.json acima, são executados assim:

npm run [nome_do_comando]

Por exemplo, vamos executar os três comandos sequencialmente:

c:\app> npm start  

> helloapp{1.0.0 start
> node app.js

name: undefined
age: undefined

c:\app> npm run dev

> helloapp{1.0.0 dev
> node app.js Tom 26

name: Tom
age: 26

c:\app> npm test

> helloapp{1.0.0 test
> echo "Hello www.programicio.com"

Hello www.programicio.com