WolfStar.rocks

The official web dashboard for WolfStar, a Discord moderation bot.

Official Site · Blog · WolfStar Invite Link · Support Server · Feedback

Share WolfStar Repository

^{Pioneering the new age of server moderation management. Built for you, the Super Admin.}

Table of contents

Table of Contents

• ✨ Features
• 🛳 Self-Hosting WolfStar.rocks
• 🚀 Self-Hosting WolfStar.rocks Requirements
• ⌨️ Local Development
• 💻 Online Development
• 🤝 Contributing
• ❤️ Sponsor

👋🏻 Welcome to WolfStar.rocks

WolfStar.rocks is the official web dashboard for WolfStar, a Discord moderation bot. It gives your team one place to configure filters and server settings, and to review moderation, command, and settings history.

✨ Features

• Modern Web Interface: Built with Nuxt 4 and modern web technologies for a smooth user experience.
• Server Management: Manage your Discord server's settings, roles, and permissions through an intuitive web interface.
• Responsive Design: Works seamlessly on desktop, tablet, and mobile devices.
• OAuth Integration: Secure Discord authentication and authorization.
• Audit Trail: Dashboard settings changes and denied access attempts are recorded in a tamper-evident audit log. Each event is persisted to PostgreSQL with a SHA-256 hash chain, and pnpm audit:verify replays the chain to verify it.
• Multi-language Dashboard: The dashboard is translated through Tolgee, and /translation-status shows how far each language has come.
• Accessibility: Built with semantic HTML, keyboard navigation, and reduced-motion support.

On the roadmap

• Real-time Updates: Live updates for guild data and bot status.
• Dashboard Analytics: Server statistics and bot usage metrics.

🚀 Self-Hosting WolfStar.rocks Requirements

• Node.js: WolfStar.rocks is built on Node.js, so you will need to have Node.js (v24+) installed.
• WolfStar Bot: You need a running instance of WolfStar bot to connect this dashboard to.
• Discord Bot Application: A Discord bot application with proper OAuth2 configuration.
• PostgreSQL: PostgreSQL database (shared with WolfStar bot instance).

🛳 Self-Hosting WolfStar.rocks

Quick Setup

1. Clone the repository

   git clone https://github.com/wolfstar-project/wolfstar.rocks.git
   cd wolfstar.rocks

2. Install dependencies

   pnpm install

3. Environment Configuration

   • Duplicate .env.example and rename it to .env.
   • Fill in all required environment variables.
   • Configure Discord OAuth2 settings in your Discord Developer Portal.

4. Database Setup

   • Ensure your WolfStar bot database is accessible.
   • Run database migrations if needed.

5. Start the development server

   pnpm dev

Environment Variables

1. Duplicate .env.example and rename it to .env.
2. Fill in all required environment variables.
3. Configure Discord OAuth2 settings in your Discord Developer Portal.

Discord OAuth2 Configuration

1. Go to the Discord Developer Portal.
2. Select your bot application.
3. Navigate to the OAuth2 tab.
4. Add redirect URLs:
   • http://localhost:3000/oauth/callback
   • http://localhost:3000/oauth/guild
5. Save your changes.

Available Scripts

• pnpm dev - Start development server.
• pnpm dev:pwa - Start development server with PWA support.
• pnpm build - Build for production.
• pnpm preview - Preview production build.
• pnpm lint:fix - Run Oxlint & Oxfmt and fix issues.
• pnpm prisma:migrate:dev - Create and apply a new migration in development.
• pnpm prisma:migrate:diff - Check for schema drift between migrations and schema (exits with error if differences found).
• pnpm prisma:migrate:deploy - Apply all pending migrations to the database.
• pnpm prisma:push - Push the Prisma schema to the database without generating a migration.
• pnpm prisma:seed - Seed the database with initial data.
• pnpm prisma:studio - Open Prisma Studio for database management.
• pnpm prisma:generate - Generate Prisma client.
• pnpm test - Run all tests.
• pnpm test:unit - Run unit tests.
• pnpm test:nuxt - Run Nuxt environment tests.
• pnpm test:browser - Run browser tests with Playwright.
• pnpm test:bench - Run performance benchmarks.
• pnpm typecheck - Run TypeScript checks.

Occasional one-off tasks are not wrapped in package.json. Run their binary directly instead:

• pnpm exec prisma migrate dev --create-only - Create a migration without applying it.
• pnpm exec prisma migrate status - Check the status of migrations.
• pnpm exec prisma migrate resolve - Mark a migration as applied or rolled back.
• pnpm exec prisma migrate reset - Reset the local database.
• pnpm exec prisma generate --watch - Regenerate the Prisma client on change.
• pnpm exec pwa-assets-generator - Generate PWA icons and assets.
• pnpm exec taze - Interactive dependency updates.

Testing & Benchmarks

Running Tests

• pnpm test - Run all tests with Vitest
• pnpm test:unit - Run unit tests only (Node.js environment)
• pnpm test:nuxt - Run Nuxt component tests (Nuxt environment with browser)
• pnpm test:browser - Run full browser E2E tests with Playwright
• pnpm test:bench - Run performance benchmarks

Performance Benchmarks

WolfStar.rocks uses CodSpeed for continuous performance tracking. Benchmarks automatically run in CI on every commit and PR, with results visible on the CodSpeed dashboard.

Currently Benchmarked:

• shared/utils/comparators.ts
  • Functions: differenceArray, differenceMap
  • Benchmark: test/unit/shared/utils/comparators.bench.ts
• server/utils/guildNameToAcronym.ts
  • Function: guildNameToAcronym
  • Benchmark: test/unit/server/utils/guild-name-to-acronym.bench.ts

Adding New Benchmarks:

1. Create a .bench.ts file under test/unit/ mirroring the path of the code you're benchmarking (e.g., for shared/utils/myUtil.ts, create test/unit/shared/utils/myUtil.bench.ts)
2. Import the utility and Vitest's bench() function:

   import { bench, describe } from "vitest";
   import { myUtility } from "../../../../shared/utils/myUtility";

3. Write benchmarks with descriptive names:

   describe("myUtility benchmarks", () => {
     bench("small dataset (10 items)", () => {
       myUtility(smallData);
     });
     bench("large dataset (1000 items)", () => {
       myUtility(largeData);
     });
   });

4. Run locally: pnpm test:bench
5. CI will automatically track performance when you open a PR

Development Guidelines

• Follow the existing code style and conventions.
• Write clear, descriptive commit messages.
• Add tests for new features.
• Update documentation as needed.
• Ensure all CI checks pass.

Development Tools

• Nuxt 4 - Vue.js framework
• TypeScript - Type safety
• Oxlint - Code linting
• Oxfmt - Code formatting
• Prisma - Database ORM
• Tailwind CSS - Utility-first CSS framework
• Nuxt UI - Vue component library and design tokens

AI Development Assistant

• Custom GitHub Copilot Agent - Specialized WolfStar development agent with Context7 MCP integration (see .github/agents/wolfstar-dev-agent.md).
• Autonomous Problem-Solving - Beast Mode with iterative refinement.
• Real-time Documentation - Up-to-date library docs via Context7.
• Quality First - Integrated Oxlint, Sentry, and testing workflows.

⌨️ Local Development

Refer to CONTRIBUTING.md for detailed setup instructions.

💻 Online Development

Click any of the buttons below to start a new development environment to demo or contribute to the codebase without having to install anything on your machine:

🤝 Contributing

Thank you to all the people who already contributed to WolfStar.rocks! Please make sure to read the Contributing Guide before making a pull request.

❤️ Sponsor

If you like WolfStar and want to support the project, consider making a donation. Every contribution helps to maintain and improve the bot.

Thank you for your support!

---

---

📝 License

Copyright © 2024 WolfStar.
This project is Apache 2.0 licensed.