layero.json — конфигурация в репозитории

Необязательный файл в корне репозитория. Он задаёт то, что Layero обычно определяет сам, и лежит рядом с кодом — значит, едет вместе с ним и может отличаться по веткам.

Правило одно:

Всё, что вы указали в файле, Layero обязан применить. Всё, чего вы не указали, Layero определяет сам.

Файл пригодится, когда:

• деплой настраивает за вас AI-агент — он кладёт нужные значения одним PR;
• конфигурация должна отличаться по веткам: staging собирается не так, как production;
• команде важно видеть в код-ревью, кто и зачем поменял сборку.

Минимальный пример

layero.json

{
  "$schema": "https://layero.ru/schema/layero-v2.json",
  "framework": "vite",
  "installCommand": "npm ci",
  "buildCommand": "npm run build",
  "outputDirectory": "dist",
  "nodeVersion": "22"
}

Все поля необязательны, включая $schema. Пустой файл тоже допустим:

layero.json

{}

Он означает «определяй всё сам» и ничего не ломает.

Укажите только то, что нужно поменять:

layero.json — только папка результата

{
  "$schema": "https://layero.ru/schema/layero-v2.json",
  "outputDirectory": "bundle"
}

$schema подключает автодополнение и подсветку ошибок в любом редакторе с поддержкой JSON Schema: VS Code, JetBrains, Neovim. На сборку это поле не влияет.

Что можно задать

framework

Имя фреймворка. Перебивает автоопределение. Допустимые значения — в списке поддерживаемых фреймворков.

installCommand

Команда установки зависимостей. По умолчанию Layero берёт воспроизводимую команду вашего пакетного менеджера: npm ci, yarn install --frozen-lockfile, pnpm install --frozen-lockfile.

buildCommand

Команда сборки. Например, pnpm build:prod.

outputDirectory

Папка с готовой статикой относительно корня приложения. Её содержимое Layero раздаёт по адресу проекта. Например: dist, build, out, dist/my-app/browser. Указывается папка, а не файл.

Поле действует только для сайтов, которые Layero раздаёт файлами. У приложений, которые Layero запускает в контейнере, папки результата нет: контейнер отвечает на запросы сам. Такому приложению задайте startCommand.

nodeVersion

Версия Node.js, на которой собирать. Принимает мажор "22", точную версию "22.14.0" или "lts".

startCommand

Команда запуска для приложений, которые Layero не раздаёт файлами, а запускает в контейнере.

Рабочая папка приложения в контейнере — /app: туда попадает ваш код, там же Layero устанавливает зависимости и собирает проект. Пути в команде отсчитываются от неё: node server.js запустит /app/server.js. Если поле не задано, Layero определяет команду сам: у Node-приложения это обычно npm start из package.json.

Короткие имена работают всегда

У пяти полей есть короткая форма, и она не устаревшая: файлы, написанные короткими именами, будут работать всегда.

основное имя	короткое
installCommand	install
buildCommand	build
outputDirectory	output
nodeVersion	node
startCommand	start

Если в файле окажутся оба имени одного поля, применится основное. Про второе Layero скажет в логе сборки: иначе вы правили бы не ту строку.

Что сильнее чего

Для каждого поля отдельно:

layero.json  →  настройки проекта  →  найденное в репозитории  →  умолчание фреймворка

Побеждает первое заданное. Например, при таком package.json:

{ "scripts": { "build": "vite build" } }

и таком layero.json:

{ "buildCommand": "npm run build:production" }

соберётся npm run build:production.

У nodeVersion порядок чуть длиннее, потому что версию умеет объявлять и сам репозиторий:

layero.json → настройки проекта → .nvmrc → .node-version → engines.node → умолчание Layero

Перекрытую версию из репозитория Layero называет в логе сборки, а не применяет молча.

В логе видно, откуда взялось каждое значение:

[config] framework=nextjs (from layero.json)
[config] node=22.18.0 (layero.json)
[config] node: layero.json перекрыл .nvmrc=20
[config] build=`npm run build` (from layero.json)
[config] output=out (default for nextjs)

Поле из файла нельзя изменить в панели

Если поле объявлено в layero.json, панель показывает его значение и бейдж с именем файла — вместо кнопки редактирования. Нажмите на бейдж — откроется файл в репозитории.

Так сделано намеренно. Открытое поле — это обещание, что правка применится, а правку в панели первая же сборка отменила бы: файл сильнее. Меняйте такое значение в репозитории — там, где оно задано.

Такое поле не участвует и в сохранении: панель не запишет в настройки проекта значение, которое всё равно проиграет файлу.

Где должен лежать файл

• Обычный проект — в корне репозитория.
• Монорепо — в подпапке, которая указана в настройках проекта как папка приложения. Указали apps/web — Layero читает apps/web/layero.json.

Ошибка в файле не роняет сборку

Layero никогда не отказывается собирать проект из-за layero.json. Всё, что не удалось прочитать, становится замечанием в логе сборки и в панели:

что в файле	что делает Layero
невалидный JSON	сообщает и собирает так, как будто файла нет
неизвестное имя поля	сообщает, предлагает ближайшее известное, поле пропускает
пустое значение	сообщает, поле пропускает
framework, которого нет в репозитории	предупреждает и всё равно применяет

Замечания видны в мастере настройки и на странице деплоя, под содержимым самого файла.

Адрес схемы

https://layero.ru/schema/layero-v2.json

Прежний адрес продолжает работать и не будет удалён:

https://layero.ru/schema/layero-v1.json

Если в ваших репозиториях стоит v1, менять его не нужно — файл читается одинаково. В новых проектах указывайте v2: в нём описаны основные имена полей, и редактор не подчёркивает как ошибку то, что Layero принимает.