> 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`. Одна команда запускает оба.
## Предварительные требования
Инструмент
Версия
Примечания
Node.js
24
Что используют образ Docker (node:24-alpine) и CI.
pnpm
Закреплено в package.json
Не устанавливайте другую версию вручную — см. ниже.
Git
Любая недавняя версия
Ветки для вкладов ответвляются от dev.
Самый простой способ получить правильный pnpm — это Corepack, который поставляется с Node:
```bash
corepack enable
```
Corepack читает `packageManager` поле в `package.json` и устанавливает именно эту версию pnpm. Dockerfile и workflow 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` — второй конкурирующий lock-файл, который в проекте никто не читает. CI устанавливает с `--frozen-lockfile`, так что рассинхронизированный lock-файл pnpm сразу ломает сборку.
* **`pnpm-workspace.yaml` содержит разрешения на установочные скрипты** (`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
```
Это запускает dev-сервер Vite и backend (под `nodemon`) бок о бок через `concurrently`. Измените `.vue` файл, и Vite применит hot reload; измените что угодно, что импортирует backend, и nodemon перезапустит API.
{% endstep %}
{% step %}
#### Откройте приложение
Перейдите на `http://localhost:18966`. Dev-сервер Vite проксирует `/api` запросы к backend за вас.
{% endstep %}
{% endstepper %}
## Порты
Оба порта берутся из `.env` и по умолчанию такие:
| Переменная | По умолчанию | Используется в |
| --------------- | ------------ | ---------------------------------------------------------------- |
| `FRONTEND_PORT` | `18966` | Dev-сервер Vite (`pnpm dev`) и статический сервер (`pnpm start`) |
| `BACKEND_PORT` | `11966` | Express API (`backend-server.js`) |
Dev-сервер Vite привязывается к `0.0.0.0`, так что вы можете открыть его с другого устройства в вашей локальной сети, и проксирует `/api` → `http://localhost:`. Вам редко нужно обращаться к порту backend напрямую.
{% hint style="warning" %}
**Запросы к `/api/*` требуют `Referer`.** Глобальный middleware (`requireReferer` в `common/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_` имя.
* Необязательные интеграции полностью отключены, когда их переменная пуста. Нет DSN Sentry — не загружается вообще никакой код Sentry; нет конфигурации Firebase — SDK никогда не подгружается. Вы можете разрабатывать большую часть приложения с почти пустым `.env`.
* Настройки логирования — `LOG_LEVEL`, `LOG_FORMAT`, и `LOG_HTTP` — см. [Логирование](/developer/ru/configuration/logging.md). Нет никакого `NODE_ENV` переключатель в любой точке этого проекта.
## Каждый скрипт
| Команда | Что она делает |
| --------------------- | -------------------------------------------------------------------------- |
| `pnpm dev` | Dev-сервер Vite + backend под nodemon, вместе |
| `pnpm build` | Сборка фронтенда для продакшена в `dist/` |
| `pnpm preview` | preview-сервер Vite для собранного вывода |
| `pnpm test` | `node --test tests/*.test.js` |
| `pnpm check` | `тест` + `сборка` — самопроверка перед коммитом |
| `pnpm start` | Статический сервер фронтенда + backend (то, что запускает production-хост) |
| `pnpm start-backend` | Только backend |
| `pnpm start-frontend` | Только статический сервер фронтенда |
## Самопроверка
Прежде чем передать изменение — PR, коммит или запрос на ревью — выполните:
```bash
pnpm check
```
То есть `pnpm test` за которым следует `pnpm build`. Это та же пара шагов, которую CI выполняет при каждом push и pull request в отношении `main` и `dev`, так что зелёная локальная `check` обычно означает зелёный прогон CI.
{% hint style="info" %}
**Визуальные изменения нельзя протестировать самостоятельно.** Node test runner не рендерит Vue-компоненты и не управляет браузером. Если ваше изменение визуальное, явно укажите это в PR и дайте человеку посмотреть на него в `pnpm dev`. См. [Тестирование](/developer/ru/development/testing.md).
{% endhint %}
## Полезные дополнения в dev-режиме
* **Мобильная консоль.** На телефоне или планшете, `pnpm dev` автоматически загружает vConsole — панель devtools на экране. Она только для разработки и только для мобильных устройств; в сборку никогда не попадает.
* **Переход к исходнику по клику.** Промежуточный слой `code-inspector-plugin` подключён к dev-серверу, так что вы можете перейти от элемента в браузере к строке его исходника в редакторе.
* **Дополнительные dev-хосты.** `vite.config.js` позволяет `dev.ipcheck.ing` и `test.ipcheck.ing` в дополнение к localhost, для тестирования с реальным именем хоста.
## Далее
* [Соглашения по написанию кода](/developer/ru/development/coding-conventions.md) — правила, которым должно следовать ваше изменение.
* [Добавление нового инструмента](/developer/ru/development/adding-a-new-tool.md) — пошаговый end-to-end обзор.
* [Структура проекта](/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 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/ru/development/dev-environment.md?ask=&goal=
```
`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.