Skip to main content

Plugin Best Practices

This guide outlines best practices for developing x-fidelity plugins.

Design Principles​

1. Single Responsibility​

Each plugin should:

  • Have a clear, focused purpose
  • Avoid feature overlap with other plugins
  • Be self-contained
  • Have minimal dependencies

2. Error Handling​

Implement robust error handling:

onError: (error) => ({
    message: `Plugin error: ${error.message}`,
    level: 'warning',
    details: {
        stack: error.stack,
        code: error.code,
        context: error.context
    }
})

3. Performance​

Optimize performance:

  • Cache expensive operations
  • Use async/await properly
  • Implement timeouts
  • Handle rate limits

4. Security​

Follow security best practices:

  • Validate all inputs
  • Sanitize file paths
  • Handle sensitive data carefully
  • Use secure dependencies

Implementation Guidelines​

1. Naming Conventions​

Follow consistent naming:

  • Package names: xfi-*
  • Facts: customFact
  • Operators: customOperator
  • Rules: customRule-[global|iterative]

2. Documentation​

Include comprehensive documentation:

  • README.md
  • JSDoc comments
  • Usage examples
  • API documentation
  • Changelog

3. Testing​

Write thorough tests:

describe('plugin', () => {
    it('should handle valid inputs', async () => {
        // Test normal operation
    });

    it('should handle invalid inputs', async () => {
        // Test error cases
    });

    it('should handle edge cases', async () => {
        // Test boundaries
    });
});

4. Version Management​

Follow semantic versioning:

  • MAJOR: Breaking changes
  • MINOR: New features
  • PATCH: Bug fixes

Code Organization​

1. Project Structure​

my-plugin/
├── src/
│   ├── facts/
│   ├── operators/
│   └── index.ts
├── test/
├── examples/
└── package.json

2. Type Definitions​

Use TypeScript for better type safety:

interface CustomFact extends FactDefn {
    name: string;
    fn: (params: CustomParams) => Promise<CustomResult>;
}

3. Configuration​

Make plugins configurable:

const plugin = {
    name: 'my-plugin',
    version: '1.0.0',
    config: {
        timeout: 5000,
        retries: 3
    }
};

Integration Guidelines​

1. Dependency Management​

Handle dependencies properly:

{
    "peerDependencies": {
        "x-fidelity": "^3.0.0"
    },
    "devDependencies": {
        "typescript": "^5.0.0",
        "jest": "^29.0.0"
    }
}

2. Error Propagation​

Propagate errors appropriately:

try {
    // Plugin operation
} catch (error) {
    throw new PluginError({
        message: 'Operation failed',
        level: 'error',
        details: error
    });
}

3. Logging​

Use consistent logging:

import { logger } from 'x-fidelity';

logger.info('Plugin operation started');
logger.error('Plugin operation failed', error);

Publishing Guidelines​

1. Package Preparation​

Prepare for publishing:

{
    "name": "xfi-my-plugin",
    "version": "1.0.0",
    "main": "dist/index.js",
    "types": "dist/index.d.ts",
    "files": [
        "dist",
        "README.md",
        "LICENSE"
    ]
}

2. Quality Checks​

Run quality checks:

# Lint code
yarn lint

# Run tests
yarn test

# Build package
yarn build

# Check package contents
yarn pack

3. Documentation​

Include usage documentation:

## Installation
```bash
yarn add xfi-my-plugin

Usage​

xfidelity . -e xfi-my-plugin

## Common Pitfalls

1. **Tight Coupling**: Avoid depending on internal x-fidelity implementation details
2. **Poor Error Handling**: Always handle errors appropriately
3. **Missing Documentation**: Document all features and configurations
4. **Insufficient Testing**: Test all functionality including edge cases
5. **Version Conflicts**: Manage peer dependencies correctly

## Next Steps

- Review the [Plugin Examples](plugin-examples)
- Create your own plugin
- Contribute to existing plugins