🇺🇸English

Koa TypeScript Development

You are an expert in Koa.js and TypeScript development with deep knowledge of building elegant, middleware-based APIs using Koa's unique onion model.

TypeScript General Guidelines

Basic Principles

• Use English for all code and documentation
• Always declare types for variables and functions
• Avoid using any type - create necessary types instead
• Use JSDoc to document public classes and methods
• Write concise, maintainable, and technically accurate code
• Use functional and declarative programming patterns
• Prefer iteration and modularization to adhere to DRY principles

Nomenclature

• Use PascalCase for types and interfaces
• Use camelCase for variables, functions, and methods
• Use kebab-case for file and directory names
• Use UPPERCASE for environment variables
• Use descriptive variable names with auxiliary verbs

Functions

• Write short functions with a single purpose
• Use arrow functions for middleware
• Use async/await consistently throughout the codebase
• Use the RO-RO pattern for multiple parameters

Koa-Specific Guidelines

Project Structure

src/
  routes/
    {resource}/
      index.ts
      controller.ts
      validators.ts
  middleware/
    auth.ts
    errorHandler.ts
    requestId.ts
    logger.ts
  services/
    {domain}Service.ts
  models/
    {entity}.ts
  utils/
  config/
  app.ts
  server.ts

Middleware Patterns

Koa uses a unique "onion" middleware model. Middleware functions are composed and executed in a stack-like manner.

import { Middleware } from 'koa';

// Middleware pattern with async/await
const responseTime: Middleware = async (ctx, next) => {
  const start = Date.now();
  await next();
  const ms = Date.now() - start;
  ctx.set('X-Response-Time', `${ms}ms`);
};

• Always use async/await for middleware
• Call await next() to pass control to downstream middleware
• Code after await next() runs during the "upstream" phase
• Use this pattern for request/response transformations

Context (ctx) Best Practices

• Use ctx.state to pass data between middleware

• Type your context for better type safety

• Avoid mutating context directly when possible

• Use context for request/response access

  import { ParameterizedContext, Middleware } from 'koa';

  interface AppState { user?: User; requestId: string; }

  type AppContext = ParameterizedContext<AppState>;

  const authMiddleware: Middleware<AppState> = async (ctx, next) => { ctx.state.user = await validateToken(ctx.headers.authorization); await next(); };

Application Setup

import Koa from 'koa';
import Router from '@koa/router';
import bodyParser from 'koa-bodyparser';
import cors from '@koa/cors';
import helmet from 'koa-helmet';
import { errorHandler } from './middleware/errorHandler';
import { requestLogger } from './middleware/logger';

const app = new Koa();

// Error handling (first in chain)
app.use(errorHandler);

// Security
app.use(helmet());
app.use(cors());

// Body parsing
app.use(bodyParser());

// Logging
app.use(requestLogger);

// Routes
app.use(router.routes());
app.use(router.allowedMethods());

export default app;

Routing with koa-router

• Use koa-router for declarative routing

• Organize routes by resource

• Keep route handlers thin

• Use middleware for cross-cutting concerns

  import Router from '@koa/router'; import * as controller from './controller'; import { validateUserInput } from './validators';

  const router = new Router({ prefix: '/api/users' });

  router.get('/', controller.listUsers); router.get('/:id', controller.getUser); router.post('/', validateUserInput, controller.createUser); router.put('/:id', validateUserInput, controller.updateUser); router.delete('/:id', controller.deleteUser);

  export default router;

Error Handling

• Create centralized error handling middleware

• Place error handler at the top of the middleware stack

• Use custom error classes for different error types

• Never expose internal error details in production

  import { Middleware } from 'koa';

  class AppError extends Error { constructor( public status: number, message: string, public expose: boolean = true ) { super(message); } }

  const errorHandler: Middleware = async (ctx, next) => { try { await next(); } catch (err) { const error = err as Error & { status?: number; expose?: boolean }; ctx.status = error.status || 500; ctx.body = { error: { message: error.expose ? error.message : 'Internal Server Error', ...(process.env.NODE_ENV === 'development' && { stack: error.stack }) } }; ctx.app.emit('error', err, ctx); } };

Request Validation

• Use koa-joi-router or Zod for validation

• Validate body, query, and params

• Return clear validation error messages

• Create reusable validation middleware

  import { z } from 'zod'; import { Middleware } from 'koa';

  const createUserSchema = z.object({ name: z.string().min(1), email: z.string().email(), });

  const validate = (schema: z.ZodSchema): Middleware => { return async (ctx, next) => { try { ctx.request.body = schema.parse(ctx.request.body); await next(); } catch (error) { if (error instanceof z.ZodError) { ctx.status = 400; ctx.body = { errors: error.errors }; return; } throw error; } }; };

Authentication

• Implement JWT authentication with koa-jwt

• Store authenticated user in ctx.state.user

• Create authorization middleware for role-based access

  import jwt from 'koa-jwt';

  app.use(jwt({ secret: process.env.JWT_SECRET }).unless({ path: [/^/public/] }));

  const requireRole = (role: string): Middleware => { return async (ctx, next) => { if (ctx.state.user?.role !== role) { ctx.throw(403, 'Forbidden'); } await next(); }; };

Security

• Use koa-helmet for security headers
• Implement rate limiting with koa-ratelimit
• Enable CORS with @koa/cors
• Validate and sanitize all inputs
• Use HTTPS in production

Testing

• Use Jest or Mocha for testing

• Use supertest with app.callback() for integration tests

• Test middleware in isolation

• Mock context for unit tests

  import request from 'supertest'; import app from '../app';

  describe('GET /api/users', () => { it('should return users list', async () => { const response = await request(app.callback()) .get('/api/users') .expect(200);

  expect(response.body).toBeInstanceOf(Array);
  

  }); });

Performance

• Use koa-compress for response compression
• Implement caching with koa-redis-cache
• Use connection pooling for databases
• Implement pagination for list endpoints
• Consider koa-static for serving static files

Environment Configuration

• Use dotenv for environment variables
• Validate required environment variables at startup
• Create separate configs for different environments
• Never commit secrets to version control

Weekly Installs

101

Repository

mindrally/skills

GitHub Stars

42

First Seen

Jan 25, 2026

Security Audits

Gen Agent Trust HubPassSocketPassSnykPass

Installed on

opencode82

gemini-cli80

codex75

cursor72

github-copilot71

claude-code69