> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squarecloud.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Como criar seu arquivo package.json

> Guia completo sobre o arquivo package.json no Node.js: aprenda a criar, configurar scripts, gerenciar dependências e preparar seu projeto para deploy em produção.

# 📋 Arquivo package.json para Node.js

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.

***

<Steps>
  <Step title="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.

    ```bash theme={null}
    npm init
    ```

    **Opção B: Automática (Padrão)**
    Gera o arquivo imediatamente aceitando todas as configurações padrão.

    ```bash theme={null}
    npm init -y
    ```
  </Step>

  <Step title="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).
  </Step>

  <Step title="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.

    ```json theme={null}
    "scripts": {
      "start": "node index.js",
      "test": "echo \"Error: no test specified\" && exit 1"
    }
    ```

    **Sobre a inicialização na Square Cloud:**
    Embora o ambiente busque padrões comuns, a Square Cloud 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 painel ou no arquivo de configuração da Square para executar `npm run start`, garantindo que o script definido acima seja respeitado.
  </Step>

  <Step title="Gerencie as dependências">
    Aqui ficam as bibliotecas essenciais para seu código rodar em produção. Para instalar e salvar automaticamente nesta lista:

    ```bash theme={null}
    npm install nome-do-pacote
    ```

    **Atenção às `devDependencies` e Build na Square Cloud:**
    Ferramentas usadas apenas no desenvolvimento local (como `eslint` ou `prettier`) ficam em `devDependencies`.

    <Warning>
      **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.
    </Warning>
  </Step>

  <Step title="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:

    ```json theme={null}
    "overrides": {
      "pacote-vulneravel": "2.0.1"
    }
    ```

    **2. Imports (Alias de caminhos):**
    Evite caminhos relativos longos como `../../../utils`. Com `imports`, você cria atalhos internos nativos (requer Node recente):

    ```json theme={null}
    "imports": {
      "#utils/*": "./src/utils/*.js",
      "#database": "./src/core/database.js"
    }
    ```

    Isso permite importar no código usando `import db from '#database'`.
  </Step>
</Steps>

***

## 💡 Dicas e Melhores 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**: Nunca delete ou ignore este arquivo no `.gitignore`. Ele é a garantia de que a Square Cloud instalará a árvore de dependências exata que funcionou na sua máquina.
* **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:

```json package.json theme={null}
{
  "name": "square-cloud-project",
  "version": "1.0.0",
  "description": "API profissional Node.js",
  "main": "src/index.js",
  "type": "module",
  "scripts": {
    "start": "node src/index.js",
    "lint": "eslint ."
  },
  "imports": {
    "#services/*": "./src/services/*.js"
  },
  "dependencies": {
    "discord.js": "14.14.1",
    "dotenv": "16.3.1",
    "typescript": "5.3.3" 
  },
  "devDependencies": {
    "eslint": "8.56.0"
  }
}
```

***

## 🚀 Próximos Passos

Com seu arquivo `package.json` configurado:

1. Commit no seu repositório Git.
2. Hospede seu projeto na **Square Cloud**.
3. Configure o deploy automático via GitHub.
4. Seja bem-vindo à hospedagem profissional de aplicações Node.js!

Um arquivo `package.json` bem estruturado é a base para qualquer aplicação Node.js de sucesso, garantindo que sua aplicação funcione perfeitamente na Square Cloud.