> ## 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.

# Primeiros passos na Square Cloud com Deno

> Aprenda como começar na Square Cloud com Deno

## 🚀 Introdução

* Antes de começar, você pode optar por usar o runtime Deno no seu projeto. Se ainda não tiver o Deno instalado localmente, você tem duas opções principais:

* Instalar via npm (recomendado para compatibilidade com `npx` durante o deploy):

```bash theme={null}
npm install deno
```

* Ou instalar o Deno pelo instalador oficial (verifique a documentação do Deno para instruções de instalação nativa).

* Ao adicionar `deno` como dependência, você poderá usar `npx deno` no `START` do `squarecloud.app` para iniciar sua aplicação com Deno. Veja mais abaixo na seção "Iniciar a Aplicação" para exemplos de `START`.

* Em seguida, será necessário criar uma conta na Square Cloud, o que pode ser feito através da [página de login](https://squarecloud.app/pt-br/signup). Você pode usar seu e‑mail, GitHub ou ambos para criar a conta.

* Por fim, é necessário ter um plano pago ativo na sua conta. Você pode ver nossos planos e adquirir um conforme sua necessidade [aqui](https://squarecloud.app/pt-br/pricing).

## ⚙️ Configuração do arquivo squarecloud.app

<Note>
  Se você estiver enviando sua aplicação através do website da Square Cloud, você pode ignorar esta seção. O site cria automaticamente o arquivo de configuração `squarecloud.app` para você.
</Note>

<Card title="Saiba mais: como criar o arquivo de configuração para a Square Cloud." icon="link" href="https://docs.squarecloud.app/pt-br/getting-started/config-file">
  O arquivo squarecloud.app é um arquivo de configuração que será usado para
  configurar sua aplicação; ele servirá para definir nome, descrição,
  versão, arquivo principal, entre outras coisas.
</Card>

## ▶️ Como iniciar sua aplicação

* Para usar o runtime Deno no ambiente Node.js da Square Cloud, primeiro adicione o pacote `deno` ao seu projeto (por exemplo `npm install deno`) para que o comando `npx deno` esteja disponível no ambiente de execução.
* Depois, defina o campo `START` no seu `squarecloud.app` com o comando que inicia sua aplicação usando Deno. Exemplos:

```squarecloud.app OU .config theme={null}
START=npx deno run --allow-net --allow-env main.ts
```

Se você utiliza tasks definidas no `deno.json`, pode iniciar assim:

```
START=npx deno task start
```

* Ajuste as permissões (`--allow-net`, `--allow-env`, `--allow-read` etc.) conforme as necessidades da sua aplicação.

* Lembre-se: se o campo `START` estiver definido, o valor nele será executado diretamente. Para mais informações sobre os parâmetros do arquivo de configuração, visite [configuration parameters](https://docs.squarecloud.app/pt-br/getting-started/config-file#configuration-parameters).

* Caso utilize módulos npm com Deno e a pasta `node_modules` não existir, a Square Cloud executará `npm install --no-package-lock --no-audit --no-fund` para instalar as dependências e limpar a pasta `.npm`.

Se você pretende usar Deno como runtime, recomendamos adicionar `deno` como dependência (`npm install deno`) para garantir que `npx deno` esteja disponível no ambiente de execução durante o deploy. Em projetos onde você prefere usar o instalador nativo do Deno, verifique a compatibilidade e os requisitos do seu build antes de optar por essa abordagem.

## 🖥️ Preparando o projeto

### 📁 Arquivos de configuração essenciais

Ao preparar seu projeto Deno para deploy na Square Cloud, certifique‑se de incluir o arquivo de configuração (`squarecloud.app/.config`) e os arquivos essenciais da sua aplicação dentro de um arquivo zip.

<Warning>O arquivo de configuração (`squarecloud.app/.config`) deve estar localizado na raiz do arquivo zip. Caso contrário, a Square Cloud não conseguirá encontrá‑lo durante o deploy.</Warning>

#### 🗑️ Arquivos a excluir antes de enviar

* `node_modules`: Só necessário se você usar módulos npm; caso contrário, não envie para reduzir o tamanho do upload.
* `package-lock.json`: O ambiente de produção instalará dependências com base no `package.json` quando houver uso de npm.
* `deno_dir` ou `.cache/deno`: Diretório de cache do Deno; não é necessário para o deploy.

### 🤔 Por que excluir esses arquivos?

Existem várias razões para excluir `node_modules`, `package-lock.json` e o cache do Deno antes de enviar seu projeto:

1. **Consistência na instalação:** Não enviar `node_modules` garante que as dependências sejam instaladas pelo ambiente de produção, resultando em um build consistente e livre de discrepâncias do sistema local.

2. **Instalações atualizadas:** O ambiente de produção instalará as versões compatíveis mais recentes das dependências listadas no `package.json` (quando aplicável) ou usará os imports remotos definidos no `deno.json`.

3. **Redução do tamanho do upload:** Não incluir esses diretórios reduz o tamanho do arquivo enviado, acelerando o processo de upload e tornando o deploy mais eficiente.

Fazendo isso, você garante que sua aplicação Deno esteja preparada de forma otimizada para hospedagem na Square Cloud.

### 📄 Arquivos Obrigatórios

Três arquivos são necessários para hospedar seu projeto Deno:

* [squarecloud.app/.config](https://docs.squarecloud.app/pt-br/getting-started/config-file)
* mainFile.ts/.js (Exemplo de arquivo principal)
* deno.json ou deno.jsonc (definição de permissões e tasks). Se usar módulos npm, inclua também o [package.json](./how-to-create-your-package-json).

## 💡 Resolução de problemas

<AccordionGroup>
  <Accordion title="O arquivo principal é inválido ou está corrompido" icon="file" iconType="solid">
    Este erro ocorre quando o arquivo definido como "main" para sua aplicação no
    arquivo de configuração não existe, está escrito incorretamente ou o caminho
    está errado. Se o seu arquivo principal estiver dentro de uma pasta, por
    exemplo, você deve informar `pasta/arquivo.ts` ou `pasta/arquivo.js`.
  </Accordion>

  <Accordion title="Memória insuficiente" icon="memory" iconType="solid">
    A quantidade mínima de RAM necessária para hospedar um bot é 256MB e para
    um site/API é 512MB. No entanto, dependendo do tamanho e complexidade da
    sua aplicação, pode ser aconselhável alocar uma quantidade maior de RAM para
    evitar que a aplicação fique sem memória e trave.
  </Accordion>
</AccordionGroup>

## 📤 Como hospedar seu projeto

Agora que você preparou todos os arquivos do seu projeto Deno, o próximo passo é enviá-los para a Square Cloud e colocar sua aplicação no ar. Existem varias formas de fazer o upload, mas vamos abordar duas: via Dashboard ou via CLI.

### Via dashboard

<Steps>
  <Step title="Acesse a página de upload">
    Acesse a [página de upload](https://squarecloud.app/pt-br/dashboard/new) e envie seu arquivo zip.
  </Step>

  <Step title="Configure seu ambiente">
    Após fazer o upload do seu arquivo zip, você precisará configurar o nome, o arquivo principal ou o ambiente de execução e outras configurações do seu projeto.\
    Se você estiver enviando um projeto web, certifique-se de selecionar "Publicação na Web" e definir um subdomínio para o seu projeto.
  </Step>

  <Step title="Faça o deploy do projeto">
    Por fim, clique no botão "Deploy" para hospedar seu projeto no Square Cloud.
    Após o deploy, você poderá monitorar o status e os registros do seu projeto no painel.

    <Frame>
      <img src="https://cdn.squarecloud.app/docs/articles/dashboard/uploading-pt-br.gif" alt="Enviando aplicação para a Square Cloud" style={{ borderRadius: "0.2rem" }} />
    </Frame>
  </Step>
</Steps>

### Via CLI

Para usar esse método, você precisa criar um arquivo de configuração chamado `squarecloud.app` no diretório raiz do seu projeto. Esse arquivo conterá a configuração necessária para o seu projeto.

<Card title="Saiba mais sobre: Como criar arquivo de configuração da Square Cloud." icon="link" href="/pt-br/getting-started/config-file">
  O arquivo squarecloud.app é um arquivo de configuração que será usado para configurar seu aplicativo; ele será usado para definir seu ambiente.
</Card>

<Steps>
  <Step title="Primeiro Passo">
    Primeiro, você precisa ter a CLI instalada em seu ambiente. Se você ainda não a possui, execute o seguinte comando em seu terminal:

    ```
    npm install -g @squarecloud/cli
    ```

    Se você já a possui, recomendamos atualizá-la. Para fazer isso, execute o seguinte comando em seu terminal:

    <Tabs>
      <Tab title="Windows">
        ```bash theme={null}
        squarecloud update
        ```
      </Tab>

      <Tab title="Linux, macOS, e WSL">
        ```bash theme={null}
        curl -fsSL https://cli.squarecloud.app/install | bash
        ```
      </Tab>
    </Tabs>
  </Step>

  <Step title="Segundo Passo">
    Agora, para autenticar e usar outros comandos da CLI, você encontrará sua chave de autorização [aqui](https://squarecloud.app/pt-br/account/security) clicando em "Solicitar Chave da API". Após obter sua chave de autorização, execute o seguinte comando:

    ```bash theme={null}
    squarecloud auth login
    ```
  </Step>

  <Step title="Terceiro Passo">
    Finalmente, para fazer o deploy da sua aplicação para a Square Cloud usando a CLI, você precisa executar o seguinte comando:

    ```bash theme={null}
    squarecloud upload
    ```

    Ou se já possui o zip criado:

    ```bash theme={null}
    squarecloud upload --file <caminho/para/zip>
    ```
  </Step>
</Steps>

## Contate-nos

Se você continuar enfrentando **dificuldades técnicas**, nossa **equipe de suporte especializada** está disponível para auxiliá-lo. [**Entre em contato conosco**](https://squarecloud.app/pt-br/support) e teremos prazer em ajudá-lo a resolver qualquer questão.