> 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/ru/development/dev-environment.md).

# Среда разработки

Настройте локальную среду разработки и запустите предварительную самопроверку перед коммитом.

MyIP — это один репозиторий с двумя половинами: a **Vue 3** одностраничное приложение под `frontend/` и **Express 5** API под `api/` + `backend-server.js`. Одна команда запускает оба.

## Необходимые условия

<table><thead><tr><th width="180">Инструмент</th><th width="220">Версия</th><th>Примечания</th></tr></thead><tbody><tr><td><strong>Node.js</strong></td><td>24.15+ или 26+</td><td>Что использует образ Docker (<code>node:24-alpine</code>) и CI оба используют.</td></tr><tr><td><strong>pnpm</strong></td><td>Закреплено в <code>package.json</code></td><td>Не устанавливайте другую версию вручную — см. ниже.</td></tr><tr><td><strong>Git</strong></td><td>Любая недавняя версия</td><td>Ветки для вкладов ответвляются от <code>dev</code>.</td></tr></tbody></table>

Самый простой способ получить нужный pnpm — Corepack, который поставляется вместе с Node:

```bash
corepack enable
```

Corepack читает `packageManager` поле в `package.json` и устанавливает ровно эту версию pnpm. Dockerfile и рабочий процесс CI делают то же самое, так что ваш локальный набор инструментов совпадает с их.

## Только pnpm

{% hint style="danger" %}
**Никогда не запускайте `npm install` или `yarn` в этом репозитории.**
{% endhint %}

Три вещи зависят именно от pnpm:

* **`packageManager` в `package.json` закрепляет точную версию pnpm.** Corepack, Dockerfile и workflow GitHub Actions все читают его, так что у всех разрешается одно и то же дерево зависимостей.
* **`pnpm-lock.yaml` закоммичен.** npm записал бы `package-lock.json` а yarn записал бы `yarn.lock` — второй, конкурирующий lockfile, который в проекте никто не читает. CI устанавливает с `--frozen-lockfile`, так что рассинхронизированный pnpm lockfile сразу ломает сборку.
* **`pnpm-workspace.yaml` содержит разрешения для install-скриптов** (`allowBuilds`) для немногих пакетов, которым разрешено запускать postinstall-скрипты. npm и yarn полностью игнорируют этот файл.

## Установите и запустите

{% stepper %}
{% step %}

#### Клонируйте и установите

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

{% endstep %}

{% step %}

#### Создайте ваш `.env`

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

Всё в `.env.example` необязательно для *запуска* приложения, но геолокация IP останется нерабочей без учётных данных MaxMind. См. [Настройка MaxMind](/developer/ru/getting-started/maxmind-setup.md) и [Переменные окружения](/developer/ru/reference/environment-variables.md).
{% endstep %}

{% step %}

#### Запустите обе части

```bash
pnpm dev
```

Это запускает сервер разработки Vite и бэкенд (под `nodemon`) параллельно через `concurrently`. Измените `.vue` файл — и Vite применит hot reload; измените что-нибудь, что импортирует бэкенд, и nodemon перезапустит API.
{% endstep %}

{% step %}

#### Откройте приложение

Перейдите в `http://localhost:18966`. Сервер разработки Vite проксирует `/api` запросы в бэкенд за вас.
{% endstep %}
{% endstepper %}

## Порты

Оба порта берутся из `.env` и по умолчанию такие:

| Переменная      | По умолчанию | Используется для                                                        |
| --------------- | ------------ | ----------------------------------------------------------------------- |
| `FRONTEND_PORT` | `18966`      | Сервер разработки Vite (`pnpm dev`) и статический сервер (`pnpm start`) |
| `BACKEND_PORT`  | `11966`      | Express API (`backend-server.js`)                                       |

Сервер разработки Vite привязывается `0.0.0.0`, так что вы можете достучаться до него с другого устройства в вашей локальной сети, и проксирует `/api` → `http://localhost:<BACKEND_PORT>`. Вам редко нужно обращаться к порту бэкенда напрямую.

{% hint style="warning" %}
**Запросы к `/api/*` нуждаются в `Referer`.** Глобальный middleware (`requireReferer` в `server/guards.js`) отклоняет запросы, чей referer не находится в списке разрешённых. `localhost` разрешён, так что браузеру всё нормально — но простой `curl http://localhost:11966/api/...` получает `403`. Добавьте `-H 'Referer: http://localhost/'` при ручном тестировании.
{% endhint %}

## Локальные `.env` заметки

* `.env` загружаются **оба** две части: `backend-server.js` во время выполнения и `vite.config.js` во время сборки.
* Переменные с префиксом `VITE_` встраиваются **в фронтенд-бандл во время сборки**. При изменении нужно `pnpm dev` перезапустить, а не просто обновить страницу — и никогда не размещайте секрет за `VITE_` именем.
* Опциональные интеграции полностью отключаются, когда их переменная пуста. Нет Sentry DSN — значит код Sentry вообще не загружается; нет конфигурации Firebase — значит SDK никогда не скачивается. Вы можете разрабатывать большую часть приложения с почти пустым `.env`.
* Параметры логирования — это `LOG_LEVEL`, `LOG_FORMAT`, и `LOG_HTTP` — см. [Логирование](/developer/ru/configuration/logging.md). В этом проекте нет `NODE_ENV` переключатели где угодно в этом проекте.

## Каждый скрипт

| Команда               | Что делает                                                            |
| --------------------- | --------------------------------------------------------------------- |
| `pnpm dev`            | сервер разработки Vite + бэкенд под nodemon, вместе                   |
| `pnpm build`          | Сборка продакшн-фронтенда в `dist/`                                   |
| `pnpm preview`        | preview-сервер Vite для собранного вывода                             |
| `pnpm test`           | `node --test tests/*.test.js`                                         |
| `pnpm check`          | `тест` + `сборка` — предварительная проверка перед коммитом           |
| `pnpm start`          | Статический сервер фронтенда + бэкенд (что запускает production-хост) |
| `pnpm start-backend`  | Только бэкенд                                                         |
| `pnpm start-frontend` | Только статический сервер фронтенда                                   |

## Самопроверка

Прежде чем передавать изменение — PR, коммит или запрос на ревью — запустите:

```bash
pnpm check
```

Это `pnpm test` за которым следуют `pnpm build`. Это та же пара шагов, которую CI выполняет при каждом push и pull request для `main` и `dev`, так что зелёный локальный `check` обычно означает зелёный запуск CI.

{% hint style="info" %}
**Визуальные изменения не могут быть самотестируемыми.** Тестовый раннер Node не рендерит Vue-компоненты и не управляет браузером. Если ваше изменение визуальное, явно укажите это в PR и позвольте человеку посмотреть на него в `pnpm dev`. См. [Тестирование](/developer/ru/development/testing.md).
{% endhint %}

## Полезные дополнения в разработке

* **Мобильная консоль.** На телефоне или планшете `pnpm dev` автоматически загружает vConsole — панель devtools на экране. Это только для разработки и только для мобильных; она никогда не попадает в сборку.
* **Переход к исходнику по клику.** Фабрика `code-inspector-plugin` подключён к серверу разработки, так что вы можете перейти от элемента в браузере к строке его исходника в вашем редакторе.
* **Дополнительные хосты для разработки.** `vite.config.js` разрешает `dev.ipcheck.ing` и `test.ipcheck.ing` помимо localhost, для тестирования на реальном hostname.

## Далее

* [Соглашения о кодировании](/developer/ru/development/coding-conventions.md) — правила, которым должно соответствовать ваше изменение.
* [Добавление нового инструмента](/developer/ru/development/adding-a-new-tool.md) — сквозной walkthrough.
* [Структура проекта](/developer/ru/architecture/project-structure.md) — что где находится.
* [Как внести вклад](/developer/ru/contributing/how-to-contribute.md) — дисциплина веток и рекомендации по 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.