upgrade-unchained

Guides upgrading Unchained Engine to a new major version. Use when the user wants to upgrade their Unchained project, mentions updating @unchainedshop packages, or asks about migration.

⭐184stars🔀20forks📁View on GitHub🕐Updated Dec 30, 2025

When & Why to Use This Skill

The Upgrade Unchained skill is a specialized assistant designed to automate and guide the complex process of migrating Unchained Engine projects to new major versions. It streamlines the developer workflow by automatically identifying compatible versions, fetching official migration guides and changelogs, and executing technical upgrade tasks. By handling dependency management and post-upgrade verification, it ensures a stable and efficient transition for @unchainedshop ecosystems.

Use Cases

  • Major Version Migration: Automatically generate a step-by-step upgrade plan for Unchained Engine, including fetching specific MIGRATION.md and CHANGELOG.md files for the target version.
  • Dependency Management & Cleanup: Update @unchainedshop npm packages to their latest compatible versions and automatically identify and remove deprecated dependencies.
  • Framework Pattern Alignment: Compare and update project boot files (Express, Fastify, OIDC) by referencing official 'kitchensink' examples to ensure compliance with new architectural patterns.
  • Automated Quality Assurance: Execute post-upgrade validation suites, including linting, unit testing, and build verification, to detect breaking changes immediately after the migration.
nameupgrade-unchained
descriptionGuides upgrading Unchained Engine to a new major version. Use when the user wants to upgrade their Unchained project, mentions updating @unchainedshop packages, or asks about migration.

Upgrade Unchained Engine

Instructions

  1. Enter planning mode to create an upgrade plan
  2. Get available versions with npm view @unchainedshop/platform versions --json
  3. Show the user which versions they can upgrade to
  4. Once a target version is selected (e.g., 4.5.0), fetch these resources:
    • Migration guide: https://raw.githubusercontent.com/unchainedshop/unchained/refs/tags/v{version}/MIGRATION.md
    • Changelog: https://raw.githubusercontent.com/unchainedshop/unchained/refs/tags/v{version}/CHANGELOG.md
    • README: https://raw.githubusercontent.com/unchainedshop/unchained/refs/heads/master/README.md
  5. Execute the upgrade by:
    • Updating npm dependencies
    • Removing deprecated dependencies
    • Running lint, tests, and build
    • Starting the project to verify

Reference Examples

Fetch example boot files for the target version to understand current patterns:

Framework Example URL
Express https://raw.githubusercontent.com/unchainedshop/unchained/refs/tags/v{version}/examples/kitchensink-express/src/boot.ts
Fastify https://raw.githubusercontent.com/unchainedshop/unchained/refs/tags/v{version}/examples/kitchensink/src/boot.ts
Minimal https://raw.githubusercontent.com/unchainedshop/unchained/refs/tags/v{version}/examples/minimal/src/boot.ts
Ticketing https://raw.githubusercontent.com/unchainedshop/unchained/refs/tags/v{version}/examples/ticketing/src/boot.ts
OIDC https://raw.githubusercontent.com/unchainedshop/unchained/refs/tags/v{version}/examples/oidc/src/boot.ts

Additional Resources