@libs-for-dev/vue-modular-application 0.0.1

package/README.md

@@ -0,0 +1,410 @@
+# Vue Modular Application
+
+A library for creating modular Vue.js applications with support for automatic registration of modules, plugins, widgets, and routes.
+
+## Overview
+
+`@libs-for-dev/vue-modular-application` provides an architecture for building scalable Vue.js applications based on a modular system. The library allows you to:
+
+- Automatically register client modules
+- Manage Vue plugins and widgets
+- Integrate Inversify containers for dependency injection
+- Combine routes and navigation from different modules
+- Support SSR (Server-Side Rendering)
+- Ensure complete module isolation
+
+## Installation
+
+```bash
+npm install @libs-for-dev/vue-modular-application
+# or
+yarn add @libs-for-dev/vue-modular-application
+```
+
+### Peer Dependencies
+
+The library requires the following dependencies:
+
+```bash
+npm install vue@^3.0.0 vue-router@^4.0.0
+```
+
+For dependency injection usage (optional):
+
+```bash
+npm install inversify@^6.0.0 reflect-metadata@^0.2.0
+```
+
+## Quick Start
+
+### 1. Creating a Client Module
+
+```typescript
+import type {
+  ClientModuleInterface,
+  ContainerPluginInterface,
+  VuePluginInterface,
+  VueWidgetsInterface
+} from '@libs-for-dev/vue-modular-application'
+import type { RouteRecordRaw } from 'vue-router'
+import { Container } from 'inversify'
+
+export class UserModule implements ClientModuleInterface<NavigationItem[], RouteRecordRaw[], Container> {
+  readonly name = 'user-module'
+
+  getRoutes(): RouteRecordRaw[] {
+    return [
+      {
+        path: '/users',
+        name: 'Users',
+        component: () => import('./components/UsersPage.vue')
+      }
+    ]
+  }
+
+  getNavigation(): NavigationItem[] {
+    return [
+      {
+        label: 'Users',
+        path: '/users',
+        icon: 'users'
+      }
+    ]
+  }
+
+  getPlugins(): VuePluginInterface[] {
+    return [
+      {
+        install(app) {
+          app.config.globalProperties.$userService = new UserService()
+        }
+      }
+    ]
+  }
+
+  getContainer(): ContainerPluginInterface<Container>[] {
+    const container = new Container()
+
+    return [
+      {
+        container,
+        install() {
+          container.bind('UserService').to(UserService).inSingletonScope()
+        }
+      }
+    ]
+  }
+
+  getWidgets(): VueWidgetsInterface[] {
+    return [
+      {
+        namespace: 'user',
+        widgets: {
+          UserCard: () => import('./widgets/UserCard.vue'),
+          UserStats: () => import('./widgets/UserStats.vue')
+        },
+        install() {
+          // Additional widget installation logic
+        }
+      }
+    ]
+  }
+}
+```
+
+### 2. Module Registration
+
+```typescript
+import { ModuleLoader } from '@libs-for-dev/vue-modular-application'
+import { UserModule } from './modules/UserModule'
+
+// Register module
+ModuleLoader.registerModuleProvider(new UserModule())
+```
+
+### 3. Application Creation
+
+```typescript
+import { createApp } from 'vue'
+import { createWebHistory } from 'vue-router'
+import { VueApplication, ModuleLoader } from '@libs-for-dev/vue-modular-application'
+
+// Get modules registry
+const moduleRegistry = ModuleLoader.getModulesRegistry()
+
+// Create application instance
+const appInstance = new VueApplication(
+  createApp,
+  createWebHistory(),
+  moduleRegistry
+)
+
+// Build application
+const app = appInstance.build(App)
+
+// Mount
+app.mount('#app')
+```
+
+## API Reference
+
+### VueApplication
+
+Main class for creating Vue applications with modular architecture.
+
+```typescript
+class VueApplication<Navigation, Routes, Container> {
+  constructor(
+    createApp: CreateAppFunction<Element>,
+    routerHistory: RouterHistory,
+    moduleRegistry: ModuleRegistry<Navigation, Routes, Container>
+  )
+
+  build(element: DefineComponent): App<Element>
+}
+```
+
+### ModuleLoader
+
+Static class for managing module registration.
+
+```typescript
+class ModuleLoader {
+  static registerModuleProvider(module: ClientModuleInterface<unknown, unknown>): void
+  static getModulesRegistry(): ModuleRegistry<unknown, unknown, unknown>
+}
+```
+
+### ModuleRegistry
+
+Module registry providing access to registered modules and their resources.
+
+```typescript
+class ModuleRegistry<Navigation, Routes, Container> {
+  constructor(clientModules: ClientModuleInterface<Navigation, Routes, Container>[])
+
+  getAllRoutes(): Routes[]
+  getModules(): ClientModuleInterface<Navigation, Routes, Container>[]
+  getNavigation(): Ref<UnwrapRef<Navigation[]>>
+  getWidget(namespace: string, widgetName: string): unknown
+}
+```
+
+## Interfaces
+
+### ClientModuleInterface
+
+Base interface for all client modules.
+
+```typescript
+interface ClientModuleInterface<Navigation, Routes, Container = unknown> {
+  readonly name: string
+
+  getRoutes(): Routes
+  getNavigation(): Navigation
+  getPlugins(): VuePluginInterface[]
+  getContainer(): ContainerPluginInterface<Container>[]
+  getWidgets(): VueWidgetsInterface[]
+}
+```
+
+### VuePluginInterface
+
+Interface for Vue plugins.
+
+```typescript
+interface VuePluginInterface {
+  install(app: App): void
+}
+```
+
+### ContainerPluginInterface
+
+Interface for plugins with Inversify container.
+
+```typescript
+interface ContainerPluginInterface<Container> extends VuePluginInterface {
+  container: Container
+}
+```
+
+### VueWidgetsInterface
+
+Interface for widgets with extended functionality.
+
+```typescript
+interface VueWidgetsInterface extends VuePluginInterface {
+  namespace: string
+  options?: Record<string, unknown>
+  widgets: Record<string, Component>
+}
+```
+
+### SSR Support
+
+```typescript
+import { createSSRApp } from 'vue'
+import { createMemoryHistory } from 'vue-router'
+import { renderToString } from 'vue/server-renderer'
+import { VueApplication, ModuleLoader } from '@libs-for-dev/vue-modular-application'
+
+export async function renderApp(url: string) {
+  const moduleRegistry = ModuleLoader.getModulesRegistry()
+  const appInstance = new VueApplication(
+    createSSRApp,
+    createMemoryHistory(),
+    moduleRegistry
+  )
+
+  const app = appInstance.build({
+    name: 'App',
+    template: '<router-view />'
+  })
+
+  // Set route for SSR
+  app.config.globalProperties.$router.push(url)
+  await app.config.globalProperties.$router.isReady()
+
+  const html = await renderToString(app)
+
+  return html
+}
+```
+
+## Advanced Scenarios
+
+### Conditional Module Loading
+
+```typescript
+// Dynamic module registration based on conditions
+if (process.env.NODE_ENV === 'development') {
+  ModuleLoader.registerModuleProvider(new DevToolsModule())
+}
+
+if (userHasAdminRole()) {
+  ModuleLoader.registerModuleProvider(new AdminModule())
+}
+```
+
+### Custom Plugins with Typing
+
+```typescript
+interface CustomPluginOptions {
+  apiUrl: string
+  timeout: number
+}
+
+class CustomPlugin implements VuePluginInterface {
+  constructor(private options: CustomPluginOptions) {}
+
+  install(app: App) {
+    app.config.globalProperties.$customService = new CustomService(this.options)
+
+    app.provide('customService', app.config.globalProperties.$customService)
+  }
+}
+
+// Usage in module
+getPlugins(): VuePluginInterface[] {
+  return [
+    new CustomPlugin({
+      apiUrl: 'https://api.example.com',
+      timeout: 5000
+    })
+  ]
+}
+```
+
+### Route Middleware
+
+```typescript
+export class ProtectedModule implements ClientModuleInterface<NavigationItem[], RouteRecordRaw[], Container> {
+  getRoutes(): RouteRecordRaw[] {
+    return [
+      {
+        path: '/admin',
+        name: 'Admin',
+        component: () => import('./components/AdminPage.vue'),
+        meta: {
+          requiresAuth: true,
+          roles: ['admin']
+        }
+      }
+    ]
+  }
+
+  getPlugins(): VuePluginInterface[] {
+    return [
+      {
+        install(app) {
+          // Register middleware for authorization check
+          app.config.globalProperties.$router.beforeEach((to, from, next) => {
+            if (to.meta.requiresAuth && !isAuthenticated()) {
+              next('/login')
+            } else {
+              next()
+            }
+          })
+        }
+      }
+    ]
+  }
+}
+```
+
+## Architectural Principles
+
+### 1. Complete Module Isolation
+
+Modules should not have direct dependencies on each other. Interaction occurs only through:
+
+- **ModuleRegistry** - for accessing widgets from other modules
+- **Data Denormalization** - passing `authorId` + `authorName` instead of importing `UserInterface`
+- **Common Interfaces** - using base types from shared library
+
+### 2. Modular Structure
+
+```text
+src/modules/
+├── module-name/
+│   ├── module-name.module.ts    # Module entry point
+│   ├── module-name.service.ts   # Module business logic
+│   ├── pages/                   # Module pages(optional)
+│   └── widgets/                 # Module widgets(optional)
+```
+
+### 3. Dependency Injection
+
+Example of using Inversify for dependency management within modules:
+
+```typescript
+getContainer(): ContainerPluginInterface<Container>[] {
+  const container = new Container()
+
+  return [{
+    container,
+    install() {
+      container.bind('UserService').to(UserService).inSingletonScope()
+    }
+  }]
+}
+```
+
+## Tips and Recommendations
+
+1. **Module Naming**: Use unique names for modules to avoid conflicts
+2. **Lazy Loading**: Use dynamic imports for components and widgets
+3. **Typing**: Define types for Navigation and Routes for better typing
+4. **Testing**: Each module should be covered by unit tests
+5. **Performance**: Register only necessary modules for specific environment
+6. **Isolation**: Avoid direct imports between modules
+7. **Denormalization**: Pass required data explicitly instead of importing types
+
+## License
+
+MIT
+
+## Support
+
+- [Issues](https://gitlab.com/libs-for-dev/nodejs/vue-modular-application/-/issues)
+- [Repository](https://gitlab.com/libs-for-dev/nodejs/vue-modular-application)

package/dist/index.cjs

@@ -0,0 +1 @@
+let e=require(`vue`),t=require(`vue-router`);const n=Symbol(`ModuleRegistry`);var r=class{widgets=new Map;constructor(e){this.clientModules=e;let t=this.clientModules.flatMap(e=>e.getWidgets());for(let e of t)this.registerWidget(e)}getAllRoutes(){return this.getModules().flatMap(e=>e.getRoutes())}getModules(){return this.clientModules}getNavigation(){let t=(0,e.ref)([]);for(let e of this.getModules()){let n=e.getNavigation();t.value.push(...n)}return t}getWidget(e,t){return this.widgets.get(e)?.widgets[t]}registerWidget(e){this.widgets.set(e.namespace,e)}},i=class{static modules=new Map;static getModulesRegistry(){return new r([...this.modules.values()])}static registerModuleProvider(e){let{name:t}=e;this.modules.has(t)||this.modules.set(t,e)}},a=class{constructor(e,t,n){this.createApp=e,this.routerHistory=t,this.moduleRegistry=n}build(e){let r=this.createApp(e);r.provide(n,this.moduleRegistry);let i=this.moduleRegistry.getAllRoutes();(0,t.createRouter)({history:this.routerHistory,routes:i}).install(r);let a=this.moduleRegistry.getModules();for(let e of a.flatMap(e=>[...e.getContainer(),...e.getPlugins(),...e.getWidgets()]))e.install(r);return r}};exports.MODULE_REGISTRY=n,exports.ModuleLoader=i,exports.ModuleRegistry=r,exports.VueApplication=a;

package/dist/index.d.cts

@@ -0,0 +1,61 @@
+import { App, Component, CreateAppFunction, DefineComponent, Ref, UnwrapRef } from "vue";
+import { RouteRecordRaw, RouterHistory } from "vue-router";
+
+//#region src/client-module/plugins/vue-plugin.interface.d.ts
+interface VuePluginInterface {
+  install(app: App): void;
+}
+//#endregion
+//#region src/client-module/plugins/container-plugin.interface.d.ts
+interface ContainerPluginInterface<Container> extends VuePluginInterface {
+  container: Container;
+}
+//#endregion
+//#region src/client-module/plugins/vue-widget.interface.d.ts
+interface VueWidgetsInterface extends VuePluginInterface {
+  namespace: string;
+  options?: Record<string, unknown>;
+  widgets: Record<string, Component>;
+}
+//#endregion
+//#region src/client-module/client-module.interface.d.ts
+interface ClientModuleInterface<Routes extends RouteRecordRaw[], Navigation$1, Container = unknown> {
+  getContainer(): ContainerPluginInterface<Container>[];
+  getNavigation(): Navigation$1;
+  getPlugins(): VuePluginInterface[];
+  getRoutes(): Routes;
+  getWidgets(): VueWidgetsInterface[];
+  readonly name: string;
+}
+//#endregion
+//#region src/client-module/module-registry.d.ts
+declare const MODULE_REGISTRY: unique symbol;
+declare class ModuleRegistry<Routes extends RouteRecordRaw[], Navigation$1> {
+  private readonly clientModules;
+  private readonly widgets;
+  constructor(clientModules: ClientModuleInterface<Routes, Navigation$1>[]);
+  getAllRoutes(): RouteRecordRaw[];
+  getModules(): ClientModuleInterface<Routes, Navigation$1>[];
+  getNavigation(): Ref<UnwrapRef<Navigation$1[]>>;
+  getWidget(namespace: string, widgetName: string): unknown;
+  private registerWidget;
+}
+//#endregion
+//#region src/client-module/module-loader.d.ts
+declare class ModuleLoader {
+  private static readonly modules;
+  static getModulesRegistry(): ModuleRegistry<RouteRecordRaw[], unknown[]>;
+  static registerModuleProvider(module: ClientModuleInterface<RouteRecordRaw[], unknown[]>): void;
+}
+//#endregion
+//#region src/vue-application.d.ts
+type Navigation = unknown[];
+declare class VueApplication {
+  private readonly createApp;
+  private readonly routerHistory;
+  private readonly moduleRegistry;
+  constructor(createApp: CreateAppFunction<Element>, routerHistory: RouterHistory, moduleRegistry: ModuleRegistry<RouteRecordRaw[], Navigation>);
+  build(element: DefineComponent): App<Element>;
+}
+//#endregion
+export { ClientModuleInterface, ContainerPluginInterface, MODULE_REGISTRY, ModuleLoader, ModuleRegistry, VueApplication, VuePluginInterface, VueWidgetsInterface };

package/dist/index.d.mts

@@ -0,0 +1,61 @@
+import { App, Component, CreateAppFunction, DefineComponent, Ref, UnwrapRef } from "vue";
+import { RouteRecordRaw, RouterHistory } from "vue-router";
+
+//#region src/client-module/plugins/vue-plugin.interface.d.ts
+interface VuePluginInterface {
+  install(app: App): void;
+}
+//#endregion
+//#region src/client-module/plugins/container-plugin.interface.d.ts
+interface ContainerPluginInterface<Container> extends VuePluginInterface {
+  container: Container;
+}
+//#endregion
+//#region src/client-module/plugins/vue-widget.interface.d.ts
+interface VueWidgetsInterface extends VuePluginInterface {
+  namespace: string;
+  options?: Record<string, unknown>;
+  widgets: Record<string, Component>;
+}
+//#endregion
+//#region src/client-module/client-module.interface.d.ts
+interface ClientModuleInterface<Routes extends RouteRecordRaw[], Navigation$1, Container = unknown> {
+  getContainer(): ContainerPluginInterface<Container>[];
+  getNavigation(): Navigation$1;
+  getPlugins(): VuePluginInterface[];
+  getRoutes(): Routes;
+  getWidgets(): VueWidgetsInterface[];
+  readonly name: string;
+}
+//#endregion
+//#region src/client-module/module-registry.d.ts
+declare const MODULE_REGISTRY: unique symbol;
+declare class ModuleRegistry<Routes extends RouteRecordRaw[], Navigation$1> {
+  private readonly clientModules;
+  private readonly widgets;
+  constructor(clientModules: ClientModuleInterface<Routes, Navigation$1>[]);
+  getAllRoutes(): RouteRecordRaw[];
+  getModules(): ClientModuleInterface<Routes, Navigation$1>[];
+  getNavigation(): Ref<UnwrapRef<Navigation$1[]>>;
+  getWidget(namespace: string, widgetName: string): unknown;
+  private registerWidget;
+}
+//#endregion
+//#region src/client-module/module-loader.d.ts
+declare class ModuleLoader {
+  private static readonly modules;
+  static getModulesRegistry(): ModuleRegistry<RouteRecordRaw[], unknown[]>;
+  static registerModuleProvider(module: ClientModuleInterface<RouteRecordRaw[], unknown[]>): void;
+}
+//#endregion
+//#region src/vue-application.d.ts
+type Navigation = unknown[];
+declare class VueApplication {
+  private readonly createApp;
+  private readonly routerHistory;
+  private readonly moduleRegistry;
+  constructor(createApp: CreateAppFunction<Element>, routerHistory: RouterHistory, moduleRegistry: ModuleRegistry<RouteRecordRaw[], Navigation>);
+  build(element: DefineComponent): App<Element>;
+}
+//#endregion
+export { ClientModuleInterface, ContainerPluginInterface, MODULE_REGISTRY, ModuleLoader, ModuleRegistry, VueApplication, VuePluginInterface, VueWidgetsInterface };

package/dist/index.mjs

@@ -0,0 +1 @@
+import{ref as e}from"vue";import{createRouter as t}from"vue-router";const n=Symbol(`ModuleRegistry`);var r=class{widgets=new Map;constructor(e){this.clientModules=e;let t=this.clientModules.flatMap(e=>e.getWidgets());for(let e of t)this.registerWidget(e)}getAllRoutes(){return this.getModules().flatMap(e=>e.getRoutes())}getModules(){return this.clientModules}getNavigation(){let t=e([]);for(let e of this.getModules()){let n=e.getNavigation();t.value.push(...n)}return t}getWidget(e,t){return this.widgets.get(e)?.widgets[t]}registerWidget(e){this.widgets.set(e.namespace,e)}},i=class{static modules=new Map;static getModulesRegistry(){return new r([...this.modules.values()])}static registerModuleProvider(e){let{name:t}=e;this.modules.has(t)||this.modules.set(t,e)}},a=class{constructor(e,t,n){this.createApp=e,this.routerHistory=t,this.moduleRegistry=n}build(e){let r=this.createApp(e);r.provide(n,this.moduleRegistry);let i=this.moduleRegistry.getAllRoutes();t({history:this.routerHistory,routes:i}).install(r);let a=this.moduleRegistry.getModules();for(let e of a.flatMap(e=>[...e.getContainer(),...e.getPlugins(),...e.getWidgets()]))e.install(r);return r}};export{n as MODULE_REGISTRY,i as ModuleLoader,r as ModuleRegistry,a as VueApplication};

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@libs-for-dev/vue-modular-application",
+  "version": "0.0.1",
+  "description": "Vue modular application",
+  "keywords": [
+    "vue"
+  ],
+  "homepage": "https://gitlab.com/libs-for-dev/nodejs/vue-modular-application",
+  "bugs": "https://gitlab.com/libs-for-dev/nodejs/vue-modular-application/-/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://gitlab.com/libs-for-dev/nodejs/vue-modular-application.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "libs-for-dev"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "main": "dist/index.mjs",
+  "types": "dist/index.d.mts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "rm -rf ./dist && cti create ./src && tsdown && cti clean ./src",
+    "dev:quality": "yarn concurrently --timings --kill-others-on-fail 'yarn lint' 'yarn test'",
+    "dev:test:watch": "vitest",
+    "lint": "yarn concurrently --timings 'yarn:lint:*'",
+    "lint:audit": "yarn npm audit",
+    "lint:depcheck": "knip",
+    "lint:eslint": "eslint --cache .",
+    "lint:scriptlint": "scriptlint",
+    "lint:tsc": "tsc --noEmit --pretty --project .",
+    "test": "yarn concurrently --timings 'npm:test:*'",
+    "test:mutation": "yarn stryker run",
+    "test:unit": "vitest run"
+  },
+  "devDependencies": {
+    "@libs-for-dev/eslint-rules": "2.5.0",
+    "@stryker-mutator/core": "9.4.0",
+    "@stryker-mutator/vitest-runner": "9.4.0",
+    "@tsconfig/strictest": "^2.0.8",
+    "@types/node": "25.0.6",
+    "@vitest/coverage-v8": "4.0.16",
+    "concurrently": "9.2.1",
+    "create-ts-index": "1.14.0",
+    "eslint": "9.39.2",
+    "jiti": "2.6.1",
+    "knip": "5.80.2",
+    "reflect-metadata": "0.2.2",
+    "sass-embedded": "1.97.2",
+    "scriptlint": "3.0.0",
+    "tsdown": "0.19.0",
+    "typescript": "5.9.3",
+    "vitest": "4.0.16",
+    "vue": "3.5.26",
+    "vue-router": "4.6.4",
+    "yarn-audit-fix": "10.1.1"
+  },
+  "peerDependencies": {
+    "vue": ">=3.0.0 <4.0.0",
+    "vue-router": ">=4.0.0 <5.0.0"
+  },
+  "packageManager": "yarn@4.12.0",
+  "engines": {
+    "node": "^24.7.0"
+  }
+}