Plugin Host Architecture Demo

This Val Town project demonstrates the plugin host pattern for managing upstream/downstream changes in a modular application architecture.

When you have a fork of an existing full-stack app that you need to customize while keeping up with upstream changes, traditional approaches create maintenance headaches. This pattern provides a clean solution.

• Plugin Host: Central registry for extension points
• Hook Points: Defined lifecycle moments where plugins can inject behavior
• Stable API: Typed interfaces that don't break with updates

• Plugins: Modular customizations that register with hook points
• Clean Separation: Your code lives outside the upstream subtree
• Future-Proof: Upstream updates don't break your customizations

1. Widget Component: Simulated upstream component with plugin hooks
2. Analytics Plugin: Tracks interactions and sends metrics
3. Customization Plugin: Modifies default behavior and adds features
4. Live Console: Watch plugin hooks fire in real-time

• ✅ Maintainable: Clear separation between upstream and downstream code
• ✅ Testable: Plugin contracts are explicit and typed
• ✅ Flexible: Add new plugins without modifying upstream code
• ✅ Trackable: Use git subtree to track upstream SHA, not just version strings
• ✅ Conflict-Free: Merge conflicts only occur at hook layer boundaries

// 1. Upstream defines hook points
const hooks = pluginHost.getHooks('ComponentName');
for (const hook of hooks) {
  state = hook.beforeInit?.(state) ?? state;
}

// 2. Downstream registers plugins
pluginHost.register('ComponentName', {
  beforeInit: (state) => ({ ...state, customField: true }),
  mounted: ({ state, update }) => console.log('Mounted!'),
  updated: ({ state }) => sendAnalytics(state)
});

├── backend/           # Hono server
├── frontend/          # Client-side demo
├── shared/           # Shared types and utilities
└── README.md         # This file

1. Click the widget button to see plugins in action
2. Open browser console to watch hook execution
3. Notice how plugins modify behavior without touching upstream code

This pattern scales from simple customizations to complex enterprise integrations while maintaining clean boundaries and upgrade paths.