Concepts

Project manifest

Every scaffolded project includes a ForgeLoop manifest: project name, preset, language, packageManager, enabled features (database, tooling, git, docker, CI), and the generated path layout. The manifest is written to disk as forgeloop.config.mjs and is what forgeloop info and forgeloop doctor read.

Config file

ForgeLoop reads exactly one config file: forgeloop.config.mjs.

The generated file is a plain default export, so it stays readable and loadable without any package-level helper.

Presets

Preset	Layout	add / commands
basic	Slash command and clientReady live inline in src/index.*	Not available — no src/commands or src/events folders.
modular	src/commands, src/events, src/interactions, src/sync-commands.*, loaders in src/index.*	Supported
advanced	Same handler folders plus src/core (e.g. start-bot, database client)	Supported

Package manager metadata

package.json includes a packageManager field (e.g. npm@10, pnpm@10.22.0) so tooling can infer the intended client. Scripts use the same manager you selected at init (dev, start, db:push, etc.).

Command sync vs commands deploy

• Modular / advanced starters include syncCommands, which runs when the bot starts: guild sync when NODE_ENV is not production (uses GUILD_ID), global sync when NODE_ENV === 'production'.
• forgeloop commands deploy pushes the current application command definitions from disk without starting the bot. Target rules: use --guild to force guild sync, --global to force global sync; otherwise production -> global, non-production -> guild. See commands.

Working directory

Commands that operate on an existing project accept --dir path. If omitted, the current working directory is used.

Component interactions (modular / advanced)

Modal, button, and string-select handlers live under src/interactions/. The generated router.ts dispatches interactionCreate: slash and context-menu commands use client.commands; components use exact customId, then flex handlers — customIdRegExp (full-string match), parseCustomId (parsed value passed to execute), or matchCustomId (boolean) — ordered by interactionRoutePriority then file load order. Prefer ^ … $ for regexes. For large or sensitive payloads, use a short token in the ID plus interaction-sessions or Redis for multi-shard bots.

---

Next: try a workflow or skim the command reference.