Skip to main content
O arquivo package.json é o coração de qualquer projeto Node.js. Ele atua como um manifesto que lista as dependências, define scripts de automação e configura o comportamento do projeto. Este guia ensina como configurar um package.json robusto, garantindo que seu projeto seja reproduzível, organizado e compatível com o ambiente da Square Cloud.
1

Inicialize o projeto

A maneira mais segura de criar o arquivo é utilizando o CLI do NPM. Navegue até a raiz do seu projeto e escolha uma das opções:Opção A: Interativa (Recomendada para iniciantes) Responda as perguntas passo a passo para configurar metadados personalizados.
Opção B: Automática (Padrão) Gera o arquivo imediatamente aceitando todas as configurações padrão.
2

Configure os metadados essenciais

Abra o package.json gerado. Para um projeto profissional, certifique-se de que estes campos estão preenchidos corretamente:
  • name: Identificador único do projeto (use kebab-case, ex: meu-projeto-api).
  • version: Segue o padrão SemVer (ex: 1.0.0).
  • main: O ponto de entrada da aplicação (geralmente index.js ou src/index.js).
  • type: Defina como "module" se estiver usando ES Modules (import/export) ou remova para usar CommonJS (require).
3

Configure os scripts de execução

A seção scripts é vital para automação. É aqui que você define como sua aplicação deve ser iniciada, testada ou construída.
Sobre a inicialização na Square Cloud: Por padrão, a Square Cloud executa node MAIN (o arquivo definido em MAIN), mas oferece flexibilidade total. Você pode (e deve) configurar explicitamente qual comando o sistema deve executar para ligar sua aplicação.Por exemplo, você pode configurar o Start Command no dashboard ou no arquivo de configuração da Square para executar npm run start, garantindo que o script definido acima seja respeitado.
4

Gerencie as dependências

Aqui ficam as bibliotecas essenciais para seu código rodar em produção. Para instalar e salvar automaticamente nesta lista:
Atenção às devDependencies e Build na Square Cloud: Ferramentas usadas apenas no desenvolvimento local (como eslint ou prettier) ficam em devDependencies.
Importante: A Square Cloud realiza a instalação em modo de produção por padrão, o que significa que pacotes listados em devDependencies NÃO são instalados.Se você precisa rodar um processo de build na nuvem (ex: compilar TypeScript ou rodar scripts de post-install), você deve mover essas ferramentas para dependencies. Caso contrário, o build falhará por falta dos pacotes.
5

Utilize recursos avançados

Para projetos mais complexos, o package.json oferece recursos poderosos de controle:1. Overrides (Forçar versões): Útil quando uma dependência que você usa instala uma sub-dependência com vulnerabilidade. Você pode forçar a resolução para uma versão segura:
2. Imports (Alias de caminhos): Evite caminhos relativos longos como ../../../utils. Com imports, você cria atalhos internos nativos (requer Node recente):
Isso permite importar no código usando import db from '#database'.

​
Dicas e boas práticas

  • Versionamento Semântico: Prefira fixar versões críticas removendo o ^ (ex: use "14.14.1" em vez de "^14.14.1") para evitar que atualizações automáticas quebrem seu código em produção.
  • Segurança: Rode npm audit regularmente para identificar vulnerabilidades nas suas dependências. O campo overrides ensinado acima é a solução ideal para corrigir esses problemas.
  • package-lock.json: Mantenha-o no Git: ele registra a árvore de dependências exata que funcionou na sua máquina. A CLI da Square Cloud e a extensão do VS Code deixam os lockfiles de fora dos uploads por padrão, então a Square Cloud instala as versões mais recentes permitidas pelos intervalos do package.json. Quando você precisar das versões fixadas, inclua-o de volta com !package-lock.json no seu squarecloud.ignore.
  • Organização: Mantenha o arquivo limpo. Se a seção scripts ficar muito grande, considere usar ferramentas de automação externas ou separar em arquivos.

​
Exemplo de arquivo final

Abaixo, um exemplo de um package.json moderno e otimizado:
package.json

​
Próximos passos

Com seu arquivo package.json configurado:
  1. Faça commit dele no seu repositório Git.
  2. Hospede o seu projeto com o guia do runtime Node.js, ou siga um guia de framework como Express ou Next.js.
  3. Faça deploy automático a partir do GitHub a cada push.