Nest Server Updating

@lenne.tech/nest-server Update Knowledge Base

This skill provides knowledge and resources for updating @lenne.tech/nest-server. For automated execution, use the nest-server-updater agent via /lt-dev:backend:update-nest-server.

When This Skill Activates

• Discussing nest-server updates or upgrades
• Asking about breaking changes between versions
• Troubleshooting update-related errors
• Planning migration strategies
• Comparing versions or checking compatibility

Related Elements

Core Resources

GitHub Repositories

npm Package

# Package info
npm view @lenne.tech/nest-server

# Current installed version
npm list @lenne.tech/nest-server --depth=0

# All available versions
npm view @lenne.tech/nest-server versions --json

Migration Guide System

File Naming Convention

Migration guides in migration-guides/ follow these patterns:

Guide Selection Logic

For an update from version CURRENT to TARGET:

1. List available guides:

   gh api repos/lenneTech/nest-server/contents/migration-guides --jq '.[].name'
   

2. Select applicable guides:

   Condition	Guides to load
   Same major, sequential minor	Each X.Y.x-to-X.Z.x.md in sequence
   Major version jump	All minor guides + X.x-to-Y.x.md
   Spanning guide exists	Include it (may consolidate steps)

3. Load order (example 11.6.0 → 12.1.0):

   1. 11.6.x-to-11.7.x.md
   2. 11.7.x-to-11.8.x.md
   3. ... (all minor steps to 11.x latest)
   4. 11.x-to-12.x.md (major jump)
   5. 12.0.x-to-12.1.x.md
   6. 11.6.x-to-12.x.md (if exists - consolidated)
   

4. Fetch guide content:

   gh api repos/lenneTech/nest-server/contents/migration-guides/11.6.x-to-11.7.x.md \
     --jq '.content' | base64 -d
   

   Or via URL:

   https://raw.githubusercontent.com/lenneTech/nest-server/main/migration-guides/11.6.x-to-11.7.x.md
   

Fallback When No Guides Available

If migration-guides/ is empty or no matching guides exist for the version range:

Fallback Priority Order:

Fallback Commands:

# Get all releases between versions
gh release list --repo lenneTech/nest-server --limit 50

# View specific release details
gh release view v11.7.0 --repo lenneTech/nest-server

# Compare reference project between versions
cd /tmp/nest-server-starter-ref
git log --oneline v11.6.0..v11.8.0
git diff v11.6.0..v11.8.0 -- package.json src/

When using fallback:

• Proceed with extra caution
• Validate more frequently (after each minor change)
• Document assumptions in the update report
• Recommend manual review before merging

Version Update Strategies

IMPORTANT: In @lenne.tech/nest-server, Major versions are reserved for NestJS Major versions. Therefore, Minor versions are treated like Major versions and may contain breaking changes.

Patch Updates (X.Y.Z → X.Y.W)

• Usually safe, no breaking changes
• Use the standard update workflow (see Quick Reference → Update Workflow)
• Run tests to verify
• Example: 11.6.0 → 11.6.5 - direct update OK

Minor Updates (X.Y.Z → X.W.0) ⚠️ Treat as Major!

• May contain breaking changes (Minor = Major in this package)
• Always stepwise: Update through each minor version
• Each minor step requires full validation cycle
• Migration guides are essential
• Example: 11.6.0 → 11.8.0 becomes 11.6 → 11.7 → 11.8

Major Updates (X.Y.Z → W.0.0)

• Reserved for NestJS major version changes
• Always stepwise: Update through each major AND minor version
• Example: 11.6.0 → 12.2.0 becomes:
  1. 11.6 → 11.7 → ... → 11.latest (all minors)
  2. 11.latest → 12.0 (major jump)
  3. 12.0 → 12.1 → 12.2 (all minors)
• Migration guides are critical

Common Error Patterns & Solutions

TypeScript Errors

Runtime Errors

Test Failures

Reference Project Usage

The nest-server-starter serves as the source of truth:

What to Check

1. package.json

   • Compatible dependency versions
   • New/removed dependencies
   • Script changes

2. src/config.env.ts

   • New configuration options
   • Changed defaults

3. src/server/modules/

   • Updated patterns for modules/services
   • New decorators or utilities

4. Git history

   git log --oneline --all --grep="nest-server" | head -20
   

   • Find commits related to version updates
   • See exactly what changed

Update Modes

The nest-server-updater agent supports these modes:

Quick Reference

Commands

# Check current version
npm list @lenne.tech/nest-server --depth=0

# Check latest version
npm view @lenne.tech/nest-server version

# List migration guides
gh api repos/lenneTech/nest-server/contents/migration-guides --jq '.[].name'

Update Workflow

IMPORTANT: The npm run update script requires a specific workflow:

1. First: Update the version in package.json to the desired target version

   "@lenne.tech/nest-server": "^X.Y.Z"
   

2. Then: Run the update script

   npm run update
   

What npm run update does:

• Verifies the specified version is available on npm
• Installs @lenne.tech/nest-server at the version from package.json
• Analyzes which packages inside @lenne.tech/nest-server were updated
• Installs those updated dependencies if they don't exist or have a lower version
• Ensures version consistency between nest-server and its peer dependencies

Manual update (only if npm run update script is not available):

npm install @lenne.tech/nest-server@X.Y.Z --save-exact
npm install

Note: This skips the automatic dependency synchronization that npm run update provides.

Package Optimization (after npm run update)

After npm run update completes, run comprehensive package maintenance:

# Via command (recommended)
/lt-dev:maintenance:maintain

# Or via agent (Task tool with npm-package-maintainer in FULL MODE)

This ensures:

• Unused dependencies are removed
• Packages are correctly categorized (dependencies vs devDependencies)
• All packages are updated to their latest compatible versions
• Security vulnerabilities are addressed

Validation Sequence

npm run build    # Must pass
npm run lint     # Must pass
npm test         # Must pass (no skips)
npm audit        # Should show no new vulnerabilities

When to Use the Agent vs. Manual Update