General Upgrade Guide

Overview

This guide provides general strategies and best practices for upgrading tsoa between major versions. For specific version migrations, see the dedicated migration guides.

Upgrade Strategy

Pre-Upgrade Checklist

Before upgrading tsoa, ensure you have:

Review release notes

Always read the release notes for the target version:

Breaking changes
New features
Deprecated features
Known issues

Find release notes at: github.com/lukeautry/tsoa/releases

Check Node.js compatibility

Verify your Node.js version meets the requirements:

tsoa Version	Minimum Node.js
v7.x	18.0.0
v6.x	18.0.0
v5.x	14.0.0
v4.x	12.0.0

Check your Node.js version:

node --version

Verify TypeScript version

Ensure your TypeScript version is compatible:

tsoa Version	Minimum TypeScript
v7.x	5.2.2
v6.x	5.3.3
v5.x	4.9.5
v4.x	4.x

npx tsc --version

Create a backup

Always work in a version-controlled environment:

git checkout -b upgrade-tsoa-v7
git add .
git commit -m "Pre-upgrade checkpoint"

Document current configuration

Save your current tsoa.json configuration for reference:

cp tsoa.json tsoa.json.backup

Upgrade Process

Update package.json

Update tsoa and related dependencies:

package.json

{
  "dependencies": {
    "tsoa": "^7.0.0",
    "express": "^4.21.2",
    "reflect-metadata": "^0.2.2"
  },
  "devDependencies": {
    "@types/node": "^18.0.0",
    "@types/express": "^4.17.21",
    "typescript": "^5.7.2"
  }
}

Install dependencies

# Clear any cached packages
rm -rf node_modules package-lock.json
# or for Yarn:
rm -rf node_modules yarn.lock

# Install fresh dependencies
npm install
# or
yarn install

Update TypeScript configuration

Review and update your tsconfig.json if needed:

tsconfig.json

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "Node16",
    "moduleResolution": "Node16",
    "lib": ["ES2022"],
    "esModuleInterop": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "skipLibCheck": true,
    "strict": true
  }
}

Clean generated files

Remove old generated files:

# Remove generated routes
rm -rf src/routes.ts
# or your configured routes directory

# Remove generated spec
rm -rf build/swagger.json
# or your configured spec directory

Regenerate code

Generate new routes and specifications:

npx tsoa spec-and-routes

Or run them separately:

npx tsoa spec
npx tsoa routes

Fix compilation errors

Address any TypeScript compilation errors:

npx tsc --noEmit

Common issues:

Decorator imports may have changed
Type definitions may have been refined
Configuration options may have been renamed

Run tests

Execute your test suite:

npm test

Focus on:

Controller tests
Validation tests
Integration tests
OpenAPI spec validation

Testing Your Upgrade

Automated Testing

Create tests to verify the upgrade:

test/upgrade.spec.ts

import { expect } from 'chai';
import * as fs from 'fs';
import * as path from 'path';

describe('tsoa Upgrade Tests', () => {
  it('should generate valid OpenAPI spec', () => {
    const specPath = path.join(__dirname, '../build/swagger.json');
    expect(fs.existsSync(specPath)).to.be.true;

    const spec = JSON.parse(fs.readFileSync(specPath, 'utf-8'));
    expect(spec.openapi || spec.swagger).to.exist;
  });

  it('should generate routes file', () => {
    const routesPath = path.join(__dirname, '../src/routes.ts');
    expect(fs.existsSync(routesPath)).to.be.true;
  });

  it('should have valid route registrations', () => {
    const { RegisterRoutes } = require('../src/routes');
    expect(RegisterRoutes).to.be.a('function');
  });
});

Manual Testing

Test API endpoints

Test all your endpoints manually:

# Start your server
npm start

# Test a sample endpoint
curl http://localhost:3000/api/users

# Test with validation
curl -X POST http://localhost:3000/api/users \
  -H "Content-Type: application/json" \
  -d '{"name":"John","email":"[email protected]"}'

Validate OpenAPI spec

Use online validators to check your spec:

# Install validator
npm install -g openapi-validator-cli

# Validate your spec
openapi-validator-cli build/swagger.json

Or use online tools:

Test authentication

Verify security configurations:

# Test with auth header
curl http://localhost:3000/api/protected \
  -H "Authorization: Bearer YOUR_TOKEN"

# Test without auth (should fail)
curl http://localhost:3000/api/protected

Test file uploads

If using file uploads:

curl -X POST http://localhost:3000/api/upload \
  -F "file=@/path/to/file.pdf" \
  -F "description=Test upload"

Common Issues

Import Errors

Problem: Decorators or types cannot be imported

Error

import { Controller, Route } from 'tsoa';
// Error: Module not found

Solution: Ensure decorators are imported correctly

Fixed

import { Controller, Route, Get, Post } from 'tsoa';
// All decorators should be available from 'tsoa'

Configuration Changes

Problem: Configuration file not recognized Solution: Check for deprecated configuration options:

{
  "spec": {
    "swagger": "2.0"
  }
}

Validation Errors

Problem: Runtime validation behaves differently Solution: Review validation decorators:

import { IsInt, IsString, MinLength } from 'class-validator';

interface CreateUserRequest {
  @IsString()
  @MinLength(3)
  name: string;

  @IsInt()
  age: number;
}

Ensure all validation rules are explicitly defined.

Generated Code Issues

Problem: Generated routes have syntax errors Solution:

Delete generated files
Clear tsoa cache: rm -rf node_modules/.tsoa
Regenerate: npx tsoa spec-and-routes

OpenAPI Spec Validation

Problem: Generated spec is invalid Solution: Use additionalProperties correctly:

interface StrictModel {
  name: string;
  age: number;
  // No additional properties allowed
}

interface FlexibleModel {
  name: string;
  [key: string]: unknown; // Additional properties allowed
}

Version-Specific Guides

For detailed migration instructions:

v6 to v7 Migration

OpenAPI 3.1.0 support and validation improvements

v5 to v6 Migration

Node.js 18 requirement and TypeScript 5 support

Major Version Changes Summary

tsoa v7 (2025)

OpenAPI 3.1.0 support
Enhanced circular reference handling
Zod infer type support
TypeScript 5.7+ support
Improved generic type resolution

tsoa v6 (2023)

Node.js 18+ required
TypeScript 5+ support
ESM improvements (.mts, .cts support)
OpenID Connect security
Enhanced validation for intersections and unions

tsoa v5 (2022)

Improved metadata generation
Better type inference
Enhanced route generation

Rollback Procedure

If the upgrade fails:

Revert package.json

git checkout package.json

Reinstall old dependencies

rm -rf node_modules package-lock.json
npm install

Restore configuration

git checkout tsoa.json

Regenerate with old version

npx tsoa spec-and-routes

Verify application works

npm test
npm start

Best Practices

1. Incremental Upgrades

Don’t skip major versions. Upgrade incrementally:

v4 → v5 → v6 → v7

This makes it easier to identify and fix breaking changes.

2. Use Lock Files

Always commit your package-lock.json or yarn.lock:

git add package-lock.json
git commit -m "Lock dependencies for tsoa upgrade"

3. Test in Staging

Never upgrade directly in production:

Test in local development
Deploy to staging environment
Run full test suite
Deploy to production

4. Monitor After Upgrade

Watch for issues after upgrading:

Response times
Error rates
Validation failures
OpenAPI spec compatibility

5. Document Changes

Keep a migration log:

MIGRATION_LOG.md

# tsoa Upgrade Log

## v6 to v7 (2025-03-06)

- Updated from 6.6.1 to 7.0.0-alpha.0
- Changed specVersion to 3.1 for OpenAPI 3.1.0
- Fixed circular reference issues in User model
- Updated validation tests

### Issues Encountered
- Fixed: Generic type resolution in SearchQuery
- Fixed: Updated multer options to RegisterRoutes

Getting Help

GitHub Issues

Report bugs or search existing issues

Discussions

Ask questions and share experiences

Configuration Reference

Review configuration options

API Reference

Explore decorator and API documentation

Next Steps

After successfully upgrading:

Update documentation: Refresh your API documentation with the new OpenAPI spec
Notify consumers: Inform API consumers of any changes
Monitor logs: Watch for unexpected behavior
Update CI/CD: Ensure deployment pipelines work with the new version
Review new features: Explore new capabilities introduced in the upgrade

Getting Started

Core Concepts

CLI & Configuration

Guides

Advanced

Migration

​Overview

​Upgrade Strategy

​Pre-Upgrade Checklist

​Upgrade Process

​Testing Your Upgrade

​Automated Testing

​Manual Testing

​Common Issues

​Import Errors

​Configuration Changes

​Validation Errors

​Generated Code Issues

​OpenAPI Spec Validation

​Version-Specific Guides