Best Practices

Production-ready patterns, security guidelines, and optimization strategies for building robust IGNIS applications. These best practices are distilled from real-world experience building enterprise applications.

Architecture

Layered architecture, DI, components, lifecycle hooks

Code Standards

Naming, types, patterns, oxlint, bun fmt

Security

Auth, validation, secrets, CORS, rate limiting

Data Modeling

Schemas, enrichers, relations, migrations

Testing

Unit tests, integration tests, mocking

Performance

Query optimization, caching, pooling

Error Handling

Error patterns, logging, user-friendly messages

Deployment

Docker, Kubernetes, cloud platforms, CI/CD

Learning Path

1

Foundation

Architecture → Decisions Guide → Code Standards

Understand patterns and establish coding conventions

2

Data Layer

Data Modeling → API Patterns → Error Handling

Design your data layer and handle edge cases

3

Quality Assurance

Testing → Avoid Pitfalls → Troubleshooting

Write tests and prevent common mistakes

4

Production Ready

Security → Performance → Deployment

Secure, optimize, and deploy your application

Quick Reference

Essential Patterns

// ✅ Layered Architecture
Controller → Service → Repository → DataSource

// ✅ Dependency Injection
@inject({ key: BindingKeys.build({ namespace: BindingNamespaces.SERVICE, key: UserService.name }) })

// ✅ Error Handling
throw getError({ statusCode: 404, message: 'User not found' });

// ✅ Scoped Logging (ILogger - never names a provider)
this.logger.for('createUser').info('User created | id: %s', user.id);

// ✅ Input Validation
request: { body: jsonContent({ schema: z.object({ email: z.string().email() }) }) }

Anti-Patterns to Avoid

// ❌ Business logic in controllers
@get({ configs: RouteConfigs.GET_USER })
async getUser(context: TRouteContext) {
  const { id } = context.req.valid<{ id: string }>('param');
  const user = await this.userRepository.findById({ id });
  if (user.lastLogin < cutoff) await this.sendReminder(user); // Move to service!
  return context.json(user, HTTP.ResultCodes.RS_2.Ok);
}

// ❌ Catching all errors silently
try { await riskyOperation(); } catch (e) { /* swallowed */ }

// ❌ Raw Error - loses statusCode, messageCode and the normalized response shape
throw new Error('User not found'); // Use getError()

// ❌ Using `any` type
const data: any = await fetchData(); // Use proper types!

Security Checklist

Check	Action
Secrets	Store in environment variables, never in code
Input	Validate with Zod schemas at API boundaries
Auth	Protect routes with authenticate: { strategies: [Authentication.STRATEGY_JWT] }
Sensitive data	Use hiddenProperties in model settings
File uploads	Use sanitizeFilename() for all user-provided filenames
CORS	Configure allowed origins explicitly

Performance Checklist

Check	Action
Queries	Use fields to select only needed columns
Pagination	Always set limit on find operations
Relations	Limit include depth to 2 levels max
Connection pool	Configure pool size based on load
Background jobs	Offload CPU-intensive tasks to workers
Caching	Cache expensive queries with Redis

All Best Practices

Architecture & Design

Guide	Description
Architectural Patterns	Layered architecture, DI, components, mixins
Architecture Decisions	When to use services, repositories, components

Development

Guide	Description
Code Style Standards	Naming conventions, types, oxlint, bun fmt
Data Modeling	Schema design, enrichers, relations, migrations
API Usage Examples	Routing, repositories, middleware, services

Quality

Guide	Description
Testing Strategies	Unit tests, integration tests, mocking, E2E
Error Handling	Error patterns, structured errors, logging
Common Pitfalls	Mistakes to avoid and how to fix them
Troubleshooting Tips	Debug common issues quickly

Production

Guide	Description
Security Guidelines	Authentication, validation, secrets, CORS
Performance Optimization	Query optimization, caching, connection pooling
Deployment Strategies	Docker, Kubernetes, cloud platforms, CI/CD

Contributing

Guide	Description
Contribution Workflow	Git workflow, PR guidelines, code review

New to IGNIS?

Start with the Getting Started Guide for tutorials, then return here for production-ready patterns.

Production Deployment?

Before deploying, review the Security Guidelines and Deployment Strategies thoroughly.

See Also

• Getting Started - New to IGNIS? Start here
• API Reference - Detailed API documentation
• Core Concepts - Deep dive into architecture
• Changelogs - Version history and updates