Getting started

Let's get a bot answering /ping. You'll need Node.js 24.17 or newer, a Discord application with a bot token, and a server to test in.

InstallingCopy Anchor Link

Hyperion is in beta and runs on prerelease versions of discord.js v15 and @discordjs/builders, so install the beta with the exact versions it was built against:

npm install @hyperion-js/core@beta [email protected] @discordjs/[email protected]

Project layoutCopy Anchor Link

Hyperion finds your code by folder. Everything lives under src, next to your entry file:

Every folder is optional, so only create the ones you use. Subfolders are fine too; they're just for organising.

Your first commandCopy Anchor Link

Each file default-exports one handler, made with a define…() function. A command gets a builder from @discordjs/builders and a run() function:

// src/commands/ping.ts
import { ChatInputCommandBuilder } from "@discordjs/builders";
import { defineCommand } from "@hyperion-js/core";

export default defineCommand({
    builder: new ChatInputCommandBuilder()
        .setName("ping")
        .setDescription("Check whether the bot is responding."),
    run: async ctx => {
        await ctx.interaction.reply("Pong!");
    },
});

ctx.interaction is the regular discord.js interaction, so you reply the way you always have.

Creating the clientCopy Anchor Link

// index.ts
import { HyperionClient } from "@hyperion-js/core";

const token = process.env.DISCORD_TOKEN;
const applicationId = process.env.DISCORD_APPLICATION_ID;
const guildId = process.env.DISCORD_DEV_GUILD_ID;

if (!token || !applicationId || !guildId) {
    throw new Error("Missing bot configuration.");
}

const client = await HyperionClient.create({
    name: "MyBot",
    root: new URL("./", import.meta.url),
    discord: { intents: ["Guilds"] },
    commands: { applicationId, token, guildIds: [guildId] },
});

await client.login(token);

create() loads every handler and deploys your commands before it returns, so mistakes show up at startup rather than when someone clicks something. Logging in is a separate step.

Passing guildIds deploys to those servers only, which updates instantly and is perfect while you develop. Leave it out to deploy globally.

Hyperion doesn't read .env files for you. Set the variables however you normally start your bot.

Running itCopy Anchor Link

Run index.ts with a TypeScript runner such as tsx. There's no build step during development. Invite the bot to your test server, wait for the ready log, and type /ping. That's it!

Where nextCopy Anchor Link

• More command shapes, like /ticket close: commands.
• Buttons and menus: buttons and select menus.
• Only letting certain people run something: guards.