@harmonixjs/express

A powerful Express-based HTTP API plugin for the Harmonix Discord framework.
This plugin provides decorators, routing, authentication, and direct bot access — allowing developers to build REST APIs that seamlessly integrate with their Discord bot logic.

---

🚀 Features

• ✔️ Express integration with automatic route binding
• ✔️ Decorator-based controllers & routes (@Controller(), @Get(), @Post(), etc.)
• ✔️ Decorator-based property injection (@Inject("...")) to automatically inject values from ExpressPluginConfig or the bot instance
• ✔️ Parameter injection (@Query(), @Params(), @Body(), @Headers(), @Req(), @Res(), @Bot())
• ✔️ JWT authentication support (@RequireAuth())
• ✔️ Custom middlewares + per-route middlewares
• ✔️ CORS configuration
• ✔️ Session support (cookies)
• ✔️ Auto-loading of controllers from a directory
• ✔️ Direct access to the Harmonix bot instance in any route
• ✔️ Fully type-safe with TypeScript

---

📦 Installation

npm install @harmonixjs/express express jsonwebtoken cookie-parser
npm install --save-dev @types/express @types/jsonwebtoken @types/cookie-parser

✨ Quick Start

import{Harmonix}from'@harmonixjs/core';import{ExpressPlugin}from'@harmonixjs/express';constbot=newHarmonix({bot: {token: "YOUR_BOT_TOKEN",id: "YOUR_BOT_CLIENT_ID"}intents: [...],plugins: [newExpressPlugin({port: 3000,controllersPath: './controllers'})]});bot.start();

📁 Example Project Structure

project/
├── controllers/
│ ├── UserController.ts
│ └── AuthController.ts
├── src/
│ └── index.ts
└── package.json

🧩 Creating a Controller

// controllers/UserController.tsimport{Controller,Get,Params,Bot}from'@harmonixjs/express';import{Harmonix}from'@harmonixjs/core';
@Controller({path: '/users'})exportclassUserController{
@Get('/:id')asyncgetUser(@Params('id')id: string, @Bot()bot: Harmonix){constuser=awaitbot.users.fetch(id);returnuser ? {id: user.id,username: user.username} : {error: 'User not found'};}
@Get('/search')asyncsearch(@Query('q')query: string, @Bot()bot: Harmonix){constresults=bot.users.cache.filter(u=>u.username.toLowerCase().includes(query.toLowerCase()));returnresults.map(u=>({id: u.id,username: u.username,tag: u.tag}));}}

🔧 Auto-loading Controllers Enable automatic controller loading:

newExpressPlugin({controllersPath: './controllers'});

All .ts/.js files inside the folder will be scanned and registered.

⚙️ Configuration Options

Option	Type	Description
port	number	Server port (default: 3000)
cors	boolean or object	Enable and configure CORS
jwt	JwtConfig	Enable JWT authentication
controllersPath	string	Directory to auto-load controllers from
middlewares	RequestHandler[]	Global middlewares
rateLimit	object	Enable rate limit on each routes

---

🛡️ Security

Rate Limiting Example

newExpressPlugin({rateLimit: {windowMs: 15*60*1000,max: 100}});

CORS Example

newExpressPlugin({cors: {origin: 'https://yourdomain.com',credentials: true}});

📜 License

MIT © HarmonixJS