Project Structure

A typical djs-core bot looks like this:

my-bot/
├── src/
│   ├── interactions/
│   │   ├── commands/           # Slash commands → /ping, /admin kick
│   │   └── contexts/           # Context menus
│   │       ├── user/
│   │       └── message/
│   ├── events/                 # discord.js gateway events
│   ├── components/
│   │   ├── buttons/
│   │   ├── modals/
│   │   └── selects/
│   │       ├── string/
│   │       ├── user/
│   │       ├── role/
│   │       ├── channel/
│   │       └── mentionable/
│   └── cron/                   # optional — experimental.cron
├── db/                         # optional — when db: is configured
│   ├── schema.ts
│   └── migrations/
├── djs.config.ts
├── config.json                 # optional — experimental.userConfig
├── .env
├── .djscore/                   # auto-generated — do not edit
├── package.json
├── tsconfig.json
└── dist/                       # production build output

How routing works

File paths become command names and component customIds. Read the routing guide for the full mapping rules.

`src/interactions/commands/`

Slash commands. Folder depth creates subcommand groups.

File	Command
`ping.ts`	`/ping`
`admin/kick.ts`	`/admin kick`
`shop/buy.ts`	`/shop buy`

Colocate tests: ping.ts + ping.test.ts.

`src/interactions/contexts/`

Right-click user and message menus. Use user/ and message/ subfolders.

`src/events/`

Discord event listeners — flat files only (ready.ts, messageCreate.ts, …). Use Events.ClientReady, not deprecated Events.Ready.

`src/components/`

Reusable buttons, modals, and select menus. Imported into commands or other handlers.

Folder	Handler class
`buttons/`	`Button`
`modals/`	`Modal`
`selects/string/`	`StringSelectMenu`
`selects/user/`	`UserSelectMenu`
`selects/role/`	`RoleSelectMenu`
`selects/channel/`	`ChannelSelectMenu`
`selects/mentionable/`	`MentionableSelectMenu`

Component customId values come from the file path — see Routing.

`src/cron/`

Scheduled tasks when experimental.cron: true. Flat files — hourly-cleanup.ts registers task hourly-cleanup.

`db/`

Created by djs-core db init when using native database. Schema + Drizzle migrations. Not needed without db: in config.

Root files

File	Role
`djs.config.ts`	Token, servers, intents, `db`, plugins, experimental flags — Configuration
`config.json`	User-tunable bot settings when `experimental.userConfig` is on — User Config
`.env`	Secrets (`TOKEN`, `DATABASE_URL`, …) — never commit
`.djscore/`	Generated types for config, plugins, and database
`dist/`	Output of `djs-core build` — deploy this, not `src/`

Scaffolding files

djs-core generate command ping
djs-core generate button shop/buy
djs-core generate modal feedback
djs-core generate select string/pick-color
djs-core generate event messageCreate

See CLI Reference.

Run djs-core list anytime to see every registered route and its source file.