ABOUTME: TypeScript skill for ecommerce monorepo with Next.js and Fastify

ABOUTME: Covers type patterns, Prisma, Zod, React Query, and testing conventions

TypeScript Skill (Ecommerce)

Quick Reference

Rule Convention

Strict mode Always enabled

Null checks strictNullChecks: true

Return types Explicit for public APIs

Zod schemas Validation at boundaries

Prisma types Auto-generated, never manual

Project Structure

apps/ ├── frontend/ # Next.js 16 │ ├── src/ │ │ ├── app/ # App Router pages │ │ ├── components/ # React components │ │ ├── hooks/ # Custom hooks (useProducts, useCart, etc.) │ │ ├── lib/ # Utilities (api.ts, auth-context.tsx) │ │ └── types/ # Type definitions │ └── tests/ # Frontend tests │ └── backend/ # Fastify API ├── src/ │ ├── config/ # Configuration │ ├── middleware/ # Auth guard, error handler │ ├── modules/ # Feature modules (auth, catalog, orders) │ └── utils/ # Prisma, Redis, logger ├── prisma/ # Schema and migrations └── tests/ # Backend tests

Type Patterns

API Response Types

// types/api.ts export interface ApiResponse<T> { data: T; meta?: { total: number; page: number; pageSize: number; }; }

export interface ApiError { statusCode: number; error: string; message: string; }

Zod Schemas (Validation)

// schemas/product.ts import { z } from 'zod';

export const ProductSchema = z.object({ id: z.string().uuid(), name: z.string().min(1).max(255), price: z.number().positive(), categoryId: z.string().uuid(), });

export type Product = z.infer<typeof ProductSchema>;

// Use at API boundaries const validated = ProductSchema.parse(requestBody);

Prisma Integration

// DON'T manually define DB types // DO use Prisma generated types import { User, Product, Order } from '@prisma/client';

// Include relations explicitly import { Prisma } from '@prisma/client';

type OrderWithItems = Prisma.OrderGetPayload<{ include: { items: { include: { product: true } } }; }>;

React Patterns

Custom Hooks

// hooks/useProducts.ts import { useQuery, useMutation, useQueryClient } from '@tanstack/react-query';

export function useProducts(categoryId?: string) { return useQuery({ queryKey: ['products', categoryId], queryFn: () => api.getProducts(categoryId), staleTime: 5 * 60 * 1000, // 5 minutes }); }

export function useCreateProduct() { const queryClient = useQueryClient();

return useMutation({ mutationFn: api.createProduct, onSuccess: () => { queryClient.invalidateQueries({ queryKey: ['products'] }); }, }); }

Component Props

// components/ProductCard.tsx interface ProductCardProps { product: Product; onAddToCart?: (productId: string) => void; className?: string; }

export function ProductCard({ product, onAddToCart, className }: ProductCardProps) { // ... }

Fastify Patterns

Route Types

// modules/catalog/catalog.routes.ts import { FastifyPluginAsync } from 'fastify'; import { z } from 'zod';

const GetProductParams = z.object({ id: z.string().uuid(), });

const catalogRoutes: FastifyPluginAsync = async (fastify) => { fastify.get<{ Params: z.infer<typeof GetProductParams>; }>('/products/:id', { schema: { params: GetProductParams, }, }, async (request, reply) => { const { id } = request.params; // ... }); };

export default catalogRoutes;

Error Handling

// middleware/error-handler.ts import { FastifyError, FastifyReply, FastifyRequest } from 'fastify';

export function errorHandler( error: FastifyError, request: FastifyRequest, reply: FastifyReply ) { const statusCode = error.statusCode ?? 500;

reply.status(statusCode).send({ statusCode, error: error.name, message: error.message, }); }

Testing Patterns

Unit Tests (Vitest)

// tests/hooks/useProducts.test.tsx import { renderHook, waitFor } from '@testing-library/react'; import { QueryClient, QueryClientProvider } from '@tanstack/react-query'; import { useProducts } from '@/hooks/useProducts';

const wrapper = ({ children }: { children: React.ReactNode }) => ( <QueryClientProvider client={new QueryClient()}> {children} </QueryClientProvider> );

describe('useProducts', () => { it('fetches products', async () => { const { result } = renderHook(() => useProducts(), { wrapper });

await waitFor(() => {
  expect(result.current.isSuccess).toBe(true);
});

expect(result.current.data).toHaveLength(18);

}); });

Integration Tests (Testcontainers)

// tests/integration/catalog.test.ts import { PostgreSqlContainer } from '@testcontainers/postgresql'; import { buildApp } from '../../src/app';

describe('Catalog API', () => { let container: StartedPostgreSqlContainer; let app: FastifyInstance;

beforeAll(async () => { container = await new PostgreSqlContainer().start(); process.env.DATABASE_URL = container.getConnectionUri(); app = await buildApp(); });

afterAll(async () => { await app.close(); await container.stop(); });

it('GET /products returns products', async () => { const response = await app.inject({ method: 'GET', url: '/api/products', });

expect(response.statusCode).toBe(200);

}); });

Commands

Type checking

npm run typecheck # All workspaces npm run typecheck -w apps/backend

Linting

npm run lint npm run lint:fix

Testing

npm run test # All tests npm run test -w apps/backend

Prisma

npm run db:generate -w apps/backend # Generate types npm run db:push -w apps/backend # Push schema npm run db:seed -w apps/backend # Seed data

Anti-Patterns

Anti-Pattern Problem Solution

any type No type safety Use unknown

• type guards

Manual DB types Drift from schema Use Prisma generated types

Implicit returns Unclear API Explicit return types

No validation Runtime errors Zod at boundaries

// @ts-ignore

Hidden bugs Fix the type issue

Checklist

Before committing TypeScript changes:

• No any types (use unknown if needed)

• Zod schemas for API inputs

• Prisma types for DB entities

• Tests cover new functionality

• npm run typecheck passes

• npm run lint passes