Phase 15: Framework Integration Package Split

September 29, 2025 · View on GitHub

Objective

Extract framework-specific integrations into separate, optional packages to keep the main @nexcraft/forge package lightweight and eliminate CI noise from unused dependencies.

Scope

Split Angular integration into @nexcraft/forge-angular ✅ COMPLETED
Split Vue integration into @nexcraft/forge-vue ✅ COMPLETED
Split React integration into @nexcraft/forge-react 🚧 PLANNED
Maintain @nexcraft/forge as pure web components only (truly framework-agnostic)
Follow the successful pattern established by @nexcraft/forge-rhf

Problem Statement

Originally, the main package contained all framework integrations, causing:

❌ CI noise: TypeScript errors when framework deps not installed
❌ Build warnings: Fallback compilation mode required
❌ Forced dependencies: Users forced to download framework code they don't use
❌ Bundle bloat: Framework-specific code increasing core package size
❌ Architectural impurity: Core package tied to specific frameworks

Solution Architecture

Package Structure (ULTIMATE MINIMAL ARCHITECTURE)

@nexcraft/forge              // PURE web components (truly framework-agnostic)
└── src/components/          // Web components ONLY

@nexcraft/forge-react        // React integration (NEW - Phase 15.4)
├── src/components/          // React component wrappers (33 components)
├── src/utils/               // React utilities
├── src/types/               // React TypeScript definitions
└── src/ssr/                 // SSR compatibility

@nexcraft/forge-vue          // Vue integration (COMPLETED ✅)
├── src/composables/         // Vue composables
├── src/directives/          // Vue directives  
├── src/plugin/              // Vue plugin
└── src/types/               // Vue TypeScript definitions

@nexcraft/forge-angular      // Angular integration (COMPLETED ✅)
├── src/directives/          // Angular directives
├── src/services/            // Angular services  
├── src/forms/               // Angular reactive forms integration
└── src/types/               // Angular TypeScript definitions

@nexcraft/forge-rhf          // React Hook Form (EXISTING ✅)
└── src/adapters/            // RHF adapters (keeps specialized purpose)

Benefits

Clean CI: No more Angular compilation errors
Focused Packages: Each package serves specific ecosystem
Optional Dependencies: Install only what you need
Better Maintenance: Framework experts can maintain their integrations
Proven Pattern: Follows successful RHF approach

Deliverables

Phase 15.1: Angular Package Creation (Priority) ✅ COMPLETED

✅ New workspace package: packages/forge-angular
✅ Migrate Angular integration from src/integrations/angular.ts
✅ Angular directives for web component integration
✅ Angular reactive forms adapters
✅ Angular service for theme management
✅ TypeScript definitions and build setup
✅ Documentation: docs/integrations/angular.md

Phase 15.2: Main Package Cleanup

✅ Remove Angular compilation from vite.config.ts
✅ Remove src/integrations/angular.ts (migrated to @nexcraft/forge-angular)
✅ Update package exports (remove Angular subpath)
✅ Clean CI output validation (zero Angular compilation errors)
✅ Update main package documentation (README.md updated with framework packages section)
✅ PUBLISHED: @nexcraft/forge-angular@0.1.0 available on npm

Phase 15.3: Vue Package (Active Implementation) ✅ COMPLETED

✅ Evaluation Complete: Vue integration is 500+ lines (NOT lightweight!)
✅ Decision: Extract to @nexcraft/forge-vue for truly minimal core package
✅ New workspace package: packages/forge-vue
✅ Migrate Vue integration from src/integrations/vue.ts (composables, plugin, types)
✅ Remove Vue compilation from main package
✅ Update package exports (remove Vue subpath)
✅ PUBLISHED: @nexcraft/forge-vue@0.1.0 available on npm
✅ Update documentation and README

Phase 15.4: React Package (Ultimate Architecture) ✅ COMPLETED

Technical Implementation

React Package Setup

// packages/forge-react/package.json
{
  "name": "@nexcraft/forge-react",
  "version": "0.1.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./components": {
      "types": "./dist/components/index.d.ts",
      "import": "./dist/components/index.js"
    },
    "./hooks": {
      "types": "./dist/hooks/index.d.ts",
      "import": "./dist/hooks/index.js"
    },
    "./ssr": {
      "types": "./dist/ssr/index.d.ts",
      "import": "./dist/ssr/index.js"
    }
  },
  "peerDependencies": {
    "@nexcraft/forge": ">=0.7.0",
    "react": "^17.0.0 || ^18.0.0 || ^19.0.0",
    "react-dom": "^17.0.0 || ^18.0.0 || ^19.0.0"
  }
}

Angular Package Setup

// packages/forge-angular/package.json
{
  "name": "@nexcraft/forge-angular",
  "version": "0.1.0",
  "type": "module",
  "exports": {
    ".": {
      "types": "./dist/index.d.ts",
      "import": "./dist/index.js"
    },
    "./forms": {
      "types": "./dist/forms/index.d.ts", 
      "import": "./dist/forms/index.js"
    }
  },
  "peerDependencies": {
    "@nexcraft/forge": ">=0.7.0",
    "@angular/core": "^17.0.0 || ^18.0.0",
    "@angular/forms": "^17.0.0 || ^18.0.0"
  }
}

Migration Strategy

Extract Current Code: Move src/integrations/angular.ts to new package
Expand Functionality: Add proper Angular directives and services
Build System: Create Angular-specific build configuration
Dependencies: Add Angular as peer dependencies only
Clean Main Package: Remove Angular compilation entirely

Usage Pattern

// Core Forge components (main package) - Pure web components
import '@nexcraft/forge/components';

// React integration (separate package)
import { ForgeButton, ForgeInput, ForgeCard } from '@nexcraft/forge-react';
import { useForgeComponent, useForgeEvent } from '@nexcraft/forge-react/hooks';

// Angular integration (separate package)
import { ForgeDirective, ForgeFormsModule } from '@nexcraft/forge-angular';
import { ForgeInputAdapter } from '@nexcraft/forge-angular/forms';

// Vue integration (separate package)
import { useForgeComponent, useForgeVModel } from '@nexcraft/forge-vue';

Timeline (1-2 weeks)

Week 1: Angular Package Creation

Day 1-2: Package scaffold and build setup
Day 3-4: Migrate and expand Angular integration
Day 5: Documentation and examples

Week 2: Integration and Cleanup

Day 1-2: Main package cleanup and CI fixes
Day 3-4: Testing with Angular projects
Day 5: Publishing and announcement

Success Metrics

Immediate (CI Health)

✅ Zero Angular compilation errors in main package CI
✅ Clean build output without fallback warnings
✅ Main package builds without Angular dependencies

Long-term (Ecosystem)

📈 Angular package adoption by Angular developers
📈 Reduced main package bundle size
📈 Better framework-specific documentation and examples

Risks & Mitigations

Risk: Package Proliferation

Mitigation: Only create packages when clear value (Angular has CI noise issue)
Decision: Vue stays in main package (lightweight, no build issues)

Risk: Version Synchronization

Mitigation: Use workspace publishing with version locking
Benefit: Follow established RHF package patterns

Risk: Maintenance Overhead

Mitigation: Framework packages can be maintained by framework experts
Community: Angular package can attract Angular community contributors

Acceptance Criteria

Phase 12: React Hook Form package split (completed) - provides pattern
Phase 13: Monorepo platform (in progress) - provides infrastructure
Phase 14: Monorepo publishing (future) - will handle multi-package releases

Status: ✅ COMPLETED - Ultimate minimal architecture achieved!
Dependencies: ✅ Phase 13 monorepo infrastructure (satisfied)
Achievements: ✅ Pure web components core, all framework packages published

🎯 Phase 15: Ultimate Architecture ACHIEVED ✅

All Framework Packages Published:

@nexcraft/forge-angular@0.1.0 - Angular integration ✅
@nexcraft/forge-vue@0.1.0 - Vue composables & plugin ✅
@nexcraft/forge-react@0.1.0 - React integration ✅
@nexcraft/forge-rhf@0.3.0 - React Hook Form adapters ✅

✅ Ultimate Architecture Achieved:

@nexcraft/forge - Pure web components (truly framework-agnostic) ✅
All frameworks are now optional separate packages ✅

Benefits Delivered:

🎯 Pure web components core - truly framework-agnostic ✅
📦 Smaller bundle size - no React dependencies in core ✅
🧩 Consistent architecture - all frameworks are optional ✅
🚀 Better performance - framework code only when needed ✅