HTTP Overview
The @nyx-discord/http package lets an @discordjs/core bot receive interactions
and webhook events over HTTP, instead of through a gateway connection.
Discord sends each interaction as a POST request to your app's Interactions Endpoint URL, so a bot that only handles
commands and components doesn't need a long-lived connection at all. It can run on a regular server, or on serverless
platforms like Cloudflare Workers or Vercel.
The framework doesn't ship a server and never opens a port. Our client takes a request and returns a response, and you pass
requests to it from the server you already use: node:http, Express, Fastify, Hono, Next.js, Bun, Deno, Workers...
Installation
Installing
npm i @nyx-discord/http @discordjs/coreThe package re-exports @nyx-discord/djs-core, so commands, events, schedules and everything else are imported from @nyx-discord/http. Everything in this guide that applies to @discordjs/core applies here too.
Creating the bot
HttpBot.create() works like @nyx-discord/djs-core's Bot.create(), but takes your application's ID and public key (both on the Developer Portal) instead of a client, and creates the client for you. Bot from @nyx-discord/http is HttpBot, so examples using Bot.create() or the Bot type work as-is:
import { } from '@nyx-discord/http';
const = .(() => ({
: .APP_ID,
: .DISCORD_PUBLIC_KEY,
: .TOKEN,
: ,
: true,
}));
await .();
const client = .();Requests are answered with 503 until bot.start() finishes, so nothing reaches your commands before they're registered.
Mounting the client
Pass incoming requests to the client from your server. See Mounting for each backend:
import { } from 'node:http';
import { } from '@nyx-discord/http';
((.())).(3000);Setting the endpoint
On the Developer Portal, set your app's Interactions Endpoint URL to the public URL of that route. Discord sends a PING to check it, which the client answers by itself.
What's different from the gateway
- Only interactions (
InteractionCreate) and webhook events are emitted. Subscribers to any other gateway event (messages, members, guilds...) never fire. - Commands work unchanged: they reply through
api.interactions.reply()and friends, as they do on the gateway. See Handling requests. - Schedules run while the process is alive. On serverless platforms, triggering them (e.g. with Workers cron triggers) is up to you, see Serverless.
- Only the
@discordjs/coreadapter is supported, since discord.js structures need a gateway-backedClient.
Getting the bot
Inside commands, subscribers and schedules, TypedFields.getBot() gets the bot from the metadata, typed so its client is the HttpNyxClient (a shorthand for TypedFields.HttpBot.get(meta, true)):
import { , , type } from '@nyx-discord/http';
class extends {
protected readonly = '0 * * * *';
public async (: ) {
const = .();
const client = .();
// Shorthand for bot.getClient().getApi(), the REST API
const = .();
}
}@nyx-discord/http exports its own TypedFields, without @nyx-discord/djs-core's GatewayCoreBot and getClient(), since HTTP bots have no gateway client.
Last updated on
