Understanding Internals

This page provides a simplified overview of how Robo.js works under the hood. Understanding these internals is not required, but it can help when debugging or extending the framework.

The Installed Package

The robo.js package consists of two components: the CLI and the Runtime.

CLI

The CLI is the primary interface for building and running your project. It handles configuration loading, file watching, automatic restarts, TypeScript compilation, and plugin installation. Commands like robo dev, robo build, and robo start are all part of the CLI.

During production, the CLI loads only the tools needed for the current task to minimize overhead.

Runtime

The Runtime operates alongside your code at execution time. It manages event routing, plugin loading, log management, and provides access to Robo APIs such as State, Flashcore, and the Portal. Sage Assist is also part of the Runtime.

Robo File Structure

Robo.js and its platform plugins require a specific organization of files. This consistent structure enables automatic command registration, event binding, and other convention-based features. See File Structure for details.

Build Process

Every Robo.js project goes through a build phase before execution. Run robo build before robo start for production deployments. During development, robo dev handles building automatically and rebuilds on every file change. Build output is stored in the .robo directory.

Manifest

During the build, Robo.js indexes all project files into a manifest (/.robo/manifest.json). This eliminates the need to walk the file tree at startup, resulting in faster boot times and a smaller memory footprint. The manifest also stores project metadata used by debugging tools and commands like robo invite.

TypeScript

TypeScript files are compiled to JavaScript and optimized during the build. This means hosting environments do not need TypeScript compilation capabilities, and there is no need for a TypeScript runtime like ts-node.

Plugins

Plugin files are also indexed during the build for faster startup. Since plugins are expected to be pre-built with robo build plugin before publishing, no TypeScript processing is needed for them at project build time. Plugins can also inject custom build steps, which is how Robo.js adapts to different platforms.

Lifecycle Hooks

Robo.js provides a file-based hook system through the src/robo/ directory. During startup, the framework executes hooks in a defined sequence: init (before manifest loading), prepare (after portal population), and start (main initialization). On shutdown, stop hooks run in reverse order — project first, then plugins. Additional hooks handle errors, HMR events, and build phases.

Plugins use the same mechanism to hook into the lifecycle. Hook execution supports a priority system where hooks with the same priority run in parallel, and different priorities run sequentially. See Lifecycle Hooks for the full reference.

Registration

Platforms like Discord require information about the slash commands your project registers. Robo.js handles this during the build process, sending registration updates automatically. The manifest tracks changes between builds so that API calls are only made when commands have actually changed.

Sage

Sage operates in several capacities within Robo.js.

Sage Assist

Sage Assist allows developers to return values directly from slash command handlers instead of calling interaction.reply() manually. It is a set of built-in abstractions that simplify the command authoring experience. Everything runs locally within the framework with no external server communication.

Sage Bot

Sage is also a Robo running on the official Robo.js Discord server. Users can interact with it to ask questions about the framework.

Sage CLI

The Sage CLI is a separate, optional CLI package useful during development. It provides framework upgrade automation, module-to-plugin conversion, and diagnostic tools. Because it is a standalone package, it does not add to the size of production deployments.

Next Steps