This document indexes all the migration work needed to upgrade an application from @vc-shell/framework v1.2.3 (or any v1.x) to v2.0.0. Each guide is self-contained — work through them in phase order.
- Backward compatibility: Many deprecated APIs still work via adapter layers. You can migrate incrementally — one module at a time.
- Runtime warnings: In development mode, deprecated APIs log console warnings with links to migration docs.
- Automated migration: Where available, codemods are provided via
npx @vc-shell/migrate. Runnpx @vc-shell/migrate --listto see all available transforms. - Comprehensive audit: See docs/migration-2.0.0/audit-report.md for a full change catalog.
- Phase 1 — Project setup (blocks build): dependencies, icons, styles, type shims
- Phase 2 — Architecture (if used): modules, blades, widgets, notifications, extensions
- Phase 3 — UI components (if used): login, app bar, dashboard, generic table
- Phase 4 — Tooling: Vue 3.5, Router 5, vue-tsc 3, injection keys, platform URL
- Phase 5 — API cleanup & new patterns: deprecated APIs, optional new composables
| # | Guide | Severity | Description |
|---|---|---|---|
| 01 | package.json | Required | Update deps, peerDeps, remove obsolete packages, wildcard exports removed |
| 03 | moment.js → date-fns | Required | Replace moment.js with date-fns utilities |
| 04 | Window Globals Removed | Required | window.Vue, window.moment, etc. no longer set |
| 05 | Icon Migration | Required | Font Awesome → Lucide / Material Symbols / Bootstrap Icons |
| 06 | Styles & SCSS | Required | @import → @use, dark theme, scrollbar tokens, Tailwind color mapping, z-index scale |
| 07 | shims-vue.d.ts | Required | Update TypeScript declarations for Vue 3.5 + vue-i18n |
| # | Guide | Severity | Description |
|---|---|---|---|
| 08 | Dynamic Views Removal | Breaking | createDynamicAppModule and JSON schemas removed |
| 09 | defineAppModule | Deprecated | createAppModule() → defineAppModule() |
| 10 | useBlade | Deprecated | useBladeNavigation() → useBlade() |
| 11 | Blade Props Simplification | Deprecated | Remove boilerplate props/emits from blade pages |
| 12 | replaceWith / coverWith | Changed | replaceWith behavior changed; new coverWith method |
| 13 | Widgets | Deprecated | registerWidget() → useBladeWidgets() |
| 14 | Notifications | Deprecated | useNotifications() → useBladeNotifications() |
| 15 | Extension Points | Breaking | useExtensionSlot → defineExtensionPoint |
| 43 | getModulesLibraryConfiguration | Breaking | getDynamicModuleConfiguration → getModulesLibraryConfiguration (ES library) |
| 44 | createModule() Removal | Breaking | Lightweight createModule() helper removed — use defineAppModule() |
| 45 | useDynamicModules() Removal | Breaking | Custom CDN-based runtime module loader removed — use @vc-shell/mf-host/mf-module for runtime federation, or static imports |
| # | Guide | Severity | Description |
|---|---|---|---|
| 16 | VcLoginForm → VcAuthLayout | Breaking | VcLoginForm removed, replaced by VcAuthLayout |
| 17 | App Bar & Settings Menu | Deprecated | Slots → useAppBarWidget() / useSettingsMenu() |
| 18 | Dashboard | Breaking | Static grid → DraggableDashboard with widget registration |
| 19 | Generic Components | Optional | @vue-generic directive for type-safe VcTable |
| # | Guide | Severity | Description |
|---|---|---|---|
| 20 | Vue 3.5, Router 5, vue-tsc 3 | Required | Dependency upgrades and breaking changes |
| 21 | Injection Keys | Deprecated | Renamed Symbol keys with backward-compat string shims |
| 22 | platformUrl Removal | Breaking | Use APP_PLATFORM_URL env variable instead |
| # | Guide | Severity | Description |
|---|---|---|---|
| 23 | Composable Return Types | Deprecated | IUsePermissions → UsePermissionsReturn and 19 other type aliases |
| 24 | VcBanner Variants | Deprecated | "light-danger" → "danger", "info-dark"/"primary" → "info" |
| 25 | VcSwitch Tooltip | Deprecated | tooltip prop → hint / labelTooltip |
| 26 | VcIcon Container | Deprecated | useContainer prop deprecated (no-op) |
| 27 | Menu Group Config | Deprecated | group/groupIcon/inGroupPriority → groupConfig object |
| 28 | Shared Components | Deprecated | Shared VcSidebar/VcDropdown → UI component versions |
| 29 | VcTable → VcDataTable | Breaking | Old VcTable removed; VcTableAdapter provides backward compat |
| 30 | Type Shims → Globals | Deprecated | Manual shims-vue.d.ts / vue-i18n.d.ts → @vc-shell/framework/globals |
| 31 | useDataTableSort | Optional | Replace manual sort boilerplate with useDataTableSort composable |
| 32 | useAssets → useAssetsManager | Deprecated | useAssets() handler bundle → useAssetsManager() ref-mutating composable |
| 33 | Locale Exports | Breaking | dist/locales/*.json wildcard → named @vc-shell/framework/locales/<lang> exports |
| 34 | App Hub Rename | Breaking | disableAppSwitcher → disableAppHub, #app-switcher → #app-hub, useAppSwitcher → useAppHub |
| 35 | defineBlade | Deprecated | defineOptions() with blade fields → defineBlade() macro |
| 36 | useResponsive | Deprecated | $isMobile.value / inject(IsMobileKey) → useResponsive() composable |
| 37 | useBladeForm | Optional | Replace manual useForm + useModificationTracker + useBeforeUnload with useBladeForm |
| 38 | Dynamic Properties Refactor | Breaking | useDynamicProperties: remove generics/constructors, options-based API |
| 39 | Transparent Blade Skeletons | Informational | Layout-aware skeleton loading via useBladeLoading() composable |
| 40 | Remove Global Component Registration | Breaking | Explicit imports required for all Vc* components and directives (no more app.component() auto-registration) |
| 41 | useDataTablePagination | Optional | Replace manual totalCount/pages/currentPage + onPaginationClick with useDataTablePagination |
| 42 | Broadcast Filter | Breaking | updateSignalRCreator → useBroadcastFilter() composable |
| 46 | CSS BEM Class Migration | Breaking | Component modifier classes renamed from _modifier → --modifier (strict BEM) |
| 47 | VcButton Props | Breaking | small/outline/raised props removed; size="base"/"xs" aliases replaced by "default"/"sm" |
| 48 | Menu Icon Type Change | Breaking | MenuItemConfig.icon narrowed from string | Component to string only; ToolbarMenu<T> removed |
| 49 | Component Prop Removals | Breaking | VcContainer usePtr, VcStatus outline, VcEditor extensions, VcField modelValue removed/changed |
These minor changes are noted inline in the referenced guides but are listed here for quick scanning:
filesfield inpackage.jsonshrunk — source-directory deep imports via npm no longer work (see #01).- Script names changed:
type-check→check:types,check-locales→check:locales. - Loading animation keyframes (
tw-animate-loadingMarker) removed from Tailwind config. - Form molecules now share
IFormFieldPropsinterface — adopt for consistency. useWidgets()no longer re-exported from the main barrel — use per-module imports.useUser()gainsgetAccessToken()method (additive, no action required).addAppBarWidget/addSettingsMenuItemstandalone exports moved — use the composable-based API (see #17).
| Label | Meaning |
|---|---|
| Required | Must do before the app will build/run |
| Breaking | Feature removed — code using it will fail at runtime |
| Changed | Same API name but different behavior |
| Deprecated | Old API works via adapter with console warnings; migrate at your pace |
| Optional | New capability, no action needed unless you want the improvement |
| Informational | Background context only — no action required |
- WHATS_NEW.md — full feature overview for v2.0
- migration/README.md — detailed migration index (mirror of this document)
- docs/migration-2.0.0/audit-report.md — audit report with coverage analysis