Ключи (env)

env.NAME — ключ проекта: токен, клиентский секрет, ключ карт, — который хранится вне кода: на этой машине — в файле проекта .env (NAME=value, рядом с app.json, никогда не уходит на платформу), на le.codes — в Project Settings → Keys. Серверный код (*.server.ts, Серверные функции) читает любой ключ. Приложение читает только ключи с именем PUBLIC_…: бандл приложения публичен, так что ключ, который несёт приложение, публичен уже по имени, а компиляция отвергает любое другое имя в коде приложения. Языковой модели проекта ключ не нужен: ai.

  • вызывать платный API с сервера с токеном, которого нет в коде (env.OPENAI_KEY)
  • использовать в приложении ключ карт или аналитики, не зашивая его в код (env.PUBLIC_MAPS_KEY)
  • держать токен бота или платёжный ключ вне репозитория и вне поля зрения ИИ
  • узнать, какого ключа не хватает, до того как упадёт первый вызов
  • быть уверенным, что секрет никогда не попадёт в бандл приложения

Обзор

TypeScript
# .env — next to app.json; the CLI never pushes it. Capital names, one per line.
OPENAI_KEY=sk-…            # server only
PUBLIC_MAPS_KEY=AIza…      # may be in the app: its name says so
TypeScript
// ask.server.ts — выполняется на бэкенде: здесь доступен любой ключ
export async function ask(question: string) {
  const r = await fetch("https://api.openai.com/v1/responses", {
    method: "POST",
    headers: { authorization: `Bearer ${env.OPENAI_KEY}`, "content-type": "application/json" },
    body: JSON.stringify({ model: "gpt-5", input: question }),
  })
  return (await r.json()).output_text as string
}
TypeScript
// main.ts — приложение: только ключи PUBLIC_
const places = await fetch(`https://maps.example/places?near=${lat},${lng}&key=${env.PUBLIC_MAPS_KEY}`)

Ключ — это string, никогда не string | undefined. Чтение незаданного ключа бросает EnvError, чьё сообщение называет ключ и место, куда его добавить: здесь — .env, на le.codes — Settings → Keys. На сервере это упавший вызов (500, причина — в консоли сервера); в приложении — исключение там, где стоит чтение. "OPENAI_KEY" in env спрашивает без исключения; Object.keys(env) перечисляет заданные ключи.

Где живёт ключ и когда он приходит

где работает приложение серверные ключи (env.NAME) ключи приложения (env.PUBLIC_NAME)
lecodes dev, lecodes test, lecodes render, desktop run .env проекта, читается при каждой перезагрузке — сохранение .env передеплоивает бэкенд .env проекта, вшивается в бандл при компиляции
превью le.codes и опубликованное приложение Project Settings → Keys, уходят на бэкенд с каждой сборкой Project Settings → Keys, вшиваются в бандл сборкой

Имена — заглавные латинские буквы, цифры и подчёркивания ([A-Z][A-Z0-9_]*, не длиннее 64). В .env лежат и собственные настройки CLI LECODES_* / CREATOR_*; это не ключи приложения.

Что проверяется при компиляции и деплое

  • Код приложения читает ключ не PUBLIC_… — ошибка компиляции с именем файла: main.ts: env.OPENAI_KEY. Читай его в файле *.server.ts и вызывай эндпоинт — или назови его PUBLIC_…, если приложению можно его нести.
  • Код приложения читает незаданный ключ PUBLIC_… — предупреждение компиляции; чтение бросает исключение, пока ключ не добавят.
  • Серверный код читает незаданный ключ — предупреждение при старте бэкенда (env: OPENAI_KEY not set), в терминале dev или в консоли сервера; падают только вызовы, которые его читают.
  • Значение секрета оказалось в бандле приложения — вставлено в код приложения или в ассет: компиляция отвергается (EnvLeakError). Значения короче 8 символов не ищутся.

Имена, которые читает серверный код, находит компиляция (env.NAME, env["NAME"]); динамическое чтение, env[name], проверяется только во время выполнения.

Чего нет

  • Разных значений для разных сборок (черновик / опубликованная): у проекта один набор ключей.
  • Ключа в общем модуле, который импортируют обе стороны: файл не *.server.ts — это код приложения, так что там разрешены только чтения PUBLIC_….