Como usar os módulos do Node.js com o npm e o package.json

Criando um arquivo package.json

Como um arquivo package.json contém várias propriedades, pode ser complicado criá-lo manualmente, sem copiar e colar um modelo de outro lugar. Para facilitar as coisas, o npm fornece o comando init. Este é um comando interativo que faz uma série de perguntas e cria um arquivo package.json com base em suas respostas.

Como usar o comando init

Primeiro, monte um projeto para que você possa praticar o gerenciamento de módulos. No seu shell, crie uma nova pasta chamada locator:

mkdir locator && cd locator && npm init

Você receberá o seguinte resultado:

Output
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 json` 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: (locator)

Primeiro, será solicitado o name (nome) do seu novo projeto. Por padrão, o comando supõe que este seja o nome da pasta em que você está. Os valores padrão para cada propriedade são mostrados entre parênteses (). Como o valor padrão para o name irá funcionar para este tutorial, pressione ENTER para aceitá-lo.

O próximo valor a ser adicionado é version (versão). Junto com o name, este campo é necessário caso seu projeto seja compartilhado com outros no repositório de pacotes do npm.

Nota: espera-se que os pacotes do Node.js sigam o guia Versionamento semântico (semver). Portanto, o primeiro número será o número de versão MAJOR, que muda somente quando a API muda. O segundo número será da versão do MINOR, que muda quando funcionalidades são adicionadas. O último número será da versão do PATCH, que muda quando bugs são consertados.

Instalando módulos

npm install axios --save

Você inicia este comando com o npm install, que instalará o pacote (para ser conciso, pode utilizar o npm i). Então, liste os pacotes que deseja que sejam instalados, separados por um espaço. Neste caso, trata-se do axios. Por fim, você termina o comando com o parâmetro opcional --save, que especifica que o axios será salvo como uma dependência do projeto.

Quando a biblioteca for instalada, você verá um resultado similar ao seguinte:

Output
...
+ axios@0.19.0
added 5 packages from 8 contributors and audited 5 packages in 0.764s
found 0 vulnerabilities

Agora, visualizando o arquivo package.json Você verá uma nova propriedade, assim como destacado a seguir:

"dependencies": {
    "axios": "^0.19.0"
  }

cat package.json

A opção --save disse ao npm para atualizar o package.json com o módulo e versão que acabou de ser instalada. Isso é ótimo, já que outros desenvolvedores trabalhando em seus projetos podem ver facilmente quais dependências externas são necessárias.

Nota: você deve ter notado o ^ antes do número de versão para a dependência do axios. Lembre-se que o versionamento semântico consiste em três dígitos: MAJOR, MINOR e PATCH. O símbolo de ^ significa que qualquer versão superior do MINOR ou do PATCH atenderia a essa restrição de versão. Caso veja ~ no início de um número de versão, então apenas versões superiores do PATCH satisfazem a restrição.

Dependências de desenvolvimento

Instale um linter como uma dependência de desenvolvimento para seu projeto. Experimente isto em seu shell:

npm i eslint@6.0.0 --save-dev

Neste comando, você usou o sinalizador --save-dev. Isso salvará o eslint como uma dependência que é necessária apenas para o desenvolvimento. Note também que você adicionou @6.0.0 ao nome da sua dependência. Quando os módulos são atualizados, eles são marcados com uma versão. O @ diz ao npm para procurar um sinalizador específico do módulo que você está instalando. Sem um sinalizador especificado, o npm instala a versão marcada mais recente. Abra o package.json novamente:

cat package.json

Isso mostrará o seguinte:

"devDependencies": {
    "eslint": "^6.0.0"
  }

O eslint foi salvo como uma devDependencies, junto com o número da versão que você especificou mais cedo.

Arquivos gerados automaticamente: node_modules e package-lock.json

Quando você instala um pacote em um projeto do Node.js pela primeira vez, o npm cria automaticamente a pasta node_modules. Ela é usada para armazenar os módulos necessários para o seu projeto e o arquivo package-lock.json

Confirme que eles estão em seu diretório de trabalho. Em seu shell, digite ls e pressione ENTER. Você observará o seguinte resultado:

Output
node_modules    package.json    package-lock.json

A pasta node_modules contém todas as dependências instaladas para o seu projeto. Na maioria dos casos, você não deve enviar essa pasta em seu repositório controlado por versão. Conforme instala mais dependências, o tamanho dessa pasta crescerá rapidamente. Além disso, o arquivo package-lock.json mantém um registro das versões exatas instaladas de uma maneira mais sucinta. Assim, incluir o node_modules não é necessário.

Enquanto o arquivo package.json lista as dependências que nos informam as versões adequadas que devem ser instaladas para o projeto, o arquivo package-lock.json acompanha todas as alterações no package.json ou node_modules e nos informa a versão exata do pacote instalado. Normalmente, você envia isso para seu repositório controlado por versão, ao invés do node_modules, pois é uma representação mais clara de todas as suas dependências.

Como instalar a partir do package.json

Usando seus arquivos package.json e package-lock.json, você consegue configurar rapidamente as mesmas dependências de projeto antes de iniciar o desenvolvimento de um novo projeto. Para demonstrar isso, suba um nível em sua árvore de diretórios e crie uma nova pasta chamada cloned_locator no mesmo nível de diretório que o locator:

cd ..
mkdir cloned_locator
cd cloned_locator

Agora, copie os arquivos package.json e package-lock.json da pasta locator para cloned_locator:

cp ../locator/package.json ../locator/package-lock.json .

Para instalar os módulos necessários para este projeto, digite:

npm i

O npm verificará se há um arquivo package-lock.json para instalar os módulos. Caso nenhum arquivo lock esteja disponível, ele leria a partir do arquivo package.json para determinar as instalações. Normalmente, é mais rápido instalar a partir do package-lock.json, pois o arquivo lock contém a versão exata dos módulos e suas dependências. Isso significa que o npm não precisa gastar tempo para descobrir uma versão adequada para instalar.

Ao implantar para a produção, pode ser que queira ignorar as dependências de desenvolvimento. Lembre-se que as dependências de desenvolvimento são armazenadas na seção devDependencies do package.json e não têm impacto na execução do seu aplicativo. Ao instalar módulos como parte do processo CI/CD para implantar o seu aplicativo, omita as dependências de desenvolvimento, executando:

npm i --production

O sinalizador --production ignora a seção devDependencies durante a instalação. Por enquanto, permaneça com sua compilação de desenvolvimento.

Antes de ir para a seção seguinte, volte para a pasta locator:

cd ../locator

Instalações globais

Até agora, você esteve instalando os módulos npm para o projeto locator. O npm também permite que você instale pacotes globalmente. Isso significa que o pacote está disponível para seu usuário no sistema como um todo, assim como qualquer outro comando do shell . Essa habilidade é útil para os muitos módulos do Node.js que são ferramentas CLI.

Por exemplo, pode ser que queira fazer postagens em blog sobre o projeto locator no qual você está trabalhando atualmente. Para fazer isso, utilize uma biblioteca como o Hexo para criar e gerenciar seu site de blog estático. Instale o Hexo CLI globalmente, desta forma:

npm i hexo-cli -g

Para instalar um pacote globalmente, você adiciona o sinalizador -g ao comando.

Nota: se receber um erro de permissão ao tentar instalar este pacote globalmente, seu sistema pode exigir privilégios de super-usuário para executar o comando. Tente novamente com sudo npm i hexo-cli -g.

Teste se o pacote foi instalado com sucesso, digitando:

hexo --version

Até agora, você aprendeu como instalar os módulos com o npm. É possível instalar os pacotes em um projeto localmente, seja como uma dependência de produção ou de desenvolvimento. Você também pode instalar pacotes com base nos arquivos package.json ou package-lock.json pré-existentes, permitindo que desenvolva com as mesmas dependências que seus pares. Por fim, você pode utilizar o sinalizador -g para instalar os pacotes globalmente. Assim, você pode acessá-los independentemente se estiver em um projeto Node.js, ou não.

Gerenciando módulos, como listar módulos

Caso queira saber quais módulos estão instalados em um projeto, é mais fácil usar uma list (lista), ou ls, ao invés de ler o package.json diretamente. Para fazer isso, digite:

npm ls

Por padrão, o ls mostra toda a árvore de dependências — os módulos dos quais seu projeto depende e os módulos dos quais suas dependências dependem. Isso pode ser um pouco complicado caso queira um panorama de alto nível sobre o que está instalado.

Para imprimir apenas os módulos que você instalou, sem as suas dependências, digite o seguinte em seu shell:

npm ls --depth 0

A opção --depth permite que você especifique qual nível da árvore de dependências quer usar. Quando ele é 0, você verá apenas suas dependências de nível superior.

Como atualizar módulos

É uma boa prática manter seus módulos do npm atualizados. Isso melhora sua probabilidade de obter os ajustes de segurança mais recentes para um módulo. Use o comando outdated para verificar se algum módulo pode ser atualizado:

npm outdated

Você receberá um resultado como o seguinte:

Output
Package  Current  Wanted  Latest  Location
eslint     6.0.0   6.7.1   6.7.1  locator

Este comando lista primeiro o Package (pacote) que está instalado e a versão Current (atual). A coluna WANTED mostra qual versão satisfaz sua exigência de versão no package.json. A coluna Latest mostra a versão mais recente publicada do módulo.

A coluna Location declara onde o pacote está localizado na árvore de dependências. O comando outdated tem o sinalizador --depth, assim como ls. Por padrão, o depth é 0.

Parece que você pode atualizar o eslint para uma versão mais recente. Use o comando update ou up, desta forma:

npm up eslint

Caso quisesse atualizar todos os módulos de uma só vez, digitaria:

npm up

Como excluir módulos

O comando npm uninstall é capaz de remover módulos dos seus projetos. Isso significa que o módulo já não estará mais instalado na pasta node_modules. Além disso, ele também não será visto em seus arquivos package.json e package-lock.json.

Remover dependências de um projeto é uma atividade normal no ciclo de desenvolvimento de software. Uma dependência pode não resolver o problema como anunciado, ou não fornecer uma experiência de desenvolvimento satisfatória. Nestes casos, é melhor desinstalar a dependência e compilar seu próprio módulo.

Imagine que o axios não forneça a experiência de desenvolvimento que você gostaria de ter ao fazer solicitações HTTP. Desinstale o axios com o comando uninstall ou un, digitando:

npm un axios

Ele não diz explicitamente que o axios foi removido. Para verificar se ele foi desinstalado, liste as dependências novamente:

npm ls --depth 0

Como auditar módulos

O npm fornece um comando audit (auditoria) para destacar possíveis riscos de segurança em suas dependências. Para ver a auditoria em ação, instale uma versão desatualizada do módulo de solicitação, executando o seguinte:

npm i request@2.60.0 && npm audit

O comando audit mostra tabelas resultantes destacando falhas de segurança

É possível ver o caminho da vulnerabilidade e, às vezes, o npm oferece maneiras para corrigi-la. Você pode executar o comando de atualização como sugerido, ou executar o subcomando fix do audit. Em seu shell, digite:

npm audit fix

Você pode utilizar o parâmetro --force para garantir que as vulnerabilidades se foram, desta forma:

npm audit fix --force