@vc-shell/framework 1.1.4 → 1.1.5

package/CHANGELOG.md

@@ -1,3 +1,13 @@
+## [1.1.5](https://github.com/VirtoCommerce/vc-shell/compare/v1.1.4...v1.1.5) (2025-05-07)
+
+
+### Features
+
+* enhance VcIcon component ([58ad2ba](https://github.com/VirtoCommerce/vc-shell/commit/58ad2baaf306caa92375e81b170fdfb198a75b20))
+* implement module versioning and compatibility checks in the modularity plugin ([19c9553](https://github.com/VirtoCommerce/vc-shell/commit/19c95534c4ca0f6041015a0489dab7eabc1a322a))
+
+
+
 ## [1.1.4](https://github.com/VirtoCommerce/vc-shell/compare/v1.1.3...v1.1.4) (2025-04-30)
 
 

package/core/directives/loading/styles.css

@@ -48,7 +48,7 @@
   display: inline-block;
 }
 
-/* Размеры спиннера */
+/* Spinner sizes */
 .v-loading[data-loading-size="small"]::after {
   --v-loading-spinner-size: var(--v-loading-spinner-size-small);
   border-width: 2px;

package/core/plugins/modularity/README.md

@@ -1,9 +1,9 @@
-
 # Modularity Plugin
 
-The Modularity Plugin provides two main features:
+The Modularity Plugin provides three main features:
 - Dynamic Module Loading
 - Extensions System
+- Module Versioning and Compatibility
 
 ## Dynamic Module Loading
 
@@ -11,23 +11,29 @@ The Dynamic Module Loading system allows you to load Vue.js modules at runtime.
 
 ### Usage
 
-
 ```typescript
 import { useDynamicModules } from '@framework/core/plugins/modularity';
 import { createApp } from 'vue';
 import { createRouter } from 'vue-router';
 const app = createApp(App);
-const router = createRouter(/ router config /);
-const { load, extensionsHelper } = useDynamicModules(app, {
+const router = createRouter(/* router config */);
+const { load, extensionsHelper, getLoadedModulesWithVersions } = useDynamicModules(app, {
     router,
     appName: 'your-app-name'
   }, 
   {
     baseUrl: 'https://your-modules-host.com/',
     manifestFileName: 'manifest.json', // optional, default: 'manifest.json'
+    frameworkVersion: '1.2.3', // current framework version
+    appVersion: '2.0.0', // current application version
+    skipVersionCheck: process.env.NODE_ENV === 'development', // optional, skip version check in dev mode
   });
 // Load all modules
 await load();
+
+// Get information about loaded modules with their versions
+const loadedModules = getLoadedModulesWithVersions();
+console.log(`Loaded modules: ${loadedModules.size}`);
 ```
 
 ### Module Structure
@@ -36,17 +42,26 @@ Each module should have:
 1. A manifest file (manifest.json) describing module files generated by `Vite` during build time
 2. An entry point file that exports a Vue plugin
 3. Optional CSS files
+4. Optional version.json file with versioning information
 
 Example manifest.json:
 
 ```json
 {
-  "entry": {
-  "file": "index.js",
+  "src/modules/index.ts": {
+    "file": "index.js",
+    "name": "index",
+    "src": "src/modules/index.ts",
     "isEntry": true
   },
-  "styles": {
-    "file": "styles.css"
+  "style.css": {
+    "file": "style.css",
+    "src": "style.css"
+  },
+  "version.json": {
+    "file": "version.json",
+    "src": "version.json",
+    "isVersionInfo": true
   }
 }
 ```
@@ -56,14 +71,324 @@ Example module:
 ```typescript
 export default {
   install(app, options) {
-  // Plugin installation code
+    // Plugin installation code
   },
   extensions: {
-  // Optional extensions configuration
+    // Optional extensions configuration
+  },
+  version: {
+    version: '1.0.0',
+    compatibleWith: {
+      framework: '^1.2.0', // Compatible with framework version 1.2.x
+      modules: {
+        'dependency-module': '>=2.0.0' // Requires dependency-module version 2.0.0 or higher
+      }
+    },
+    appCompatibility: {
+      'vendor-portal': '>=2.0.0', // Compatible with vendor-portal app version 2.0.0 or higher
+      'admin-app': '^1.0.0'       // Compatible with admin-app version 1.x.x
+    }
+  }
+}
+```
+
+## Module Versioning System
+
+The Module Versioning System ensures compatibility between:
+- Modules and the framework
+- Modules and specific applications
+- Modules and other modules
+
+### Version Information Structure
+
+```typescript
+interface VersionInfo {
+  version: string;
+  compatibleWith: {
+    framework: string; // Framework version range (semver)
+    modules?: Record<string, string>; // Dependencies on other modules
+  };
+  appCompatibility?: {
+    [appName: string]: string; // Compatible application names and version ranges
+  }
+}
+```
+
+### Setting Up Module Versioning
+
+There are three ways to specify version information:
+
+1. **In the module's code** (highest priority):
+
+```typescript
+export default {
+  install(app, options) { /* ... */ },
+  version: {
+    version: '1.0.0',
+    compatibleWith: {
+      framework: '^1.2.0'
+    },
+    appCompatibility: {
+      'vendor-portal': '>=2.0.0',
+      'admin-app': '^1.0.0'
+    }
+  }
+}
+```
+
+2. **Using a version.json file** (medium priority):
+
+```json
+{
+  "version": "1.0.0",
+  "compatibleWith": {
+    "framework": "^1.2.0",
+    "modules": {
+      "other-module": ">=1.0.0"
+    }
+  },
+  "appCompatibility": {
+    "vendor-portal": ">=2.0.0"
+  }
+}
+```
+
+3. **In the apps.json file** (lowest priority):
+
+```json
+[
+  {
+    "vendor-portal": {
+      "modules": [
+        {
+          "id": "my-module",
+          "url": "/modules/my-module/",
+          "version": "1.0.0"
+        }
+      ]
+    }
   }
+]
+```
+
+### Version Patterns
+
+The versioning system uses [semver](https://semver.org/) syntax for version ranges:
+
+- `*` - Compatible with any version
+- `1.2.3` - Requires exact version 1.2.3
+- `^1.2.3` - Compatible with 1.2.3 up to but not including 2.0.0
+- `~1.2.3` - Compatible with 1.2.3 up to but not including 1.3.0
+- `>=1.2.3` - Version 1.2.3 or higher
+- `1.2.3 - 1.5.0` - Range between 1.2.3 and 1.5.0 (inclusive)
+
+### Application Compatibility
+
+To specify which applications your module is compatible with:
+
+```typescript
+appCompatibility: {
+  // Compatible with any version of vendor-portal
+  'vendor-portal': '*',
+  
+  // Compatible with admin-app version 2.0.0 and above
+  'admin-app': '>=2.0.0',
+  
+  // Compatible with any application (if appCompatibility is omitted entirely,
+  // the module is also considered compatible with any application)
+  '*': '*'
 }
 ```
 
+If an application name is not listed in `appCompatibility`, the module will not be loaded in that application.
+
+### Setting Up Vite Config for Module Versioning
+
+Here's a complete example of a Vite configuration that supports the versioning system:
+
+```javascript
+import { defineConfig } from "vite";
+import { resolve, join, dirname } from "node:path";
+import vue from "@vitejs/plugin-vue";
+import { fileURLToPath } from "node:url";
+import fs from "node:fs";
+import pkg from "./package.json";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// Get dependency versions from package.json
+const { version, dependencies = {}, peerDependencies = {} } = pkg;
+
+// Function to read framework version from dependencies
+const getFrameworkVersion = () => {
+  const frameworkDep = dependencies["@vc-shell/framework"] || 
+                      peerDependencies["@vc-shell/framework"] || 
+                      "^1.0.0";
+  return frameworkDep.replace(/^\^|~/, ""); // Remove ^ or ~ prefixes
+};
+
+export default defineConfig({
+  build: {
+    manifest: "manifest.json",
+    copyPublicDir: false,
+    sourcemap: true,
+    minify: false,
+    lib: {
+      entry: resolve(__dirname, "./index.ts"),
+      fileName: (format, name) => `${name}.js`,
+      formats: ["umd"],
+      name: "VcShellDynamicModules",
+    },
+    outDir: join(__dirname, "../../dist/packages/modules"),
+    rollupOptions: {
+      output: {
+        globals: {
+          vue: "Vue",
+          "vue-router": "VueRouter",
+          "vee-validate": "VeeValidate",
+          "vue-i18n": "VueI18n",
+          moment: "moment",
+          "lodash-es": "_",
+          "@vueuse/core": "VueUse",
+          "@vc-shell/framework": "VcShellFramework",
+        },
+        banner: () => {
+          const versionInfo = {
+            version,
+            compatibleWith: {
+              framework: peerDependencies["@vc-shell/framework"] || "^" + getFrameworkVersion(),
+              modules: {}
+            },
+            appCompatibility: {
+              "vendor-portal": ">=2.0.0",
+              "admin-app": "^1.0.0"
+            }
+          };
+          
+          return `
+            /* Module Version Info */
+            (function() {
+              if (typeof window !== 'undefined') {
+                window.__VC_SHELL_MODULE_VERSION_INFO__ = window.__VC_SHELL_MODULE_VERSION_INFO__ || {};
+                window.__VC_SHELL_MODULE_VERSION_INFO__["${pkg.name}"] = ${JSON.stringify(versionInfo)};
+              }
+            })();
+          `;
+        }
+      },
+      external: [
+        /node_modules/,
+        "@vc-shell/framework",
+        "vue",
+        "vue-router",
+        "vee-validate",
+        "vue-i18n",
+        "moment",
+        "lodash-es",
+        "@vueuse/core",
+      ],
+    },
+  },
+  plugins: [
+    vue(),
+    {
+      name: 'module-version-plugin',
+      apply: 'build',
+      enforce: 'post',
+      
+      // Modify manifest.json after it's created
+      closeBundle: async () => {
+        const manifestPath = join(__dirname, "../../dist/packages/modules/manifest.json");
+        
+        if (fs.existsSync(manifestPath)) {
+          try {
+            // Read generated manifest
+            const manifestContent = await fs.promises.readFile(manifestPath, 'utf-8');
+            const manifest = JSON.parse(manifestContent);
+            
+            // Add version metadata file
+            const versionFileName = 'version.json';
+            const versionFilePath = join(__dirname, "../../dist/packages/modules/", versionFileName);
+            
+            // Create version info
+            const versionInfo = {
+              version: pkg.version,
+              compatibleWith: {
+                framework: peerDependencies["@vc-shell/framework"] || "^" + getFrameworkVersion(),
+                modules: {}
+              },
+              appCompatibility: {
+                "vendor-portal": ">=2.0.0",
+                "admin-app": "^1.0.0"
+              }
+            };
+            
+            // Write version file
+            await fs.promises.writeFile(versionFilePath, JSON.stringify(versionInfo, null, 2));
+            
+            // Add version file info to manifest
+            manifest[versionFileName] = {
+              file: versionFileName,
+              src: versionFileName,
+              isVersionInfo: true // Special marker
+            };
+            
+            // Write updated manifest
+            await fs.promises.writeFile(manifestPath, JSON.stringify(manifest, null, 2));
+            
+            console.log(`✓ Version information added to manifest: ${manifestPath}`);
+          } catch (error) {
+            console.error('Error updating manifest with version info:', error);
+          }
+        } else {
+          console.warn(`Manifest file not found at ${manifestPath}`);
+        }
+      }
+    }
+  ],
+});
+```
+
+### Accessing Version Information in the Module
+
+In your module code, you can access the version information:
+
+```typescript
+// In your module's index.ts
+import pkg from './package.json';
+
+export default {
+  install(app, options) {
+    // Your module code
+  },
+  // Access version info from window global if available (set by banner in vite config),
+  // or fall back to static configuration
+  version: window.__VC_SHELL_MODULE_VERSION_INFO__?.[pkg.name] || {
+    version: pkg.version,
+    compatibleWith: {
+      framework: "^1.0.0"
+    },
+    appCompatibility: {
+      "vendor-portal": ">=2.0.0"
+    }
+  }
+};
+```
+
+### Error Handling
+
+When a module fails the compatibility check, it won't be loaded, and an error message will be logged to the console:
+
+```
+Version compatibility error: Module my-module requires framework version ^2.0.0, but current is 1.2.3
+```
+
+or
+
+```
+Module my-module is not compatible with application customer-app. This module supports only: vendor-portal, admin-app
+```
+
 ## Extensions System
 
 The Extensions System enables communication between the application and its modules.
@@ -79,7 +404,7 @@ The Extensions System enables communication between the application and its modu
 // In your module
 export default {
   install(app) {
-  // Plugin installation code
+    // Plugin installation code
   },
   extensions: {
     inbound: {
@@ -145,8 +470,13 @@ type Extension = Record<string, unknown>;
 
 ## Best Practices
 
-1. Always provide unique IDs for extensions
-2. Document your module's extension points
-3. Handle missing or failed extensions gracefully
-4. Use TypeScript interfaces for type safety
-5. Keep extension configurations simple and serializable
+1. Always provide version information for your modules.
+2. Use semantic versioning for your module versions.
+3. Be explicit about framework compatibility requirements.
+4. Specify application compatibility if your module is designed for specific applications.
+5. Handle missing extensions gracefully.
+6. Test your modules with different versions of the framework and applications.
+7. Consider using the `skipVersionCheck` option in development for easier testing.
+8. Document your module's version compatibility requirements.
+9. Keep version.json and manifest.json files up to date when deploying modules.
+10. Use the error messages to troubleshoot version compatibility issues.