# xflow.json

> Поля файла в корне проекта и в папке приложения, исключения из отправки и локальное состояние.

> Оглавление всей документации: https://docs.getxflow.com/llms.txt

Файлов два вида: в корне проекта лежит `projectId`, в каждой `apps/<папка>/` лежит `appId`.
По ним CLI понимает, где стоит команда. Оба файла пишут `xflow init`, `xflow link` и
`xflow apps add`; руками правят `functions`, `build` и `ignore`.

## Корень проекта

```json
{
  "projectId": "3f2a9c1e-…",
  "functions": {
    "book-slot": { "callers": ["zapis"] },
    "nightly-report": { "callers": [] }
  },
  "ignore": ["drafts/"]
}
```

| Поле | Обязательно | Что значит |
|---|---|---|
| `projectId` | да | id проекта на платформе |
| `functions` | нет | объект `{ "<имя функции>": { "callers": [...] } }` |
| `functions.<имя>.callers` | нет | папки приложений этого проекта, которым можно звать функцию (`"zapis"` для `apps/zapis`) |
| `ignore` | нет | дополнительные правила исключения для корня, синтаксис как в `.xflowignore` |

- Функция без записи в `functions` или с `"callers": []` никем из приложений не зовётся: её
  будит расписание, ключ или `xflow functions invoke`.
- Зовущие доезжают до платформы на `xflow deploy functions`, а не при сохранении файла.
- У каждого имени в `functions` должна быть папка `functions/<имя>/index.ts`. Зовущий это
  папка приложения этого проекта, страница зовущим не бывает. Ошибки: [Коды ошибок](https://docs.getxflow.com/reference/errors.md).
- Кто ещё откроет приложение-зовущего, решает его уровень доступа: [Доступ](https://docs.getxflow.com/platform/access.md).

## Папка приложения

```json
{
  "appId": "8b41d0f2-…",
  "build": { "command": "npm run build", "dir": "dist" },
  "ignore": ["fixtures/"]
}
```

| Поле | Обязательно | Что значит |
|---|---|---|
| `appId` | да | id приложения; папку можно переименовать, приложение остаётся тем же |
| `build.command` | нет | команда сборки, по умолчанию `npm run build`; скрипт должен быть в `package.json` |
| `build.dir` | нет | куда пишет сборка, по умолчанию `dist`; путь внутри папки приложения, на платформу не уходит |
| `ignore` | нет | дополнительные правила исключения для этого приложения |

Файл приложения без корня проекта выше не работает: клонируйте проект целиком через
`xflow link <id>` в пустой папке. Подробнее: [Приложения](https://docs.getxflow.com/platform/apps.md).

## Что уходит на платформу

Корень проекта и каждое приложение отправляются отдельно. Корень отправляет всё, кроме
`apps/`, плюс файлы `apps/<папка>/xflow.json`: из них читаются зовущие. Приложение
отправляет свою папку.

Никогда не уходят:

| Что | Почему |
|---|---|
| `node_modules/`, `dist/`, `build/`, `.next/` | зависимости и сборку платформа делает сама |
| `.git/`, `.xflow/` | история и локальное состояние |
| `.env`, `.env.*` | секреты хранятся в переменных: [Переменные и секреты](https://docs.getxflow.com/platform/secrets.md) |
| `.DS_Store`, `Thumbs.db`, `tsconfig.tsbuildinfo` | служебные файлы системы и компилятора |
| копии скилла xflow, которые раскладывает CLI | CLI кладёт свежую копию сам |
| символические ссылки | не архивируются |

Тяжёлые фото, видео и PDF держат в [файлах проекта](https://docs.getxflow.com/platform/storage.md), а не в исходниках.

## .xflowignore

Лежит в корне проекта или в папке приложения и действует на то, что отправляется оттуда.
Правила складываются с полем `ignore` и списком выше.

```
# черновики и дампы
drafts/
*.psd
/data/dump.sql
```

| Запись | Значит |
|---|---|
| `#` в начале | комментарий |
| `*`, `?` | любые символы и один символ внутри имени |
| `**` | любая глубина папок |
| `/` в конце | только папка |
| `/` в начале или внутри | путь от папки, где лежит файл; иначе имя ищется на любой глубине |

Отрицания `!` нет. Если отправлять стало нечего, команда так и скажет: проверьте `.xflowignore`.

## .xflow/

Локальное состояние папки: с какой ревизией на платформе она сверялась последней и к какой
организации привязан проект. Оно своё у каждой машины, поэтому `xflow init` и `xflow link`
дописывают `.xflow/` в `.gitignore`. Удалённая `.xflow/` не ломает проект: следующая выкатка
ляжет поверх текущей ревизии и скажет об этом.