@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

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

✨ Quick Start

`js
import { Harmonix } from '@harmonixjs/core';
import { ExpressPlugin } from '@harmonixjs/express';

const bot = new Harmonix({
bot: {
token: "YOUR_BOT_TOKEN",
id: "YOUR_BOT_CLIENT_ID"
}
intents: [...],
plugins: [
new ExpressPlugin({
port: 3000,
controllersPath: './controllers'
})
]
});

bot.start();
`

📁 Example Project Structure

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

🧩 Creating a Controller

`ts
// controllers/UserController.ts
import { Controller, Get, Params, Bot } from '@harmonixjs/express';
import { Harmonix } from '@harmonixjs/core';

@Controller({ path: '/users' })
export class UserController {

@Get('/:id')
async getUser(@Params('id') id: string, @Bot() bot: Harmonix) {
const user = await bot.users.fetch(id);
return user ? { id: user.id, username: user.username } : { error: 'User not found' };
}

@Get('/search')
async search(@Query('q') query: string, @Bot() bot: Harmonix) {
const results = bot.users.cache.filter(u =>
u.username.toLowerCase().includes(query.toLowerCase())
);

return results.map(u => ({
id: u.id,
username: u.username,
tag: u.tag
}));
}
}
`

🔧 Auto-loading Controllers
Enable automatic controller loading:

`ts
new ExpressPlugin({
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

$3

`ts
new ExpressPlugin({
rateLimit: {
windowMs: 15 60 1000,
max: 100
}
});
`

$3

`ts
new ExpressPlugin({
cors: {
origin: 'https://yourdomain.com',
credentials: true
}
});
``

📜 License

MIT © HarmonixJS