Epic Flow Package Boilerplate 🏗️

This directory contains the boilerplate template for creating new packages in the Epic Flow monorepo. Use this as a starting point when creating new standalone packages.

📋 Package Structure Overview

Based on the @epic-flow/storage package, this boilerplate provides a complete, production-ready package structure following Epic Digital standards.

Directory Structure

packages/your-package-name/
├── 📄 README.md              # Package documentation
├── 📄 package.json           # Package configuration
├── 📄 tsconfig.json          # TypeScript configuration
├── 📄 tsup.config.ts         # Build configuration (tsup)
├── 📄 jest.config.js         # Test configuration
├── 📄 .gitignore             # Git ignore patterns
├── 📄 .eslintrc.js           # ESLint configuration
├── 📄 CONTRIBUTING.md        # Contribution guidelines
├── 📄 SECURITY.md            # Security policy
├── 📄 SUPPORT.md             # Support information
├── 📄 LICENSE.md             # License file
├── 📂 src/                   # Source code
│   ├── 📄 index.ts           # Main export file
│   ├── 📄 types.ts           # Type definitions
│   └── 📄 [your-modules].ts  # Implementation files
├── 📂 tests/                 # Test files
│   ├── 📄 *.test.ts          # Unit tests
│   └── 📄 *.integration.test.ts # Integration tests
└── 📂 dist/                  # Built output (auto-generated)

🚀 Quick Start

1. Copy Boilerplate

# Copy the boilerplate to create a new package
cp -r packages/_boilerplate packages/your-package-name

# Navigate to your new package
cd packages/your-package-name

2. Customize Package

• Update package.json with your package details
• Modify README.md with your package's purpose
• Implement your code in src/
• Add tests in tests/

3. Build and Test

# Install dependencies
yarn install

# Build the package
yarn build

# Run tests
yarn test

# Type check
yarn typecheck

📦 Package.json Template

The boilerplate includes a complete package.json with:

• Modern module exports (ESM + CommonJS)
• TypeScript configuration
• Build scripts (tsup)
• Testing setup (Jest)
• Development tools (ESLint, TypeScript)
• Proper file inclusion for npm publishing

🔧 Configuration Files

TypeScript (tsconfig.json)

• Strict mode enabled
• Modern ES2020 target
• Declaration files generated
• Source maps included

Build System (tsup.config.ts)

• Dual format output (ESM + CommonJS)
• Type declarations generated
• Source maps enabled
• Tree shaking enabled

Testing (jest.config.js)

• TypeScript support via ts-jest
• Coverage reporting enabled
• Module path mapping configured
• Test file patterns defined

Linting (.eslintrc.js)

• TypeScript ESLint rules
• Strict configuration for code quality
• Import/export validation

📚 Documentation Templates

The boilerplate includes complete documentation templates:

README.md

• Professional package description
• Installation instructions
• Usage examples
• API documentation
• Contributing guidelines

CONTRIBUTING.md

• Development setup instructions
• Coding standards
• Testing guidelines
• Pull request process

SECURITY.md

• Vulnerability reporting process
• Security best practices
• Contact information

SUPPORT.md

• Support channels
• Issue reporting guidelines
• Community resources

🏗️ Implementation Patterns

Source Structure (src/)

// src/index.ts - Main export file
export { YourMainClass } from './YourMainClass';
export { YourUtility } from './YourUtility';
export * from './types';

// src/types.ts - Type definitions
export interface YourInterface {
  id: string;
  name: string;
}

export type YourType = 'option1' | 'option2';

// src/YourMainClass.ts - Implementation
export class YourMainClass {
  // Implementation
}

Test Structure (tests/)

// tests/YourMainClass.test.ts - Unit tests
import { YourMainClass } from '../src';

describe('YourMainClass', () => {
  it('should work correctly', () => {
    // Test implementation
  });
});

// tests/integration.test.ts - Integration tests
describe('Integration Tests', () => {
  it('should integrate correctly', () => {
    // Integration test implementation
  });
});

🔄 Development Workflow

1. Development Setup

# Install dependencies
yarn install

# Start development mode (watch for changes)
yarn dev

# Run tests in watch mode
yarn test:watch

2. Code Quality

# Type checking
yarn typecheck

# Linting
yarn lint

# Run all tests
yarn test

3. Building for Production

# Clean previous build
yarn clean

# Build the package
yarn build

# Verify build output
ls -la dist/

📝 Naming Conventions

Package Names

• Use @epic-flow/ scope for all packages
• Use kebab-case: @epic-flow/your-package-name
• Be descriptive and clear about purpose

File Names

• Use PascalCase for classes: YourMainClass.ts
• Use camelCase for utilities: yourUtility.ts
• Use lowercase for types: types.ts
• Use descriptive test names: YourMainClass.test.ts

Export Patterns

• Export main functionality from index.ts
• Group related types in types.ts
• Use named exports for better tree-shaking
• Provide convenient re-exports

🧪 Testing Strategy

Test Types

1. Unit Tests - Test individual functions/classes
2. Integration Tests - Test component interactions
3. Type Tests - Validate TypeScript interfaces

Coverage Requirements

• Minimum 90% test coverage
• 100% coverage for critical paths
• Type safety validation
• Error handling tests

Test Structure

describe('FeatureName', () => {
  describe('methodName', () => {
    it('should handle normal case', () => {
      // Test implementation
    });

    it('should handle error case', () => {
      // Error test implementation
    });
  });
});

📚 Documentation Standards

README Requirements

• Clear package description
• Installation instructions
• Basic usage examples
• API reference
• Contributing guidelines

Code Documentation

• JSDoc comments for public APIs
• Type annotations for all functions
• Clear variable and function names
• Inline comments for complex logic

Example Documentation

/**
 * Processes data according to the specified configuration.
 *
 * @param data - The input data to process
 * @param config - Processing configuration options
 * @returns Promise resolving to processed data
 *
 * @example
 * ```typescript
 * const result = await processData({ id: '1' }, { validate: true });
 * console.log(result);
 * ```
 */
export async function processData(
  data: InputData,
  config: ProcessingConfig
): Promise<ProcessedData> {
  // Implementation
}

🔧 Advanced Configuration

Custom Build Options

Modify tsup.config.ts for specific needs:

export default defineConfig({
  entry: ['src/index.ts'],
  format: ['cjs', 'esm'],
  dts: true,
  external: ['your-external-deps'],
  // Add custom options here
});

Custom Jest Configuration

Extend jest.config.js for specific testing needs:

module.exports = {
  preset: 'ts-jest',
  // Add custom test configuration
  setupFilesAfterEnv: ['<rootDir>/tests/setup.ts'],
  globalSetup: '<rootDir>/tests/globalSetup.ts',
};

🚢 Publishing Checklist

Before publishing a new package:

• [ ] Package name is unique and follows conventions
• [ ] Version is set correctly in package.json
• [ ] Dependencies are minimal and necessary
• [ ] Tests pass with good coverage
• [ ] Documentation is complete and accurate
• [ ] Types are properly exported
• [ ] Build produces correct output
• [ ] License is set appropriately

🤝 Contributing

When contributing to packages:

1. Follow the boilerplate structure
2. Maintain coding standards
3. Add comprehensive tests
4. Update documentation
5. Ensure type safety

📞 Support

For questions about package development:

• Documentation: Check existing package examples
• Issues: Create GitHub issues for bugs
• Discussions: Use GitHub discussions for questions
• Team: Contact the development team

Happy coding! 🚀

This boilerplate ensures consistency, quality, and maintainability across all Epic Flow packages.