@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';

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

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

🧩 Creating a Controller

// 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:

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

Rate Limiting Example

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

CORS Example

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

📜 License

MIT © HarmonixJS