ABOUTME: Architectural patterns skill for TypeScript ecommerce

ABOUTME: Covers DI, error handling, testing, and common anti-patterns

Design Patterns (Ecommerce)

Architectural patterns for the TypeScript/Node.js ecommerce stack.

Quick Reference

Pattern Frontend (Next.js) Backend (Fastify)

DI React Context Constructor injection

Errors Error boundaries Fastify error handler

Config env.local dotenv + config module

State React Query In-memory + Redis

Testing Testing Library Testcontainers

1. Dependency Injection

Backend (Fastify)

// Define interface interface UserRepository { findById(id: string): Promise<User | null>; create(data: CreateUserDto): Promise<User>; }

// Constructor injection class UserService { constructor( private readonly userRepo: UserRepository, private readonly logger: Logger ) {}

async getUser(id: string): Promise<User> { this.logger.info({ id }, 'Getting user'); const user = await this.userRepo.findById(id); if (!user) throw new NotFoundError(User ${id} not found); return user; } }

// Wire up in app const userRepo = new PrismaUserRepository(prisma); const userService = new UserService(userRepo, logger);

Frontend (React Context)

// Context for dependency injection const CartContext = createContext<CartContextValue | null>(null);

export function CartProvider({ children }: { children: React.ReactNode }) { const [items, setItems] = useState<CartItem[]>([]);

const addItem = useCallback((product: Product, quantity: number) => { setItems((prev) => [...prev, { product, quantity }]); }, []);

return ( <CartContext.Provider value={{ items, addItem }}> {children} </CartContext.Provider> ); }

export function useCart() { const context = useContext(CartContext); if (!context) throw new Error('useCart must be used within CartProvider'); return context; }

2. Error Handling

Backend (Fastify)

// Custom error classes class AppError extends Error { constructor( message: string, public statusCode: number = 500, public code: string = 'INTERNAL_ERROR' ) { super(message); this.name = 'AppError'; } }

class NotFoundError extends AppError { constructor(message: string) { super(message, 404, 'NOT_FOUND'); } }

class ValidationError extends AppError { constructor(message: string) { super(message, 400, 'VALIDATION_ERROR'); } }

// Error handler middleware function errorHandler(error: Error, request: FastifyRequest, reply: FastifyReply) { if (error instanceof AppError) { return reply.status(error.statusCode).send({ statusCode: error.statusCode, error: error.code, message: error.message, }); }

// Log unexpected errors request.log.error(error); return reply.status(500).send({ statusCode: 500, error: 'INTERNAL_ERROR', message: 'An unexpected error occurred', }); }

Frontend (Error Boundaries)

// Error boundary for React class ErrorBoundary extends React.Component<Props, State> { state = { hasError: false, error: null };

static getDerivedStateFromError(error: Error) { return { hasError: true, error }; }

componentDidCatch(error: Error, info: React.ErrorInfo) { console.error('Error caught:', error, info); }

render() { if (this.state.hasError) { return <ErrorFallback error={this.state.error} />; } return this.props.children; } }

// React Query error handling const { data, error } = useQuery({ queryKey: ['products'], queryFn: fetchProducts, retry: 3, onError: (error) => { toast.error(error.message); }, });

3. Configuration

Backend

// config/index.ts import { z } from 'zod';

const ConfigSchema = z.object({ NODE_ENV: z.enum(['development', 'production', 'test']).default('development'), PORT: z.coerce.number().default(4000), DATABASE_URL: z.string(), REDIS_HOST: z.string().default('localhost'), REDIS_PORT: z.coerce.number().default(6379), JWT_SECRET: z.string(), });

export type Config = z.infer<typeof ConfigSchema>;

export function loadConfig(): Config { const result = ConfigSchema.safeParse(process.env); if (!result.success) { console.error('Invalid configuration:', result.error.format()); process.exit(1); } return result.data; }

export const config = loadConfig();

Frontend

// next.config.js handles env // Access via process.env.NEXT_PUBLIC_*

// For runtime config const config = { apiUrl: process.env.NEXT_PUBLIC_API_URL || 'http://localhost:4000', environment: process.env.NODE_ENV, };

4. Testing Patterns

Prefer Real Over Mocks

// GOOD: Real database with Testcontainers describe('UserRepository', () => { let container: StartedPostgreSqlContainer; let prisma: PrismaClient;

beforeAll(async () => { container = await new PostgreSqlContainer().start(); prisma = new PrismaClient({ datasources: { db: { url: container.getConnectionUri() } }, }); });

afterAll(async () => { await prisma.$disconnect(); await container.stop(); });

it('creates a user', async () => { const repo = new PrismaUserRepository(prisma); const user = await repo.create({ email: 'test@example.com' }); expect(user.email).toBe('test@example.com'); }); });

// BAD: Excessive mocking it('creates a user', async () => { const mockPrisma = { user: { create: jest.fn().mockResolvedValue({ id: '1' }) } }; // This tests mock behavior, not real behavior });

Test Behavior, Not Implementation

// GOOD: Tests observable behavior it('rejects invalid email', async () => { const response = await app.inject({ method: 'POST', url: '/auth/register', payload: { email: 'invalid', password: 'secret123' }, }); expect(response.statusCode).toBe(400); expect(response.json()).toMatchObject({ error: 'VALIDATION_ERROR', }); });

// BAD: Tests internal implementation it('calls validateEmail function', async () => { const spy = jest.spyOn(validator, 'validateEmail'); await register({ email: 'test@example.com' }); expect(spy).toHaveBeenCalled(); // Who cares? });

5. Common Anti-Patterns

TypeScript

Anti-Pattern Problem Solution

any type No type safety Use unknown

• guards

// @ts-ignore

Hidden bugs Fix the type issue

Optional chaining abuse Hides nulls Explicit null checks

as casting Runtime errors Type guards

React

Anti-Pattern Problem Solution

Prop drilling Coupling Context or state lib

useEffect for data Race conditions React Query

Inline styles No reuse Tailwind classes

Index as key Render bugs Stable IDs

Fastify

Anti-Pattern Problem Solution

Sync in handlers Blocks event loop Always async

Global state Race conditions Inject dependencies

No validation Security risk Zod schemas

Catching all errors Hides bugs Let Fastify handle

6. Naming Conventions

Files

Components: PascalCase

src/components/ProductCard.tsx src/components/CartSummary.tsx

Hooks: camelCase with use prefix

src/hooks/useProducts.ts src/hooks/useCart.ts

Modules: kebab-case

src/modules/auth/auth.routes.ts src/modules/catalog/catalog.service.ts

Types: PascalCase

src/types/Product.ts src/types/Order.ts

Variables

// Constants: SCREAMING_SNAKE_CASE const MAX_RETRIES = 3; const DEFAULT_PAGE_SIZE = 20;

// Functions: camelCase function calculateTotal(items: CartItem[]): number {} async function fetchProducts(categoryId?: string): Promise<Product[]> {}

// Classes: PascalCase class OrderService {} class ProductRepository {}

// Interfaces: PascalCase (no I prefix) interface User {} interface CartItem {}

Resources

See references/typescript-patterns.md for more detailed examples.