| 1 | # Project Goal |
| 2 | |
| 3 | The goal of this project is to develop a comprehensive web component library for EVM blockchain applications. This library will provide reusable, vanilla JavaScript web components that enable developers to integrate blockchain functionality (such as wallet connections, transaction handling, contract interactions, and network management) into their web applications without dependencies on React or other frameworks. It aims to be a framework-agnostic alternative to libraries like wagmi, focusing on simplicity, performance, and broad compatibility. |
| 4 | |
| 5 | Key objectives: |
| 6 | - Provide a set of standardized web components for common EVM operations |
| 7 | - Ensure full TypeScript support for type safety |
| 8 | - Maintain browser compatibility across modern browsers |
| 9 | - Follow web component best practices and standards |
| 10 | - Include comprehensive documentation and examples |
| 11 | - Support both ESM and UMD module formats |
| 12 | |
| 13 | # Rules |
| 14 | |
| 15 | ## Development Rules |
| 16 | - Use vanilla JavaScript/TypeScript only; no React, Vue, or other framework dependencies |
| 17 | - All components must extend HTMLElement and follow the Custom Elements API |
| 18 | - Implement Shadow DOM for encapsulation where appropriate |
| 19 | - Use TypeScript for all source code to ensure type safety |
| 20 | - Follow semantic versioning (SemVer) for releases |
| 21 | - Write unit tests for all components using Bun's test runner |
| 22 | - Ensure all code passes linting with ESLint and type checking with TypeScript |
| 23 | |
| 24 | ## Code Quality Rules |
| 25 | - Follow the project's coding style (consistent indentation, naming conventions) |
| 26 | - Use meaningful variable and function names |
| 27 | - Add JSDoc comments for all public APIs |
| 28 | - Avoid global state; encapsulate state within components |
| 29 | - Handle errors gracefully and provide meaningful error messages |
| 30 | - Optimize for performance; minimize bundle size and runtime overhead |
| 31 | |
| 32 | ## Testing Rules |
| 33 | - Maintain test coverage above 80% for all components |
| 34 | - Write both unit tests and integration tests |
| 35 | - Test components in multiple browsers (Chrome, Firefox, Safari, Edge) |
| 36 | - Include tests for error scenarios and edge cases |
| 37 | - Run tests on every commit via CI/CD |
| 38 | |
| 39 | ## Contribution Rules |
| 40 | - All changes must be submitted via pull requests |
| 41 | - Include tests and documentation updates with new features |
| 42 | - Follow conventional commit messages |
| 43 | - Ensure backward compatibility unless breaking changes are explicitly planned |
| 44 | - Review and approve pull requests from at least one maintainer |
| 45 | |
| 46 | ## Security Rules |
| 47 | - Never expose private keys or sensitive data in code |
| 48 | - Validate all user inputs to prevent injection attacks |
| 49 | - Use secure random generation for any cryptographic operations |
| 50 | - Regularly audit dependencies for vulnerabilities |
| 51 | - Implement proper error handling to avoid information leakage |
| 52 | |
| 53 | ## Build and Deployment Rules |
| 54 | - Use Bun for building, testing, and running the project |
| 55 | - Generate both ESM and UMD bundles for distribution |
| 56 | - Minify production builds to reduce bundle size |
| 57 | - Publish to npm with proper package.json configuration |
| 58 | - Maintain a changelog for all releases |
| 59 | |
| 60 | ## Commands |
| 61 | - `bun run build`: Build the library for production |
| 62 | - `bun run dev`: Start development server with hot reload |
| 63 | - `bun test`: Run all tests |
| 64 | - `bun run lint`: Run ESLint for code quality checks |
| 65 | - `bun run typecheck`: Run TypeScript type checking |