Como melhorar o package.json do seu projeto
Tags: javascript, node, npm, typescript
Published: 2020-07-11 19:03:31

<p>
Vamos falar sobre como deixar o seu <code>package.json</code> mais detalhado e com mais informações sobre o seu projeto. Isso pode ser muito útil se você estiver desenvolvendo uma library ou outro projeto open source.
</p>

<hr/>

<h1>Primeiros Passos</h1>

<p>
Para começar, eu criei um projeto utilizando o npm. Estou usando o Linux, mas os comandos são os mesmos para macOS e Windows.
</p>
<pre>
<b>$ mkdir</b> minhaapi
<b>$ cd</b> minhaapi
<b>$ npm init</b> -y
</pre>

<p>Podemos perceber que o <code>package.json</code> foi criado. Ele deve estar desta forma:</p>
<pre>
{
  <b>"name"</b>: <i>"minhaapi"</i>,
  <b>"version"</b>: <i>"1.0.0"</i>,
  <b>"description"</b>: <i>""</i>,
  <b>"main"</b>: <i>"index.js"</i>,
  <b>"scripts"</b>: {
    <b>"test"</b>: <i>"echo \"Error: no test specified\" && exit 1"</i>
  },
  <b>"keywords"</b>: <i>[]</i>,
  <b>"author"</b>: <i>""</i>,
  <b>"license"</b>: <i>"ISC"</i>
}
</pre>

<h1>Configurações Básicas</h1>
<p>Agora vamos falar sobre as informações básicas do <code>package.json</code>.</p>
<ol>
  <li>
    <h2>name</h2>
    <p>O nome da chave já fala por si só. Aqui você deve colocar o nome da sua aplicação, por exemplo:</p>
<pre>
<b>"name"</b>: <i>"minhaapi"</i>
</pre>
  </li>

  <li>
    <h2>version</h2>
    <p>Neste campo você deve colocar a versão da sua aplicação.</p>
<pre>
<b>"version"</b>: <i>"0.1.0"</i>
</pre>
<p><a href="https://semver.org/lang/pt-BR/">Aqui você pode conferir mais detalhes sobre versionamento semântico.</a></p>
  </li>

  <li>
    <h2>description</h2>
    <p>Coloque aqui uma descrição do seu projeto, não precisa ser um texto longo.</p>
<pre>
<b>"description"</b>: <i>"API for data on COVID-19"</i>
</pre>
  </li>
</ol>

<hr/>

<h1>Configurações da Aplicação</h1>
<p>Nesta parte você pode colocar informações importantes acerca da execução do seu projeto.</p>

<ol>
<li>
<h2>main</h2>
<p>Use o <code>main</code> para indicar o ponto de entrada da sua aplicação.</p>
<pre>
<b>"main"</b>: <i>"index.js"</i>
</pre>
</li>

<li>
<h2>scripts</h2>
<p>Essa parte é bem importante, aqui você pode adicionar scripts com comandos uteis para sua aplicação.</p>

<p>Você pode adicionar scripts para iniciar a aplicação em modo de desenvolvimento, rodar testes, migrations, seeds, realizar o build etc.</p>

<pre>
<b>"scripts"</b>: {
  <b>"start"</b>: <i>"nodemon</i>",
  <b>"knex:migrate"</b>: <i>"knex migrate:latest"</i>,
  <b>"knex:seed"</b>: <i>"knex seed:run"</i>,
  <b>"test"</b>: <i>"jest"</i>,
  <b>"build"</b>: <i>"node index.js"</i>
}
</pre>
<p>Após isso, basta rodar no terminal: <code>npm run nome_do_script</code> ou <code>yarn nome_do_script</code>.</p>
</li>

<li>
<h2>dependencies</h2>
<p>Aqui não tem muito o que alterar, quando você instala alguma dependência com <code>npm install dependência</code> ou <code>yarn add dependência</code>, são adicionadas neste campo automaticamente as dependências necessárias para sua aplicação funcionar em produção.</p>

<pre>
<b>"dependencies"</b>: {
  <b>"express"</b>: <i>"^4.17.1"</i>,
  <b>"knex"</b>: <i>"^0.21.1"</i>,
  <b>"sqlite3"</b>: <i>"^4.2.0"</i>
}
</pre>
</li>

<li>
<h2>devDependencies</h2>
<p>Seguindo a lógica do campo <code>dependencies</code>, aqui são descritas as dependências utilizadas no desenvolvimento da aplicação. Essas dependências são desnecessárias em ambiente de produção.</p>
<p>Elas são adicionadas com <code>npm install dependência -D</code> ou <code>yarn add dependência -D</code>.</p>

<pre>
<b>"devDependencies"</b>: {
  <b>"jest"</b>: <i>"^25.2.6"</i>,
  <b>"nodemon"</b>: <i>"^2.0.2"</i>,
  <b>"supertest"</b>: <i>"^4.0.2"</i>
}
</pre>
</li>

<li>
<h2>engines</h2>
<p>Nessa parte você pode especificar quais versões do node e do npm são compatíveis com sua aplicação.</p>

<pre>
<b>"engines"</b> : {
  <b>"node"</b> : <i>">=10.21.0"</i>
}
</pre>
</li>

<li>
<h2>os</h2>
<p>Você pode especificar aqui quais são os sistemas operacionais compatíveis com o seu projeto. Pode também informar quais não são compatíveis.</p>

<pre>
<b>"os"</b> : [ <i>"!darwin"</i>, <i>"linux"</i>, <i>"win32"</i>]
<i>// Ao usar "!" antes da plataforma, você informa que ela não é suportada</i>
</pre>

<p>As plataformas disponíveis são todos os possíveis resultados do global <code>process.plataform</code>.</p>
<p><a href=https://nodejs.org/docs/latest-v12.x/api/process.html#process_process_platform">Para mais informações, confira a documentação do Node.js.</p>
</li>

<li>
<h2>cpu</h2>
<p>Da mesma forma você pode informar quais arquiteturas são compatíveis e quais não são compatíveis com sua aplicação.</p>
<pre>
<b>"cpu"</b> : [ <i>"x64"</i>, <i>"arm"</i>, <i>"ia32"</i>, <i>"!mips"</i> ]
</pre>
<p>As arquiteturas que podem ser informadas são todos os possíveis resultados do global <code>process.arch</code>.</p>
<p><a href="https://nodejs.org/docs/latest-v12.x/api/process.html#process_process_arch">Para mais informações, consulte a documentação do Node.js.</a></p>
</li>
</ol>

<hr/>

<h1>Informações sobre Repositórios, Licença e Autoria</h1>
<ol>
<li>
<h2>homepage</h2>
<p>Você pode colocar a URL da página do seu projeto. Pode ser o readme do seu repositório no Github.</p>
<pre>
<b>"homepage"</b>: <i>"https://github.com/weltonfelix/minhaapi#--------"</i>
</pre>
</li>

<li>
<h2>bugs</h2>
<p>Aqui é onde você informa o local onde o usuário pode reportar bugs, como a página de issues do seu repositório, e seu e-mail.</p>
<pre>
<b>"bugs"</b>: {
  <b>"url"</b> : <i>"https://github.com/weltonfelix/minhaapi/issues"</i>,
  <b>"email"</b> : <i>"contato.weltonf@gmail.com"</i>
}
</pre>
<p>ou você pode informar apenas uma URL:</p>
<pre>
<b>"bugs"</b>: <i>"https://github.com/weltonfelix/minhaapi/issues"</i>
</pre>
</li>

<li>
<h2>license</h2>
<p>Agora você pode adicionar a sua licença. Pode ser uma licença comum, como a MIT, Apache-2.0…</p>
<pre>
<b>"license"</b>: <i>"MIT"</i>
</pre>
<p>ou uma licença customizada.</p>
<pre>
<b>"license"</b>: <i>"SEE LICENSE IN LICENSE.md"</i>
</pre>
<p>Você também pode usar <code>UNLICENSED</code> para informar que seu projeto é privado.</p>
<pre><b>"license"</b>: <i>"UNLICENSED"</i></pre>
<p><a href="https://spdx.org/licenses/">Nesta página você encontra todas as licenças comuns que podem ser utilizadas.</a></p>
</li>

<li>
<h2>private</h2>
<p>Você pode adicionar esse campo se estiver desenvolvendo um projeto privado, ele previne que o pacote seja publicado acidentalmente.</p>
<pre>
<b>"private"</b>: <i>true</i>
</pre>
</li>

<li>
<h2>author</h2>
<p>O <code>author</code> é o principal responsável pelo projeto, somente uma pessoa pode ser informada nesse campo.</p>
<p>O nome é obrigatório, você também pode adicionar e-mail e URL.</p>
<pre>
<b>"author"</b>: {
  <b>"name"</b> : <i>"Welton Felix"</i>,
  <b>"email"</b> : <i>"contato.weltonf@gmail.com"</i>,
  <b>"url"</b> : <i>"https://github.com/weltonfelix"</i>
}
</pre>
<p>Você também pode informar o autor de forma mais simples:</p>
<pre>
<b>"author"</b>: <i>"Welton Felix <contato.weltonf@gmail.com> (https://github.com/weltonfelix)"</i>
</pre>
</li>

<li>
<h2>contributors</h2>
<p>Aqui você pode informar as pessoas que contribuíram no desenvolvimento do projeto. Podem ser inseridas as mesmas informações do campo <code>author</code>.</p>
<pre>
<b>"contributors"</b>: [
  {
    <b>"name"</b>: <i>"Ross Cordova"</i>,
    <b>"email"</b>: <i>"rosscordova@outlook.com"</i>,
    <b>"url"</b>: <i>"https://rosscordova.com"</i>
  },
  {
    <b>"name"</b>: <i>"Elissa Guzman"</i>,
    <b>"email"</b>: <i>"elissaguzman@gmail.com"</i>,
    <b>"url"</b>: <i>"https://elissaguzman.com"</i>
  }
]
</pre>
<p>ou</p>
<pre>
<b>"contributors"</b>: [
  <i>"Ross Cordova <rosscordova@outlook.com> (https://rosscordova.com)"</i>,
  <i>"Elissa Guzman <elissaguzman@gmail.com> (https://elissaguzman.com)"</i>
],
</pre>
</li>

<li>
<h2>repository</h2>
<p>Agora você pode descrever as informações do seu repositório, como o tipo e a URL.</p>
<pre>
<b>"repository"</b>: {
  <b>"type"</b> : <i>"git"</i>,
  <b>"url"</b> : <i>"https://github.com/weltonfelix/minhaapi.git"</i>
}
</pre>
<p>Se o seu <code>package.json</code> não estiver na raiz do projeto, você pode informar o diretório da aplicação.</p>
<pre>
<b>"repository"</b>: {
  <b>"type"</b> : <i>"git"</i>,
  <b>"url"</b> : <i>"https://github.com/weltonfelix/minhaapi.git"</i>,
  <b>"directory"</b>: <i>"/api"</i>
}
</pre>
</li>
</ol>

<hr/>

<h1>Informações Adicionais</h1>

<ol>
<li>
<h2>keywords</h2>
<p>Você pode adicionar palavras-chave, o que ajuda bastante se seu projeto for publicado no npm.</p>
<pre>
<b>"keywords"</b>: [<i>"covid19"</i>, <i>"api"</i>, <i>"express"</i>, <i>"app"</i>, <i>"rest"</i>, <i>"restful"</i>]
</pre>
</li>

<li>
<h2>files</h2>
<p>Esse campo funciona parecido com o inverso de um <code>.gitignore</code>, aqui você informa quais arquivos devem ser enviados para o npm quando você publicar o pacote.</p>
<pre>
<b>"files"</b>: [<i>"index.js"</i>, <i>"/src/*"</i>, <i>"!/src/server.js"</i>]
</pre>
</li>
</ol>

<hr/>

<p>Com essas informações, o seu <code>package.json</code> vai ficar bem mais completo e organizado.</p>
<p><a href="https://docs.npmjs.com/files/package.json">Para mais informações, acesse a documentação na página do NPM.</a></p>

<rr>
<footer>
<small>
  <span>Cover Image by<a href="https://unsplash.com/@codestorm?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText"> Safar Safarov</a> on <a href="https://unsplash.com/s/photos/coding?utm_source=unsplash&amp;utm_medium=referral&amp;utm_content=creditCopyText">Unsplash</a>
  </span>
</small>
</footer>