Bun Server Skills Index & Best Practices
This skill provides an overview of all available skills for the Bun Server framework and guides you to the right resource.
Available Skills
Getting Started
| Skill | When to Use |
|---|---|
| quickstart | New project setup, TypeScript configuration, first application |
Core Framework
| Skill | When to Use |
|---|---|
| dependency-injection | @Injectable, @Inject, DI scopes, Symbol+Interface pattern |
| controller-routing | @Controller, HTTP methods, route parameters, request/response |
| module-system | @Module, imports/exports, forRoot pattern, modular architecture |
| middleware | Custom middleware, interceptors, CORS, rate limiting |
| validation | @IsString, @IsEmail, DTOs, custom validators |
| error-handling | HttpException, exception filters, error responses |
Official Modules
| Skill | When to Use |
|---|---|
| security | JWT, OAuth2, @UseGuards, @Roles, authentication |
| database | DatabaseModule, ORM, @Entity, @Repository, @Transactional |
| cache | @Cacheable, @CacheEvict, Redis cache |
| queue | @Queue, @Cron, background jobs, scheduled tasks |
| session | SessionModule, session storage, user state |
| events | EventModule, @OnEvent, event-driven architecture |
| websocket | @WebSocketGateway, real-time communication |
| swagger | SwaggerModule, OpenAPI, @ApiOperation |
| health-metrics | HealthModule, MetricsModule, Prometheus |
| logger | LoggerModule, log levels, structured logging |
Microservices
| Skill | When to Use |
|---|---|
| microservice | Service discovery, config center, circuit breaker, tracing |
Troubleshooting
| Skill | When to Use |
|---|---|
| troubleshooting | Debugging, common errors, "not working" issues |
Quick Reference by Task
"I want to create a new project"
→ Start with quickstart
"I need to add authentication"
→ Use security for JWT/OAuth2 and guards
"I want to validate user input"
→ Use validation for DTO validation
"I need to cache expensive operations"
→ Use cache for @Cacheable decorator
"I want to run background jobs"
→ Use queue for job queues and @Cron
"I need real-time features"
→ Use websocket for WebSocket gateways
"I want to build microservices"
→ Use microservice for service discovery and governance
"Something is not working"
→ Check troubleshooting for common issues
Best Practices Summary
Project Structure
code
src/
├── main.ts # Entry point
├── app.module.ts # Root module
├── common/ # Shared utilities
│ ├── middleware/
│ ├── filters/
│ └── guards/
├── users/ # Feature module
│ ├── user.module.ts
│ ├── user.controller.ts
│ ├── user.service.ts
│ └── dto/
└── orders/ # Feature module
├── order.module.ts
└── ...
Module Configuration Order
typescript
// 1. Configure global modules FIRST
ConfigModule.forRoot({ defaultConfig: {} });
LoggerModule.forRoot({ level: LogLevel.INFO });
EventModule.forRoot({ wildcard: true });
// 2. THEN define modules
@Module({
imports: [ConfigModule, LoggerModule, EventModule],
})
class AppModule {}
TypeScript Configuration (Required)
json
{
"compilerOptions": {
"experimentalDecorators": true,
"emitDecoratorMetadata": true
}
}
Symbol + Interface Pattern
typescript
// Define interface and Symbol with same name
interface UserService {
find(id: string): Promise<User>;
}
const UserService = Symbol("UserService");
// Register in module
@Module({
providers: [{ provide: UserService, useClass: UserServiceImpl }],
})
// Import as value, not type
import { UserService } from "./user.service"; // ✅
import type { UserService } from "./user.service"; // ❌
Error Handling
typescript
// Use built-in exceptions
throw new NotFoundException("User not found");
throw new BadRequestException("Invalid input");
// Or custom exceptions
class UserNotFoundException extends HttpException {
constructor(id: string) {
super(404, `User ${id} not found`);
}
}
Testing
bash
# Run tests in package directory bun --cwd=packages/bun-server test # Run specific test bun --cwd=packages/bun-server test user.test.ts