Extend packmind with plugins

[MaloPromyze]

Packmind Plugin System

see demo plugin repository here

Plugin System Summary

Purpose

The plugin system enables external plugins to extend Packmind's functionality at runtime without modifying the core codebase. Plugins can add:

• Backend domain logic (Hexa classes)
• API endpoints (NestJS controllers)
• Frontend routes and components
• Navigation items (sidebar links)
• Dashboard widgets (custom UI components)

Architecture

Plugin Structure

Each plugin is a separate repository containing:

• Hexa Domain (hexaBundle.cjs): Business logic classes that extend BaseHexa
• API Module (apiBundle.cjs): NestJS modules and controllers
• Frontend Bundle (frontendBundle.mjs): React components, routes, and UI elements
• Manifest (manifest.json): Plugin metadata and configuration

Loading Mechanism

• Plugins are discovered from the /plugins directory at application startup
• Bundles are loaded dynamically using Node.js require() and ES module imports
• Hexa classes are registered in the HexaRegistry
• NestJS modules are imported into the main application
• Frontend routes are merged with the main app's routing system

Current Capabilities

✅ Backend Integration

• Hexa Domain: Plugins can define domain logic classes that integrate with the HexaRegistry
• API Endpoints: Plugins can expose REST endpoints via NestJS controllers
• Dependency Injection: Plugins can inject services (e.g., HexaRegistry) via NestJS DI

✅ Frontend Integration

• Dynamic Routes: Plugins can add React Router routes that are automatically registered
• Navigation Items: Plugins can inject navigation items into the sidebar via the usePlugins() hook
• Dashboard Widgets: Plugins can inject React components into the dashboard
• Outlet System: Generic system for plugins to inject content into predefined "outlets" (e.g., sidebar-nav, dashboard-content)

✅ Type Safety

• Shared types in @packmind/types ensure type safety between plugins and the main app
• TypeScript interfaces for plugin contracts (PluginNavigationItem, PluginOutletContent, etc.)

Technical Implementation

Build Process

• Hexa & API: Compiled with TypeScript to preserve decorator metadata (required for NestJS)
• Frontend: Bundled with esbuild, with external dependencies provided by the main app
• Metadata Preservation: API bundles use compiled TypeScript code to ensure NestJS decorators work correctly

Runtime Loading

• Backend: Plugins are loaded before NestJS app bootstrap to ensure proper module registration
• Frontend: Plugin bundles are loaded asynchronously via PluginProvider React context
• Route Generation: Plugin routes are generated at build-time and merged with main app routes

Example Plugin

The packmind-plugin repository demonstrates:

• A Hexa class with a helloWorld() method
• A NestJS controller with /api/sample-plugin/health and /api/sample-plugin/hello-world endpoints
• A frontend route at /org/:orgSlug/plugin-feature
• A sidebar navigation item
• A dashboard widget component

Current Status

✅ Working

• Plugin discovery and loading
• Hexa class registration
• NestJS module and controller registration
• Frontend route generation and loading
• Navigation item injection
• Dashboard widget injection
• Type safety with shared types

⚠️ Known Issues

• Controller route metadata detection shows "0 methods" in logs (routes still work correctly - NestJS discovers them automatically)
• Requires Docker container restart after plugin changes

Future Enhancements

• Plugin priority/ordering system
• Plugin configuration UI
• Hot-reloading for development
• Plugin marketplace/discovery
• Plugin versioning and compatibility checks

Conclusion

This system enables Packmind to be extended by third-party developers without modifying the core codebase, supporting a plugin ecosystem that can grow independently of the main application.

[sonarqubecloud]

Quality Gate failed

Failed conditions
C Reliability Rating on New Code (required ≥ A)

See analysis details on SonarQube Cloud

Catch issues before they fail your Quality Gate with our IDE extension SonarQube for IDE