Express TypeScript API Development Assistant

This skill provides comprehensive guidance for developing Express.js API servers with TypeScript, focusing on best practices for AI-powered services, structured validation, and clean architecture patterns.

Project Architecture

When working with Express TypeScript projects following this pattern:

Core Structure

Development Workflow

**Available Commands:**

**Code Conventions:**

Validation System (Zod-based)

Implement ASP.NET-style model validation using Zod schemas:

Schema Organization

Validation Middleware Pattern

```typescript

import { validate } from '../../validation';

import { SeoImproveTextSchema, UserParamsSchema, SearchQuerySchema } from '../../models';

// Body validation

router.post('/improve-text', validate({

body: SeoImproveTextSchema

}), async (req, res) => {

// req.body is now validated and typed

});

// Parameter validation

router.get('/user/:userId', validate({

params: UserParamsSchema

}), async (req, res) => {

const { userId } = (req as any).validatedParams || req.params;

});

// Query validation

router.get('/search', validate({

query: SearchQuerySchema

}), async (req, res) => {

const { q, limit, offset } = (req as any).validatedQuery || req.query;

});

// File validation

router.post('/upload', upload.single('image'), validate({

file: {

fieldName: 'image',

maxSize: 10 * 1024 * 1024,

allowedMimeTypes: ['image/jpeg', 'image/png']

}

}), handler);

```

Error Handling

AI SDK Integration

When implementing AI-powered features:

Required Dependencies

Environment Configuration

Create `.env` file with:

Common AI Service Patterns

**Image Analysis Services** (`/v1/image/`):

**Text Enhancement Services** (`/v1/seo/`):

File Upload Handling

When implementing file upload endpoints:

Best Practices

1. **Type Safety**: Leverage TypeScript strict mode and Zod schema inference for end-to-end type safety

2. **Modular Routing**: Organize routes by version and domain (e.g., `/v1/image/`, `/v1/seo/`)

3. **Validation First**: Always validate inputs before processing using the `validate()` middleware

4. **Error Handling**: Implement consistent error responses across all endpoints

5. **Environment Variables**: Use dotenv for configuration and never commit `.env` files

6. **Code Quality**: Run ESLint and TypeScript compiler checks before committing

Common Tasks

Adding a New API Endpoint

1. Create Zod schema in `src/models/{domain}/`

2. Create route handler in `src/routes/v1/{domain}/`

3. Apply validation middleware with appropriate schema

4. Implement business logic with proper error handling

5. Add TypeScript types inferred from schemas

Integrating New AI Features

1. Ensure `OPENAI_API_KEY` is configured

2. Import AI SDK and OpenAI provider

3. Use GPT-4 Turbo model for high-quality results

4. Handle streaming responses when appropriate

5. Validate all inputs and outputs

Debugging Validation Issues

1. Check schema definitions in `src/models/`

2. Verify validation middleware is applied before route handler

3. Inspect error responses for field-level details

4. Use TypeScript compiler to catch type mismatches early