Migrating from koa-router to @koa/router - Koa Router Middleware Migration Guide

Why Migrate?

As Koa and its ecosystem continue to evolve, koa-router, which was previously maintained by the open-source community, has stopped receiving updates, no longer providing security patches, feature updates, or TypeScript type optimizations. The official recommendation is to adopt @koa/router, which is maintained by the Koa core team and is the main force of the Koa ecosystem going forward.

Summary of Migration Reasons

• Active Maintenance: Continuous updates from the official team with higher security assurance
• Consistent API: Low-risk, seamless upgrade
• Enhanced TypeScript Support: Improved development efficiency and code quality
• Higher Performance: Optimized route lookup and faster path parameter parsing
• Mainstream Ecosystem: Compatible with the latest Koa and popular community tools

Benefits of Migration

Potential Risks and Considerations

• Package Name Change: All import paths need to be updated to @koa/router
• Type Compatibility: TypeScript projects need to remove the old @types/koa-router to avoid type conflicts
• Koa Version Requirements: Requires Koa v2+; Koa v1 projects need to upgrade the framework first
• Some private APIs or Monkey Patch scenarios may need adjustments
• Minor parameter naming differences in some low-level types or methods

Migration Steps

Step 1. Uninstall Old Dependencies

npm uninstall koa-router @types/koa-router
# or
yarn remove koa-router @types/koa-router

Step 2. Install New Package

npm install @koa/router
# or
yarn add @koa/router

Step 3. Global Replace import/require Paths

// Old way (needs replacement)
import Router from 'koa-router'

// New way
import Router from '@koa/router'

Step 4. Type Declaration Review and Cleanup

Remove custom type extensions related to koa-router and align with @koa/router's new type definitions as needed. If you've extended the router context, please enhance the types based on the new version's supported generic parameters.

// Example: Custom ctx.state type
import Router from '@koa/router'

interface ICustomState {
	userId: string
}

const router = new Router<{}, ICustomState>()

Step 5. Run Tests and Manual Verification

• Execute automated tests to ensure business functionality is not affected by the router upgrade
• If you have CI/CD, run regression tests before deployment

Step 6. Deep Cleanup

• Check package.json, global declarations, and scaffolding configuration to avoid leaving koa-router related configs

Common Migration Issues and Solutions

• Project fails to start after migration: Check if Koa version is >= 2.x and all dependencies are upgraded
• TypeScript compilation errors: Confirm @types/koa-router is uninstalled and align with new type definitions
• Route parameter type inference errors: Refer to new generic interface definitions and enhance context generics
• Custom hacks or private API dependencies: Check @koa/router documentation, rely on public APIs as much as possible, adjust code if necessary

Migration Summary

• Migrating to @koa/router is strongly recommended by the official community
• Comprehensive improvements in performance, security, and development experience with low compatibility risks
• Pay attention to TypeScript type compatibility and Koa version requirements
• New projects should use @koa/router directly; existing projects should migrate early to maintain a healthy technology stack