discord-starboard-plus/README.md

Discord Starboard Plus: A clean, maintainable starboard system for Discord.js bots. Features per-guild configuration, TypeScript support. Highlight your community's favorite messages with customizable starboards.

# ⭐ Discord Starboard Plus

[![npm version](https://img.shields.io/npm/v/discord-starboard-plus.svg?style=flat-square)](https://www.npmjs.com/package/discord-starboard-plus)
[![npm downloads](https://img.shields.io/npm/dm/discord-starboard-plus.svg?style=flat-square)](https://www.npmjs.com/package/discord-starboard-plus)
[![GitHub license](https://img.shields.io/github/license/GlamgarOnDiscord/discord-starboard-plus.svg?style=flat-square)](https://github.com/GlamgarOnDiscord/discord-starboard-plus/blob/master/LICENSE)

> A modern, TypeScript-first starboard system for Discord.js v14.25+. Highlight your community's favorite messages with customizable starboards, per-guild configuration, and Components V2 support.

> UPDATED ON 20/12/2025

## 🪐 Table of Contents
- [Features](#-features)
- [Installation](#-installation)
- [Usage](#-usage)
- [Options](#-options)
- [Per-Guild Configuration](#-per-guild-configuration)
- [Components V2](#-components-v2)
- [TypeScript](#-typescript)
- [Contributing](#-contributing)
- [License](#-license)

## 🚀 Features
- **TypeScript Support** - Full type definitions included
- **Per-Guild Configuration** - Different settings for each server
- **Components V2** - Modern Discord UI with containers and media galleries
- **Smart Search** - Paginated search (500+ messages) with ID-based matching
- **GIF & Video Support** - Properly handles all media types
- **Memory Safe** - Proper event listener cleanup with `destroy()` method
- **Custom Emojis** - Use any emoji for starring messages

## ⬇️ Installation

```sh
npm install discord-starboard-plus
```

**Requirements:** Node.js 18+ and discord.js 14.25+

## 📖 Usage

```js
const { Client, GatewayIntentBits, Partials } = require('discord.js');
const { Starboard } = require('discord-starboard-plus');

const client = new Client({
  intents: [
    GatewayIntentBits.Guilds,
    GatewayIntentBits.GuildMessages,
    GatewayIntentBits.GuildMessageReactions,
    GatewayIntentBits.MessageContent,
  ],
  partials: [Partials.Message, Partials.Channel, Partials.Reaction],
});

client.once('ready', () => {
  const starboard = new Starboard(client, {
    starboardChannelID: 'YOUR_CHANNEL_ID',
    requiredReactions: 3,
    starEmoji: '⭐',
    useComponentsV2: true,
  });
});

client.login('YOUR_BOT_TOKEN');
```

## ⚙️ Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `starboardChannelID` | `string` | *required* | Channel ID for starboard posts |
| `requiredReactions` | `number` | `1` | Minimum reactions to post |
| `starEmoji` | `string` | `'⭐'` | Emoji to watch for |
| `ignoreBots` | `boolean` | `true` | Ignore bot reactions |
| `ignoreSelf` | `boolean` | `false` | Ignore author self-reactions |
| `ignoredChannels` | `string[]` | `[]` | Channel IDs to ignore |
| `ignoreGuilds` | `string[]` | `[]` | Guild IDs to ignore |
| `updateOnReaction` | `boolean` | `true` | Update count on reaction change |
| `logActions` | `boolean` | `true` | Log to console |
| `embedColor` | `number` | `0xFFAC33` | Embed color (hex) |
| `maxAttachments` | `number` | `4` | Max attachments to show |
| `allowNSFW` | `boolean` | `false` | Allow NSFW channel messages |
| `jumpToMessage` | `boolean` | `true` | Add jump link |
| `showMessageDate` | `boolean` | `true` | Show message date |
| `maxSearchDepth` | `number` | `500` | Max messages to search |
| `useComponentsV2` | `boolean` | `false` | Use Discord Components V2 |

## 🌐 Per-Guild Configuration

```js
const starboard = new Starboard(client, defaultOptions);

// Set custom config for a specific guild
starboard.setGuildConfig('GUILD_ID', {
  starboardChannelID: 'DIFFERENT_CHANNEL_ID',
  requiredReactions: 5,
  starEmoji: '🌟',
});

// Get guild config
const config = starboard.getGuildConfig('GUILD_ID');

// Remove custom config (falls back to defaults)
starboard.removeGuildConfig('GUILD_ID');
```

## 🎨 Components V2

Enable modern Discord UI with containers, sections, and media galleries (discord.js 14.19+):

```js
new Starboard(client, {
  starboardChannelID: 'YOUR_CHANNEL_ID',
  useComponentsV2: true,
});
```

## 📘 TypeScript

```ts
import { Starboard, StarboardOptions } from 'discord-starboard-plus';

const options: StarboardOptions = {
  starboardChannelID: '123456789',
  requiredReactions: 3,
};

const starboard = new Starboard(client, options);
```

## 🧹 Cleanup

```js
// Remove event listeners on shutdown
starboard.destroy();
```

## 🤝 Contributing

Contributions are welcome! Open an issue or submit a pull request on [GitHub](https://github.com/GlamgarOnDiscord/discord-starboard-plus).

## 📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

## 👏 Credits

> Created by [glamgar](https://github.com/GlamgarOnDiscord)