packages-rules

Backend Packages Rules

Package Overview

Core (@projectx/core)

• Purpose: Shared backend utilities, authentication, health checks, logging
• Module System: Dual (CJS + ESM via tsup)
• Exports: AuthService, JwtAuthGuard, HealthModule, Logger utilities
• Dependencies: NestJS, Passport, JWT

DB (@projectx/db)

• Purpose: Prisma client and database utilities
• Module System: Dual (CJS + ESM via tsup)
• Exports: PrismaService, DbModule, Prisma client
• Database: PostgreSQL with PostGIS extension

Email (@projectx/email)

• Purpose: Email sending via SendGrid
• Module System: Dual (CJS + ESM via tsup)
• Exports: EmailService, EmailModule
• Provider: SendGrid

Payment (@projectx/payment)

• Purpose: Stripe payment integration
• Module System: Dual (CJS + ESM via tsup)
• Exports: StripeService, PaymentModule
• Provider: Stripe

Workflows (@projectx/workflows)

• Purpose: Temporal workflow client and worker management
• Module System: Dual (CJS + ESM via tsup)
• Exports: ClientService, WorkerService, WorkflowsModule
• Integration: Temporal.io

Build Configuration

All packages use tsup for dual builds

{
  "scripts": {
    "build": "tsup src/index.ts --format cjs,esm --sourcemap --clean"
  }
}

Build outputs:

• dist/index.js - CommonJS (for NestJS apps)
• dist/index.mjs - ESM (for web app)
• dist/index.d.ts - TypeScript declarations
• Source maps for both formats

Critical: Declaration files

# Always generate declaration files
tsup src/index.ts --format cjs,esm --sourcemap --clean && \
tsc -p tsconfig.json --emitDeclarationOnly --outDir dist

Package: @projectx/core

Exports

// Authentication
export { AuthService } from './lib/auth/auth.service';
export { JwtAuthGuard } from './lib/auth/auth.guard';
export { JwtStrategy } from './lib/auth/jwt.strategy';
export { AuthModule } from './lib/auth/auth.module';
// Decorators
export { AuthenticatedUser } from './lib/auth/auth.decorator';
// Health checks
export { HealthModule } from './lib/health/health.module';
// Logger
export { createLoggerOptions } from './lib/logger';
// Workflows (Temporal)
export { 
  verifyLoginCodeUpdate,
  createOrderUpdate,
  getOrderStateQuery,
  cancelWorkflowSignal,
  paymentWebHookEventSignal 
} from './workflows';
// Types
export type { AuthUser, OrderWorkflowData, PaymentWebhookEvent };