@khester/create-dynamics-app 2.1.0 → 2.2.0

package/templates/react-custom-page/docs/MIGRATION_GUIDE.md

@@ -1,447 +0,0 @@
-# Migration Guide - Dynamics 365 Template
-
-## Overview
-
-This guide helps you migrate existing Dynamics 365 projects to use the enhanced template patterns
-and architecture.
-
-## Migration Scenarios
-
-### 1. From Basic React D365 Apps
-
-If you have a basic React application for Dynamics 365:
-
-#### Before (Basic Pattern)
-
-```typescript
-// Direct API calls without abstraction
-function createAccount(data) {
-  return Xrm.WebApi.createRecord('account', data);
-}
-
-// Component with inline API logic
-function AccountForm() {
-  const handleSubmit = async () => {
-    try {
-      await Xrm.WebApi.createRecord('account', formData);
-    } catch (error) {
-      console.error(error);
-    }
-  };
-}
-```
-
-#### After (Enhanced Pattern)
-
-```typescript
-// Entity model with validation and logging
-export class Account extends BaseEntity {
-  public static async create(apiService: IApiService, account: Account): Promise<Account> {
-    return await this.createEntity<Account>(
-      apiService,
-      account,
-      AccountConstants.EntityCollectionName,
-      'Account.create'
-    );
-  }
-}
-
-// Component using service layer
-function AccountForm() {
-  const { apiService } = useDynamicsApi();
-
-  const handleSubmit = async () => {
-    try {
-      const account = new Account(formData);
-      await Account.create(apiService, account);
-      Logger.userAction('Account created', { name: formData.name });
-    } catch (error) {
-      Logger.error('Failed to create account', 'AccountForm', error);
-    }
-  };
-}
-```
-
-#### Migration Steps
-
-1. **Install the Template Dependencies**
-
-   ```bash
-   npm install @khester/dynamics-ui-components @khester/dynamics-ui-api-client
-   ```
-
-2. **Create Entity Models**
-   - Copy `src/models/BaseEntity.ts` to your project
-   - Create entity models extending BaseEntity
-   - Add constants files for field definitions
-
-3. **Implement Service Layer**
-   - Copy `src/services/ServiceFactory.ts`
-   - Copy API service implementations
-   - Update components to use the service layer
-
-4. **Add Logging System**
-   - Copy `src/components/Logging/` directory
-   - Wrap your app with `LoggingProvider`
-   - Replace console calls with Logger methods
-
-### 2. From PCF Controls to Template
-
-If you're building PCF controls:
-
-#### Before (Basic PCF)
-
-```typescript
-export class MyControl implements ComponentFramework.StandardControl<IInputs, IOutputs> {
-  public init(context: ComponentFramework.Context<IInputs>): void {
-    // Direct DOM manipulation or basic React
-    this.container.innerHTML = '<div>Basic Content</div>';
-  }
-}
-```
-
-#### After (Template PCF)
-
-```typescript
-export class MyControl implements ComponentFramework.StandardControl<IInputs, IOutputs> {
-  public init(context: ComponentFramework.Context<IInputs>): void {
-    // Use sophisticated wrapper components
-    ReactDOM.render(
-      React.createElement(CustomPCFWrapper, {
-        context,
-        entityType: 'contact',
-        enableLogging: true,
-        showTabs: true,
-      }),
-      this.container
-    );
-  }
-}
-```
-
-#### Migration Steps
-
-1. **Copy PCF Wrapper Components**
-   - Copy `src/pcf/` directory to your PCF project
-   - Update your PCF control to use the wrappers
-
-2. **Integrate with Entity Models**
-   - Copy entity models and constants
-   - Use the service factory for API access
-
-3. **Update PCF Configuration**
-   - Update your `ControlManifest.Input.xml`
-   - Ensure React dependencies are included
-
-### 3. From Web Resources to Template
-
-If you're using traditional web resources:
-
-#### Before (Traditional Web Resources)
-
-```html
-<!-- HTML Web Resource -->
-<script src="/scripts/jquery.min.js"></script>
-<script src="/scripts/custom.js"></script>
-<div id="myApp">
-  <!-- Static HTML content -->
-</div>
-
-<script>
-  // Direct Xrm calls
-  function loadAccounts() {
-    Xrm.WebApi.retrieveMultipleRecords('account', '?$select=name,accountid').then(
-      function (result) {
-        // Manual DOM manipulation
-        var html = '';
-        result.entities.forEach(function (account) {
-          html += '<div>' + account.name + '</div>';
-        });
-        document.getElementById('accountList').innerHTML = html;
-      }
-    );
-  }
-</script>
-```
-
-#### After (Template Web Resources)
-
-```html
-<!-- Modern React Web Resource -->
-<div id="root"></div>
-<script src="/scripts/main.js"></script>
-
-<!-- main.js contains the compiled React app -->
-<script>
-  // Sophisticated React application with:
-  // - Entity models and validation
-  // - Service layer abstraction
-  // - Comprehensive logging
-  // - Error handling
-  // - Type safety
-</script>
-```
-
-#### Migration Steps
-
-1. **Generate Template Application**
-
-   ```bash
-   npx @khester/create-dynamics-app my-app --template dynamics-365
-   ```
-
-2. **Copy Existing Business Logic**
-   - Convert existing functions to entity model methods
-   - Move validation to model classes
-   - Replace direct DOM manipulation with React components
-
-3. **Build and Deploy**
-   ```bash
-   npm run build:prod
-   # Upload dist/main.js as Script (JScript) web resource
-   # Upload dist/index.html as Web Page (HTML) web resource
-   ```
-
-## Best Practices for Migration
-
-### 1. Incremental Migration
-
-Don't migrate everything at once. Start with:
-
-1. **Core Infrastructure**
-   - Service factory and API services
-   - Logging system
-   - Base entity class
-
-2. **One Entity at a Time**
-   - Pick the most important entity
-   - Create model, constants, and components
-   - Test thoroughly before moving to next entity
-
-3. **Component by Component**
-   - Replace existing forms with template components
-   - Update list views to use DetailsList patterns
-   - Add proper error handling and validation
-
-### 2. Data Validation Migration
-
-#### Before
-
-```typescript
-function validateAccount(data) {
-  var errors = [];
-  if (!data.name) {
-    errors.push('Name is required');
-  }
-  return errors;
-}
-```
-
-#### After
-
-```typescript
-export class Account extends BaseEntity {
-  public validate(): boolean {
-    const errors: string[] = [];
-
-    if (!this.name?.trim()) {
-      errors.push('Account name is required');
-    }
-
-    if (this.name && this.name.length > 160) {
-      errors.push('Account name cannot exceed 160 characters');
-    }
-
-    if (errors.length > 0) {
-      Logger.validation('Account', errors, 'Account.validate');
-      throw new Error(`Validation failed: ${errors.join(', ')}`);
-    }
-
-    return true;
-  }
-}
-```
-
-### 3. Error Handling Migration
-
-#### Before
-
-```typescript
-try {
-  await Xrm.WebApi.createRecord('account', data);
-  alert('Success');
-} catch (error) {
-  alert('Error: ' + error.message);
-}
-```
-
-#### After
-
-```typescript
-try {
-  const account = new Account(data);
-  const result = await Account.create(apiService, account);
-  Logger.userAction('Account created successfully', { accountId: result.accountid });
-  // Use proper UI notifications instead of alerts
-} catch (error) {
-  Logger.error('Failed to create account', 'AccountForm.handleSubmit', error);
-  // Show user-friendly error message
-  setErrorMessage('Unable to create account. Please try again.');
-}
-```
-
-### 4. Environment Detection Migration
-
-#### Before
-
-```typescript
-// Hard-coded environment logic
-if (window.location.hostname === 'localhost') {
-  // Use mock data
-} else {
-  // Use Xrm.WebApi
-}
-```
-
-#### After
-
-```typescript
-// Sophisticated environment detection
-const apiService = ServiceFactory.createApiService();
-// Automatically detects environment and provides appropriate service
-```
-
-## Common Migration Challenges
-
-### 1. TypeScript Adoption
-
-**Challenge**: Existing JavaScript code needs TypeScript conversion
-
-**Solution**:
-
-1. Start with `.ts` files and `any` types
-2. Gradually add proper type definitions
-3. Use the template's interface definitions as examples
-
-### 2. Bundle Size Concerns
-
-**Challenge**: React app may be larger than traditional web resources
-
-**Solution**:
-
-- Use the template's optimized build configuration
-- Production build is only ~726KB
-- Enable compression in IIS for web resources
-- Consider code splitting for large applications
-
-### 3. PCF Framework Limitations
-
-**Challenge**: PCF has restrictions on external dependencies
-
-**Solution**:
-
-- Use the template's PCF wrapper patterns
-- Bundle dependencies in the control
-- Use the provided ComponentFramework type definitions
-
-### 4. Dynamics 365 API Differences
-
-**Challenge**: Different API behaviors between environments
-
-**Solution**:
-
-- Use the ServiceFactory to abstract differences
-- Implement environment-specific logic in service classes
-- Test thoroughly in both development and production
-
-## Migration Checklist
-
-### Pre-Migration Assessment
-
-- [ ] Inventory existing entities and operations
-- [ ] Identify current validation logic
-- [ ] Document existing API usage patterns
-- [ ] Assess current error handling approaches
-
-### Migration Implementation
-
-- [ ] Set up development environment with template
-- [ ] Create entity models for core entities
-- [ ] Implement service layer abstraction
-- [ ] Add logging throughout application
-- [ ] Create management components
-- [ ] Implement proper error handling
-- [ ] Add comprehensive validation
-
-### Testing and Validation
-
-- [ ] Test in development environment
-- [ ] Validate all CRUD operations
-- [ ] Test error scenarios
-- [ ] Verify logging functionality
-- [ ] Test build and deployment process
-- [ ] User acceptance testing
-
-### Production Deployment
-
-- [ ] Build production bundle
-- [ ] Upload web resources to D365
-- [ ] Configure security roles
-- [ ] Train users on new interface
-- [ ] Monitor for issues
-
-## Support and Resources
-
-### Template Resources
-
-- **Documentation**: README.md in template root
-- **Examples**: `/src/examples/` directory
-- **Integration Tests**: INTEGRATION_TEST_RESULTS.md
-
-### Development Tools
-
-- **Quality Scripts**: `npm run quality`
-- **Build Validation**: `npm run validate`
-- **Type Checking**: `npm run typecheck`
-
-### Community and Support
-
-- **GitHub Issues**: Report problems or ask questions
-- **Documentation**: Comprehensive inline documentation
-- **Examples**: Real-world implementation patterns
-
-## Version Compatibility
-
-### Dynamics 365 Versions
-
-- **Online**: Fully supported
-- **On-Premises**: Compatible with modern browsers
-- **Government Cloud**: Supported
-
-### Browser Support
-
-- **Chrome**: 70+
-- **Edge**: 79+
-- **Firefox**: 65+
-- **Safari**: 12+
-
-### Node.js Versions
-
-- **Minimum**: Node 16+
-- **Recommended**: Node 18+
-- **Latest**: Node 20+
-
-## Conclusion
-
-Migrating to the enhanced Dynamics 365 template provides significant benefits:
-
-- **Type Safety**: Full TypeScript support
-- **Error Handling**: Comprehensive error management
-- **Logging**: Detailed operation tracking
-- **Validation**: Client-side and business rule validation
-- **Performance**: Optimized build process
-- **Maintainability**: Clean architecture patterns
-- **Developer Experience**: Modern tooling and documentation
-
-The migration process, while requiring initial effort, results in more robust, maintainable, and
-scalable Dynamics 365 applications.

package/templates/react-custom-page/public/index.html

@@ -1,15 +0,0 @@
-<!DOCTYPE html>
-<html lang="en">
-<head>
-    <meta charset="utf-8" />
-    <link rel="icon" href="data:," />
-    <meta name="viewport" content="width=device-width, initial-scale=1" />
-    <meta name="theme-color" content="#000000" />
-    <meta name="description" content="Dynamics 365 Application built with Dynamics UI Kit" />
-    <title>Dynamics 365 App - Dynamics UI Kit</title>
-</head>
-<body>
-    <noscript>You need to enable JavaScript to run this app.</noscript>
-    <div id="root"></div>
-</body>
-</html>

package/templates/react-custom-page/scripts/custom-build.js

@@ -1,255 +0,0 @@
-const webpack = require('webpack');
-const path = require('path');
-const fs = require('fs');
-
-// Get webpack config
-const webpackConfigPath = path.resolve(__dirname, '../webpack.config.js');
-const getWebpackConfig = require(webpackConfigPath);
-
-// Check command line arguments for dev mode
-const isDev = process.argv.includes('--dev') || process.argv.includes('-dev');
-const mode = isDev ? 'development' : 'production';
-
-console.log(`Custom Build Script - Mode: ${mode}`);
-
-// Create custom webpack config for D365 deployment
-function createD365WebpackConfig() {
-  // Get base config
-  const baseConfig = getWebpackConfig({}, { mode });
-
-  // D365-specific optimizations
-  const d365Config = {
-    ...baseConfig,
-    mode,
-    optimization: {
-      // Disable code splitting for single file deployment
-      splitChunks: {
-        cacheGroups: {
-          default: false,
-          vendors: false,
-        },
-      },
-      // Disable runtime chunk
-      runtimeChunk: false,
-      // Control minimization based on mode
-      minimize: !isDev,
-    },
-    output: {
-      ...baseConfig.output,
-      // Remove hashes for consistent D365 web resource naming
-      filename: '[name].js',
-      chunkFilename: '[name].chunk.js',
-      assetModuleFilename: '[name][ext]',
-      // Set public path for D365 context
-      publicPath: './',
-    },
-    // Add performance hints for large bundles
-    performance: {
-      hints: isDev ? false : 'warning',
-      maxEntrypointSize: 2000000, // 2MB - reasonable for D365
-      maxAssetSize: 2000000,
-    },
-  };
-
-  // Modify CSS handling for single file output
-  const rules = d365Config.module.rules.map((rule) => {
-    if (rule.test && rule.test.toString().includes('css')) {
-      return {
-        ...rule,
-        use: [
-          'style-loader', // Inline CSS instead of separate files
-          'css-loader',
-        ],
-      };
-    }
-    return rule;
-  });
-
-  d365Config.module.rules = rules;
-
-  // Modify HTML plugin for D365
-  const htmlPluginIndex = d365Config.plugins.findIndex(
-    (plugin) => plugin.constructor.name === 'HtmlWebpackPlugin'
-  );
-
-  if (htmlPluginIndex !== -1) {
-    d365Config.plugins[htmlPluginIndex] = new (require('html-webpack-plugin'))({
-      template: './public/index.html',
-      filename: 'index.html',
-      inject: 'body',
-      // Inline all assets for single-file deployment
-      inlineSource: isDev ? false : '.(js|css)$',
-    });
-  }
-
-  // Add banner for D365 deployment info
-  d365Config.plugins.push(
-    new webpack.BannerPlugin({
-      banner: `
-Dynamics 365 Custom Page Bundle
-Built: ${new Date().toISOString()}
-Mode: ${mode}
-Environment: ${isDev ? 'Development' : 'Production'}
-Generated with Dynamics UI Kit
-      `.trim(),
-      raw: false,
-    })
-  );
-
-  // Add define plugin for environment variables
-  d365Config.plugins.push(
-    new webpack.DefinePlugin({
-      'process.env.NODE_ENV': JSON.stringify(mode),
-      'process.env.D365_BUILD': JSON.stringify(true),
-      'process.env.BUILD_MODE': JSON.stringify(mode),
-    })
-  );
-
-  return d365Config;
-}
-
-// Build function
-function build() {
-  const config = createD365WebpackConfig();
-
-  console.log('Starting D365-optimized build...');
-  console.log(`Output directory: ${config.output.path}`);
-  console.log(
-    `Bundle splitting: ${config.optimization.splitChunks ? 'enabled' : 'disabled'}`
-  );
-  console.log(`Minimization: ${config.optimization.minimize}`);
-
-  const compiler = webpack(config);
-
-  compiler.run((err, stats) => {
-    if (err) {
-      console.error('Build failed with error:', err);
-      process.exit(1);
-    }
-
-    if (stats.hasErrors()) {
-      console.error('Build completed with errors:');
-      console.error(
-        stats.toString({
-          colors: true,
-          chunks: false,
-          modules: false,
-          errorDetails: true,
-        })
-      );
-      process.exit(1);
-    }
-
-    if (stats.hasWarnings()) {
-      console.warn('Build completed with warnings:');
-      console.warn(
-        stats.toString({
-          colors: true,
-          chunks: false,
-          modules: false,
-          warningsFilter: /export.*was not found in/,
-        })
-      );
-    }
-
-    console.log('Build completed successfully!');
-    console.log(
-      stats.toString({
-        colors: true,
-        chunks: false,
-        modules: false,
-        assets: true,
-        performance: true,
-      })
-    );
-
-    // Generate deployment info
-    generateDeploymentInfo(stats, config);
-
-    compiler.close((closeErr) => {
-      if (closeErr) {
-        console.error('Error closing compiler:', closeErr);
-      }
-    });
-  });
-}
-
-// Generate deployment information file
-function generateDeploymentInfo(stats, config) {
-  const distPath = config.output.path;
-  const deploymentInfo = {
-    buildTime: new Date().toISOString(),
-    mode: config.mode,
-    isDevelopment: isDev,
-    assets: [],
-    entrypoints: {},
-    performance: {
-      totalSize: 0,
-      maxAssetSize: config.performance?.maxAssetSize || 'unlimited',
-      maxEntrypointSize: config.performance?.maxEntrypointSize || 'unlimited',
-    },
-    d365Integration: {
-      singleFileDeployment: !config.optimization.splitChunks,
-      webResourceReady: true,
-      customPageReady: true,
-      pcfReady: true,
-    },
-  };
-
-  const compilation = stats.compilation;
-
-  // Collect asset information
-  Object.keys(compilation.assets).forEach((assetName) => {
-    const asset = compilation.assets[assetName];
-    const assetInfo = {
-      name: assetName,
-      size: asset.size(),
-      type: path.extname(assetName) || 'unknown',
-    };
-    deploymentInfo.assets.push(assetInfo);
-    deploymentInfo.performance.totalSize += assetInfo.size;
-  });
-
-  // Collect entrypoint information
-  if (compilation.entrypoints) {
-    compilation.entrypoints.forEach((entrypoint, entryName) => {
-      const files = entrypoint.getFiles ? entrypoint.getFiles() : [];
-      deploymentInfo.entrypoints[entryName] = {
-        assets: files,
-        size: files.reduce((total, fileName) => {
-          const asset = compilation.assets[fileName];
-          return total + (asset ? asset.size() : 0);
-        }, 0),
-      };
-    });
-  }
-
-  // Write deployment info file
-  const deploymentInfoPath = path.join(distPath, 'deployment-info.json');
-  fs.writeFileSync(deploymentInfoPath, JSON.stringify(deploymentInfo, null, 2));
-
-  console.log('\n📋 Deployment Information:');
-  console.log(
-    `   Total bundle size: ${(deploymentInfo.performance.totalSize / 1024).toFixed(2)} KB`
-  );
-  console.log(`   Assets generated: ${deploymentInfo.assets.length}`);
-  console.log(`   Deployment info saved: ${deploymentInfoPath}`);
-
-  // D365 deployment recommendations
-  console.log('\n🚀 D365 Deployment Guidelines:');
-  console.log('   1. Upload JS files as Script (JScript) web resources');
-  console.log('   2. Upload CSS files as Style Sheet (CSS) web resources');
-  console.log('   3. Upload HTML file as Web Page (HTML) web resource');
-  console.log('   4. Set "Available for Dynamics 365 mobile" if needed');
-  console.log('   5. Publish all web resources after upload');
-
-  if (deploymentInfo.performance.totalSize > 1000000) {
-    console.log('\n⚠️  Warning: Bundle size is large (>1MB). Consider:');
-    console.log('   - Using code splitting for better performance');
-    console.log('   - Removing unused dependencies');
-    console.log('   - Enabling compression in D365');
-  }
-}
-
-// Start the build
-build();