⚠️ DISCLAIMER: FOR INSPIRATION ONLY

This project is provided for educational and inspirational purposes only. It is not intended for production use.
It serves as a proof of concept and should be treated as a reference or learning example, not a production-ready implementation.
The code has not been thoroughly tested or validated for production use cases.

⚠️ CAUTION: AI-Generated Code
Portions of this project were developed using AI assistance (Claude Code). Always review and validate the code before adapting it for your own use.

⚠️ IMPORTANT: Bundler Compatibility Limitations
This tool uses Vite bundler for development while PCF uses webpack for production builds. These have fundamental compatibility differences that may cause issues.
Code that works in this harness may fail when built with PCF's webpack bundler.

📖 Read the full technical details in BUNDLER-COMPATIBILITY.md

A modern Vite-based development harness for PowerApps Component Framework (PCF) components with hot module replacement and PowerApps-like environment simulation.

• 🚀 Fast Development: Vite-powered with instant hot module replacement (HMR)
• 🎯 PowerApps Environment: Accurate replication of PowerApps container structure and styling
• 🔗 Dataverse Integration: Built-in integration with dataverse-utilities for real data testing
• 📱 Responsive: Works across different screen sizes like PowerApps
• 🛠️ TypeScript Support: Full TypeScript support with type definitions
• ⚡ Modern Tooling: Built on modern web technologies (Vite, React, TypeScript)

1. Navigate to your PCF project directory

   cd your-pcf-project

2. Run the initializer

   npx pcf-vite-harness
   # or explicitly:
   npx pcf-vite-harness init

   The CLI will:

   • 🔍 Auto-detect your PCF components
   • ⚙️ Guide you through interactive configuration
   • 📝 Generate all necessary development files
   • 📦 Update your package.json with dev script
   • ✅ All dependencies included - no manual installation needed!

3. Start development

   npm run dev:pcf

Create a complete new PCF project with Vite harness pre-configured:

npx pcf-vite-harness create

Your PCF component will open at http://localhost:3000 with full HMR support!

If you prefer manual setup or need explicit dependency control:

# Install the harness locally
npm install pcf-vite-harness --save-dev

Then create the development files in a dev/ directory. See the templates directory for examples.

The main command with subcommands for different workflows:

• 🔍 Auto-detection: Automatically finds PCF components by scanning for ControlManifest.xml files
• 📝 Smart Configuration: Generates configuration files with correct paths and component imports
• ⚙️ Interactive Setup: Guided prompts for port configuration, Dataverse integration, etc.
• 🔒 Safe Operation: Asks before overwriting existing files
• 📦 Package Integration: Automatically adds npm scripts to your package.json

npx pcf-vite-harness init

The CLI will guide you through:

• Component selection (if multiple found)
• Development server configuration
• Dataverse integration setup

Creates a complete PCF project using Power Platform CLI (pac) with Vite harness pre-configured:

• 🚀 Full Project Setup: Creates PCF project structure using pac pcf init
• 🎯 Template Support: Supports both field and dataset component types
• ⚙️ Interactive Setup: Guided prompts for easy configuration
• 📊 Manifest Parsing: Extracts component info from ControlManifest.Input.xml
• 📦 Dependency Management: Updates package.json and installs dependencies

npx pcf-vite-harness create

The CLI will guide you through:

• PCF component namespace and name
• Component type (field or dataset)
• Project directory setup
• Dataverse integration (optional)

Regenerates the context configuration after completing the setup wizard:

• 🔄 Context Regeneration: Updates main.ts with proper dataset information from manifest
• 📋 Dataset Detection: Automatically detects dataset configurations from ControlManifest.xml
• ⚙️ Environment Integration: Works with .env variables set by the setup wizard

npx pcf-vite-harness generate-context

Use this command after completing the browser-based setup wizard to ensure your development context includes all the dataset configurations discovered during setup.

import { initializePCFHarness } from 'pcf-vite-harness';
import { YourPCFComponent } from '../YourComponent/index';

initializePCFHarness({
    pcfClass: YourPCFComponent,
    contextOptions: {
        displayName: 'John Doe',
        userName: 'john.doe@company.com',
        controlId: 'custom-control-id',
        viewId: 'custom-view-id'
    },
    className: 'custom-container-class'
});

The dataverse-utilities package is automatically included and configured. To enable Dataverse integration:

1. Set your Dataverse URL in .env:

   VITE_DATAVERSE_URL=https://yourorg.crm.dynamics.com/
   

2. Configure Dataverse URL:

   export default createPCFViteConfig({
       dataverseUrl: process.env.VITE_DATAVERSE_URL
   });

3. Use Dataverse Web API in your component:

   // Your component can now make calls to /api/data/v9.2/...
   const response = await fetch('/api/data/v9.2/accounts?$top=10');
   const data = await response.json();

For dataset components only, the harness includes a setup wizard accessible at /setup when running the development server. This wizard helps configure your dataset component with real Dataverse data:

• 📊 Dataset-Only: Designed specifically for PCF dataset components (not available for field components)
• 🔗 Table Relationships: Automatically discovers and configures table relationships
• 👁️ View Selection: Choose from available system or custom views for your dataset
• 🎯 PCF Component Detection: Scans forms to find PCF controls and their dataset configurations
• ⚙️ Interactive Configuration: Step-by-step wizard for complex dataset setup

1. Page Context (Optional): Select the parent table/record for context
2. Record Selection: Choose a specific record for testing
3. Target Table: Select the main table for your dataset component
4. Relationship Discovery: Automatically finds relationships between tables
5. View Selection: Choose the view that defines your dataset structure
6. Component Scanning: Locates PCF controls on forms and extracts dataset names

# Start your development server
npm run dev:pcf

# Navigate to the setup wizard
# http://localhost:3000/setup

Note: The setup wizard is only available for dataset components because they require complex configuration involving table relationships, views, and dataset properties. Field components have simpler requirements and don't need this multi-step setup process.

import { createMockContext, initializePCFHarness } from 'pcf-vite-harness';

const customContext = createMockContext({
    displayName: 'Custom User',
    datasetOptions: {
        loading: false,
        // Add custom dataset properties
    }
});

initializePCFHarness({
    pcfClass: YourPCFComponent,
    customContext
});

Simple initialization function for quick setup.

Parameters:

• pcfClass: Your PCF component class
• options?: Optional configuration object

Advanced initialization with full configuration options.

Parameters:

• options.pcfClass: Your PCF component class
• options.contextOptions?: Mock context configuration
• options.containerId?: Custom container element ID
• options.className?: Additional CSS class
• options.customContext?: Use custom context instead of mock

Creates a realistic mock PCF context.

Parameters:

• options.controlId?: Custom control ID
• options.viewId?: Custom view ID
• options.displayName?: User display name
• options.userName?: Username
• options.userId?: User ID
• options.datasetOptions?: Dataset configuration

Creates optimized Vite configuration for PCF development.

Parameters:

• options.port?: Development server port
• options.dataverseUrl?: Dataverse URL (enables integration when provided)
• options.hmrPort?: HMR WebSocket port
• options.open?: Whether to open browser on server start
• options.viteConfig?: Additional Vite configuration

The library includes comprehensive TypeScript definitions for all interfaces and types.

Contributions are welcome! Please feel free to submit a Pull Request.

MIT License - see LICENSE file for details.

Found a bug or have a feature request? Please create an issue on GitHub.

The harness includes several built-in workarounds for common compatibility issues:

optimizeDeps: { 
  exclude: ['fsevents'] // Already included in base config
}

Issue: On macOS, fsevents (file system watching) contains native .node files that ESBuild cannot process, causing build errors.

Solution: The harness automatically excludes fsevents from Vite's dependency optimization. You can use the same pattern for other native modules:

// In your vite.config.ts if you encounter similar issues
viteConfig: {
  optimizeDeps: { 
    exclude: ['another-native-module', 'problematic-package'] 
  }
}

• Node.js: 18 or higher
• @types/node: 20.19.0 or higher (automatically handled by the CLI)

If you encounter peer dependency conflicts during installation, they are usually resolved automatically during the setup process.