ConfigurationCopy Anchor Link

Yurst is configured through environment variables. The only required variable is TOKEN; all others have default values.

The .env fileCopy Anchor Link

Create a .env file in the project root:

# Обов'язково
TOKEN=b.your_bot_token_here

# Опціонально
MODE=ws
YURST=dev
LOG_FILE=bot.log

Loading variablesCopy Anchor Link

Yurst automatically reads .env on import. Two methods are supported:

Recommended — passing via Node.js:

node --env-file=.env src/index.js

Automatic — Yurst looks for .env in the current working directory, and if it is not there — in the workspace root. Additionally, the path can be set with the YURST_ENV_FILE variable.

If a variable already exists in process.env, the value from .env will not overwrite it. This allows overriding configuration through the environment.

Environment variablesCopy Anchor Link

RequiredCopy Anchor Link

If TOKEN is not found, Yurst prints an error and terminates the process:

Yurst: TOKEN not found. Create .env with TOKEN=b.xxxx

TransportCopy Anchor Link

HTTP and APICopy Anchor Link

LoggingCopy Anchor Link

OtherCopy Anchor Link

Transport modesCopy Anchor Link

WebSocket (recommended)Copy Anchor Link

MODE=ws

Benefits:

• Instant receipt of updates
• Less load on the API
• Automatic reconnect with exponential backoff

If WebSocket is unavailable (Node < 22 without the ws package) or the connection fails WS_MAX_FAILS times in a row — Yurst automatically switches to polling.

Long PollingCopy Anchor Link

MODE=poll

Used when:

• WebSocket is unavailable in the environment
• Full control over requests is required
• MODE=poll is set explicitly

Learn more about how the transport works: Update transport.

Development modeCopy Anchor Link

For local development, enable detailed logs:

YURST=dev
YURST_LOG=debug

In dev mode:

• The logger outputs debug messages
• Raw updates (raw update) get into the logs
• HTTP request details are shown

Example logs in dev mode:

[info]  bot start | MODE=ws | node=v22.0.0 | DEV
[info]  bot Ani @ani_ id=2251
[info]  bot commands → 200 /ping[all] /help[all]
[debug] api GET /bot/me → 200 (156ms) {User: {...}}
[info]  update #12345 via=ws lag=1s | message /ping

Configuration examplesCopy Anchor Link

ProductionCopy Anchor Link

TOKEN=b.prod_token
MODE=ws
LOG_FILE=/var/log/bot.log
WS_MAX_FAILS=10

DevelopmentCopy Anchor Link

TOKEN=b.dev_token
MODE=ws
YURST=dev
YURST_LOG=debug
LOG_FILE=bot.log

Testing with pollingCopy Anchor Link

TOKEN=b.test_token
MODE=poll
YURST=dev
YURST_LOG=debug
POLL_TIMEOUT_S=10

The CFG objectCopy Anchor Link

After loading, the configuration is available inside the package as a frozen object:

// Внутрішня структура (не публічний експорт):
CFG = {
  mode: 'ws',           // 'ws' | 'poll'
  logFile: undefined,   // string | undefined
  wsIdleMs: 0,          // number
  wsMaxFails: 5,        // number
  maxText: 4000,        // number
  apiTimeoutMs: 10000,  // number
  pollTimeoutS: 30,     // number
};

Process environment variablesCopy Anchor Link

You can pass variables directly to the process:

TOKEN=b.xxx MODE=poll YURST=dev node src/index.js

Or through a CI/CD environment — this is safer than storing the token in a file.

NextCopy Anchor Link