Robo File Structure

The file structure is the foundation of every Robo.js project. Directories and file names determine your project's functionality, similar to frameworks like Next.js.

Standard Structure

A standard Robo.js project contains the following directories:

You will spend most of your time in the /src directory, where your project's features live. The /config directory holds project and plugin configurations. Not every project needs all of these — only create the directories you use.

Depending on your setup, you may have additional files from tools like ESLint or Prettier.

Source Code

The /src directory is where your project's functionality is defined. Each subdirectory has a specific purpose and Robo.js uses the file structure to automatically register commands, events, routes, and more.

Any file type supported by Node.js works here, including JavaScript, TypeScript, and JSON. TypeScript works out of the box with no additional setup.

Commands

Files in src/commands/ become slash commands. The file name is the command name, and folders create subcommands.

See Commands for more details.

Events

Files in src/events/ handle Discord gateway events. The file name matches the event name. Multiple handlers for the same event go in a subfolder.

See Events for more details.

API Routes

Files in src/api/ become HTTP endpoints when using @robojs/server. The file path maps directly to the URL.

See Server Routing for more details.

Context Menus

Files in src/context/ register right-click context menu commands. Separate user/ and message/ subdirectories determine the target type.

See Context Menus for more details.

Middleware

Files in src/middleware/ intercept commands and events before they execute. Middleware runs in alphabetical order — use number prefixes to control the sequence.

See Middleware for more details.

Modules

Modules group related commands, events, and middleware into self-contained units inside src/modules/. Each module follows the same directory conventions as the top-level src/.

See Modules for more details.

Lifecycle Hooks

Files in src/robo/ hook into the Robo.js lifecycle. Each file runs at a specific phase — startup, shutdown, errors, or build.

See Lifecycle Hooks for more details.

Configuration

Config files live in the /config directory. The main config is robo.mjs (or .ts, .cjs, .json). Plugin configs are organized by scope inside config/plugins/.

Plugin config files are generated automatically when you run npx robo add. You may rarely need to edit these files directly.

See Configuration for more details.

Environment Variables

The .env file stores sensitive information such as API keys, database URLs, and Discord tokens. These variables are loaded into your project at startup.

See Environment Variables for more details.

.robo Directory

The /.robo directory is managed by Robo.js and contains generated files. You should not edit this directory manually.

Build

/.robo/build contains compiled output from your project. TypeScript files are compiled to JavaScript here, and production bundles are stored in this location.

For plugins, this is the directory that gets published to npm.

Data

/.robo/data contains Flashcore data. Flashcore uses the local filesystem by default but can be configured to use an external database.

Manifest

The /.robo/manifest.json file contains project metadata including the project name, version, registered plugins, and directory information. Robo.js generates and updates this file automatically for faster startup times.

Temp Files

The /.robo/temp directory appears occasionally and holds temporary files generated during runtime, such as intermediate files created during compression.

Full Example

Here is what a fully-featured Discord bot project looks like with commands, events, API routes, context menus, middleware, and modules:

Your project does not need all of these. Start with what you need and add directories as your project grows.

Next Steps