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.
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.
| name | upgrade-unchained |
|---|---|
| description | 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. |
Upgrade Unchained Engine
Instructions
- Enter planning mode to create an upgrade plan
- Get available versions with
npm view @unchainedshop/platform versions --json - Show the user which versions they can upgrade to
- 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
- Migration guide:
- 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
- Documentation: https://docs.unchained.shop