> For the complete documentation index, see [llms.txt](https://docs.ipcheck.ing/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.ipcheck.ing/developer/pt-br/development/dev-environment.md).

# Ambiente de desenvolvimento

Configure um ambiente de desenvolvimento local e execute a verificação automática de pré-commit.

MyIP é um repositório com duas metades: uma **Vue 3** aplicação de página única em `frontend/` e uma **Express 5** API em `api/` + `backend-server.js`. Um comando executa ambos.

## Pré-requisitos

<table><thead><tr><th width="180">Ferramenta</th><th width="220">Versão</th><th>Observações</th></tr></thead><tbody><tr><td><strong>Node.js</strong></td><td>24</td><td>O que a imagem Docker (<code>node:24-alpine</code>) e o CI usam.</td></tr><tr><td><strong>pnpm</strong></td><td>Fixado em <code>package.json</code></td><td>Não instale uma versão diferente manualmente — veja abaixo.</td></tr><tr><td><strong>Git</strong></td><td>Qualquer versão recente</td><td>Os branches de contribuição se ramificam a partir de <code>dev</code>.</td></tr></tbody></table>

A maneira mais fácil de obter o pnpm correto é o Corepack, que vem com o Node:

```bash
corepack enable
```

O Corepack lê o `packageManager` campo em `package.json` e provisiona exatamente essa versão do pnpm. O Dockerfile e o fluxo de trabalho de CI fazem o mesmo, então sua cadeia de ferramentas local corresponde à deles.

## somente pnpm

{% hint style="danger" %}
**Nunca execute `npm install` ou `yarn` neste repositório.**
{% endhint %}

Três coisas dependem especificamente do pnpm:

* **`packageManager` em `package.json` fixa a versão exata do pnpm.** O Corepack, o Dockerfile e o fluxo de trabalho do GitHub Actions leem isso, então todo mundo resolve a mesma árvore de dependências.
* **`pnpm-lock.yaml` é comitado.** O npm escreveria `package-lock.json` e o yarn escreveria `yarn.lock` — um segundo arquivo de bloqueio concorrente que nada no projeto lê. O CI instala com `--frozen-lockfile`, então um lockfile do pnpm divergente faz a build falhar imediatamente.
* **`pnpm-workspace.yaml` carrega as aprovações de scripts de instalação** (`allowBuilds`) para os poucos pacotes autorizados a executar scripts de postinstall. npm e yarn ignoram esse arquivo completamente.

## Instale e execute

{% stepper %}
{% step %}

#### Clone e instale

```bash
git clone https://github.com/jason5ng32/MyIP.git
cd MyIP
pnpm install
```

{% endstep %}

{% step %}

#### Crie sua `.env`

```bash
cp .env.example .env
```

Tudo em `.env.example` é opcional para *iniciar* o aplicativo, mas a geolocalização de IP continua quebrada sem credenciais da MaxMind. Veja [Configuração da MaxMind](/developer/pt-br/getting-started/maxmind-setup.md) e [Variáveis de Ambiente](/developer/pt-br/reference/environment-variables.md).
{% endstep %}

{% step %}

#### Inicie as duas metades

```bash
pnpm dev
```

Isso executa o servidor de desenvolvimento do Vite e o backend (em `nodemon`) lado a lado por meio de `concurrently`. Edite um `.vue` arquivo e o Vite faz hot-reload dele; edite qualquer coisa que o backend importe e o nodemon reinicia a API.
{% endstep %}

{% step %}

#### Abra o app

Acesse `http://localhost:18966`. O servidor de desenvolvimento do Vite faz proxy de `/api` para o backend para você.
{% endstep %}
{% endstepper %}

## Portas

Ambas as portas vêm de `.env` e têm o padrão a seguir:

| Variável        | Padrão  | Usado por                                                                             |
| --------------- | ------- | ------------------------------------------------------------------------------------- |
| `FRONTEND_PORT` | `18966` | Servidor de desenvolvimento do Vite (`pnpm dev`) e o servidor estático (`pnpm start`) |
| `BACKEND_PORT`  | `11966` | API Express (`backend-server.js`)                                                     |

O servidor de desenvolvimento do Vite se vincula a `0.0.0.0`, então você pode acessá-lo de outro dispositivo na sua LAN, e faz proxy de `/api` → `http://localhost:<BACKEND_PORT>`. Raramente você precisa acessar a porta do backend diretamente.

{% hint style="warning" %}
**As solicitações para `/api/*` precisam de um `Referer`.** Um middleware global (`requireReferer` em `common/guards.js`) rejeita solicitações cujo referer não está na lista de permissões. `localhost` é permitido, então o navegador funciona bem — mas um simples `curl http://localhost:11966/api/...` recebe um `403`. Adicione `-H 'Referer: http://localhost/'` ao testar manualmente.
{% endhint %}

## Notas `.env` locais

* `.env` é carregado por **ambos** metades: `backend-server.js` em tempo de execução e `vite.config.js` em tempo de build.
* Variáveis prefixadas `VITE_` são **incorporadas ao bundle do frontend no momento do build**. Alterar uma delas exige um `pnpm dev` reinício, e não apenas uma atualização da página — e nunca coloque um segredo atrás de um `VITE_` nome.
* Integrações opcionais permanecem totalmente desligadas quando sua variável está vazia. Sem DSN do Sentry, nenhum código do Sentry é carregado; sem configuração do Firebase, o SDK nunca é buscado. Você pode desenvolver a maior parte do aplicativo com um `.env`.
* Os controles de logging são `LOG_LEVEL`, `LOG_FORMAT`, e `LOG_HTTP` — veja [Logs](/developer/pt-br/configuration/logging.md). Não há `NODE_ENV` um interruptor em qualquer lugar neste projeto.

## Cada script

| Comando               | O que faz                                                                   |
| --------------------- | --------------------------------------------------------------------------- |
| `pnpm dev`            | Servidor de desenvolvimento do Vite + backend sob o nodemon, juntos         |
| `pnpm build`          | Build de frontend de produção em `dist/`                                    |
| `pnpm preview`        | Servidor de pré-visualização do Vite para a saída compilada                 |
| `pnpm test`           | `node --test tests/*.test.js`                                               |
| `pnpm check`          | `test` + `build` — a verificação automática pré-commit                      |
| `pnpm start`          | Servidor estático do frontend + backend (o que um host de produção executa) |
| `pnpm start-backend`  | Somente backend                                                             |
| `pnpm start-frontend` | Somente servidor estático do frontend                                       |

## A verificação automática

Antes de repassar uma alteração — um PR, um commit, uma solicitação de revisão — execute:

```bash
pnpm check
```

Isso é `pnpm test` seguido por `pnpm build`. É o mesmo par de etapas que o CI executa em cada push e pull request contra `main` e `dev`, então um local verde `check` geralmente significa uma execução verde na CI.

{% hint style="info" %}
**Mudanças visuais não podem ser testadas por si mesmas.** O executor de testes do Node não renderiza componentes Vue nem controla um navegador. Se sua alteração for visual, diga isso explicitamente no PR e deixe um humano analisá-la em `pnpm dev`. Veja [Testes](/developer/pt-br/development/testing.md).
{% endhint %}

## Extras úteis no dev

* **Console móvel.** Em um celular ou tablet, `pnpm dev` carrega o vConsole automaticamente — um painel de ferramentas de desenvolvimento na tela. É exclusivo do dev e do mobile; nunca é incluído em um build.
* **Clique para o código-fonte.** A `code-inspector-plugin` está integrado ao servidor de desenvolvimento, então você pode pular de um elemento no navegador para sua linha-fonte no editor.
* **Hosts extras de dev.** `vite.config.js` permite `dev.ipcheck.ing` e `test.ipcheck.ing` além de localhost, para testar com um hostname real.

## Próximo

* [Convenções de Codificação](/developer/pt-br/development/coding-conventions.md) — as regras que sua alteração deve seguir.
* [Adicionando uma nova ferramenta](/developer/pt-br/development/adding-a-new-tool.md) — o passo a passo ponta a ponta.
* [Estrutura do projeto](/developer/pt-br/architecture/project-structure.md) — o que fica em cada lugar.
* [Como Contribuir](/developer/pt-br/contributing/how-to-contribute.md) — disciplina de branches e diretrizes de PR.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.ipcheck.ing/developer/pt-br/development/dev-environment.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.