More on CodeGen

Best Practices

CodeGen Configuration Management

• Store CodeGen configuration in version control
• Use environment variables for sensitive information
• Create different configurations for development, staging, and production
• Document custom templates and configurations

Generation Workflow

• Run CodeGen as part of your build process
• Validate generated code with linting
• Include tests for custom generators
• Keep custom templates simple and focused

Working with Generated Code

• Avoid manual edits to generated files
• Use custom subclasses for specialized behavior
• Regenerate code after metadata changes
• Use source control to track changes to generated code

Troubleshooting

Common Issues and Solutions

Generation Fails with Type Errors

Issue: Code generation fails with TypeScript errors.

Solution:

1. Check that your template syntax is correct
2. Ensure type imports are properly defined
3. Verify the metadata structure matches template expectations
4. Examine template output for syntax errors

Missing Navigation Properties

Issue: Generated entity classes don't include navigation properties.

Solution:

1. Ensure relationships are defined in the metadata
2. Check that includeNavigationProperties option is enabled
3. Verify that relationship target entities exist
4. Check custom templates for navigation property handling

Performance Issues with Large Schemas

Issue: Code generation is slow with large database schemas.

Solution:

1. Use selective generation with includeEntities option
2. Filter out unused entities with entityFilter
3. Split generation into multiple steps
4. Optimize templates for performance

Template Rendering Errors

Issue: Template rendering fails or produces incorrect output.

Solution:

1. Check template syntax for errors
2. Verify template variable usage
3. Add debug logging to templates
4. Examine the context data being passed to templates

Other Tips and Tricks

1. Version Control: Include generated code in version control
2. Separate Branches: Use separate branches for regenerating code
3. Diff Review: Carefully review changes in generated code
4. Incremental Generation: Use incremental generation for large schemas
5. Template Optimization: Optimize templates for large projects
6. Custom Extensions: Use subclassing pattern to extend generated code
7. Template Reuse: Share templates across projects for consistency
8. Documentation: Document custom templates and plugins
9. Testing: Write tests for custom templates and plugins
10. Configuration Management: Manage configuration files in version control

Be on the Look Out For

1. Missing Metadata: Ensure your database schema is properly defined
2. Template Errors: Verify custom templates are correctly formatted
3. Type Mapping Issues: Check type mappings for unusual data types
4. Naming Conflicts: Watch for potential naming conflicts between entities
5. Path Issues: Ensure output paths exist and are writable
6. Database Connectivity: Verify database connection settings
7. Plugin Errors: Debug plugin code with detailed logging

Logging and Diagnostics

Enable detailed logging for troubleshooting:

# Enable verbose logging
npx mj-codegen --verbose --config ./codegen-config.json

# Output logs to file
npx mj-codegen --log ./codegen.log --config ./codegen-config.json

Advanced Topics

Incremental Generation

For large projects, incremental generation can improve performance:

import { IncrementalCodeGenerator } from '@memberjunction/codegen';

// Configure incremental generation
const generator = new IncrementalCodeGenerator({
  outputPath: './src/generated',
  cacheDirectory: './.codegen-cache',
  onlyGenerateChanged: true
});

generator.generate().then(() => {
  console.log('Incremental code generation completed successfully');
});

Multi-Language Generation

The CodeGen system can generate code in multiple languages:

import { MultiLanguageGenerator } from '@memberjunction/codegen';

// Configure multi-language generation
const generator = new MultiLanguageGenerator({
  outputPath: './src/generated',
  languages: ['typescript', 'csharp', 'java'],
  languageTemplates: {
    typescript: './templates/typescript',
    csharp: './templates/csharp',
    java: './templates/java'
  }
});

generator.generate().then(() => {
  console.log('Multi-language code generation completed successfully');
});

Integration with Build Systems

The CodeGen system can be integrated with various build systems:

Webpack Integration

// webpack.config.js
const { CodeGenWebpackPlugin } = require('@memberjunction/codegen/webpack');

module.exports = {
  // Webpack configuration
  plugins: [
    new CodeGenWebpackPlugin({
      configFile: './codegen.config.js',
      watch: true // Regenerate code when metadata changes
    })
  ]
};

Gulp Integration

// gulpfile.js
const gulp = require('gulp');
const { CodeGenGulpTask } = require('@memberjunction/codegen/gulp');

gulp.task('codegen', CodeGenGulpTask({
  configFile: './codegen.config.js'
}));

gulp.task('build', gulp.series('codegen', 'tsc'));

Custom Plugins

The CodeGen system supports plugins for extending functionality:

import { CodeGenerator, CodeGenPlugin } from '@memberjunction/codegen';

// Create a custom plugin
class DocumentationPlugin implements CodeGenPlugin {
  name = 'DocumentationPlugin';
  
  // Called before generation starts
  async beforeGeneration(generator: CodeGenerator): Promise<void> {
    console.log('Documentation generation starting');
  }
  
  // Called for each entity
  async processEntity(entity: any, generator: CodeGenerator): Promise<void> {
    // Generate documentation for the entity
    const documentation = await this.generateDocumentation(entity);
    
    // Write the documentation to a file
    await generator.writeFile(
      `${generator.options.outputPath}/docs/${entity.name}.md`,
      documentation
    );
  }
  
  // Called after generation completes
  async afterGeneration(generator: CodeGenerator): Promise<void> {
    console.log('Documentation generation completed');
  }
  
  private async generateDocumentation(entity: any): Promise<string> {
    // Custom documentation generation logic
    return `# ${entity.displayName}\n\n${entity.description || ''}`;
  }
}

// Use the plugin with the code generator
const generator = new CodeGenerator({
  outputPath: './src/generated',
  plugins: [
    new DocumentationPlugin()
  ]
});

generator.generate().then(() => {
  console.log('Code generation with plugins completed successfully');
});