Skip to content

README.md

Latest commit

 

History

History
228 lines (171 loc) · 5.77 KB

README.md

File metadata and controls

228 lines (171 loc) · 5.77 KB
Raw

Contributing to Leptos ShadCN UI

Welcome to the Leptos ShadCN UI project! This guide will help you get started as a contributor.

🚀 Quick Start for Contributors

Prerequisites

  • Rust 1.75+ with Cargo
  • Node.js 18+ (for frontend tooling)
  • Git for version control
  • Basic knowledge of Leptos v0.8+ and Rust

1. Clone and Setup

# Clone the repository
git clone https://github.com/cloud-shuttle/leptos-shadcn-ui.git
cd leptos-shadcn-ui

# Install dependencies
cargo build --workspace

# Verify setup with TDD tests
cargo nextest run --package leptos-shadcn-contract-testing

2. Development Workflow

TDD-First Development

This project follows Test-Driven Development (TDD) principles:

# 1. Run contract tests before making changes
cargo nextest run --package leptos-shadcn-contract-testing

# 2. Make your changes
# 3. Run tests again to ensure nothing broke
cargo nextest run --package leptos-shadcn-contract-testing

# 4. Run full workspace check
cargo check --workspace

Component Development

# Test individual component
cargo build --package leptos-shadcn-button

# Test main package with specific features
cargo build --package leptos-shadcn-ui --features button,input,card,dialog

3. Project Structure

leptos-shadcn-ui/
├── packages/
│   ├── leptos/              # Individual component packages
│   │   ├── button/          # Button component
│   │   ├── input/           # Input component
│   │   └── ...
│   ├── contract-testing/    # TDD framework
│   ├── signal-management/   # Signal lifecycle management
│   └── tailwind-rs-core/    # Type-safe Tailwind CSS
├── examples/leptos/         # Example applications
├── docs/                    # Documentation
└── scripts/                 # Automation scripts

4. Adding New Components

Step 1: Create Component Package

# Use the component generator
cargo run --package leptos-shadcn-component-generator -- --name my-component

Step 2: Implement TDD Tests

// In your component's tests/
#[cfg(test)]
mod tests {
    use super::*;
    use leptos_shadcn_contract_testing::*;

    #[test]
    fn test_component_contracts() {
        let tester = ContractTester::new();
        tester.validate_component_contracts("my-component");
    }
}

Step 3: Update Workspace

Add your component to Cargo.toml workspace members and dependencies.

5. Performance Requirements

All components must meet these performance contracts:

  • Bundle Size: < 500KB per component
  • Render Time: < 16ms initial render
  • WASM Compatibility: Full compatibility with WebAssembly targets
# Validate performance contracts
cargo run --package leptos-shadcn-contract-testing --bin validate_performance

6. Code Quality Standards

Rust Standards

  • Use cargo fmt for formatting
  • Use cargo clippy for linting
  • Follow Rust naming conventions
  • Document all public APIs

Component Standards

  • Implement both default and new_york variants
  • Include comprehensive prop documentation
  • Support signal-based state management
  • Include accessibility features

7. Testing Strategy

Contract Testing

# Run all contract tests
cargo nextest run --package leptos-shadcn-contract-testing

# Run specific test categories
cargo nextest run --package leptos-shadcn-contract-testing --test-threads 1

Integration Testing

# Test example applications
cd examples/leptos
cargo run

8. Dependency Management

Automated Dependency Fixing

# Fix dependency issues automatically
cargo run --package leptos-shadcn-contract-testing --bin fix_dependencies

Version Consistency

All packages must use version 0.8.0 and workspace dependencies.

9. Pull Request Process

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/my-feature
  3. Implement your changes with tests
  4. Run the full test suite: cargo nextest run --workspace
  5. Update documentation if needed
  6. Submit a pull request with a clear description

10. Common Issues and Solutions

Build Failures

# Clean and rebuild
cargo clean
cargo build --workspace

# Check for dependency issues
cargo run --package leptos-shadcn-contract-testing --bin fix_dependencies

Test Failures

# Run tests with verbose output
cargo nextest run --package leptos-shadcn-contract-testing -- --nocapture

# Check specific test
cargo test --package leptos-shadcn-contract-testing test_name

Performance Issues

# Profile bundle size
cargo run --package leptos-shadcn-contract-testing --bin profile_bundle_size

# Check render performance
cargo run --package leptos-shadcn-contract-testing --bin profile_render_time

11. Getting Help

  • Documentation: Check docs/ directory
  • Issues: Open a GitHub issue
  • Discussions: Use GitHub Discussions
  • Examples: Look at examples/leptos/ for usage patterns

12. Release Process

Releases are automated through CI/CD. To trigger a release:

  1. Update version numbers in Cargo.toml
  2. Update CHANGELOG.md
  3. Create a release tag
  4. CI/CD will handle publishing

🎯 Development Goals

  • Quality: Maintain 100% test pass rate
  • Performance: Meet all performance contracts
  • Compatibility: Full Leptos v0.8+ compatibility
  • Documentation: Comprehensive API documentation
  • Accessibility: WCAG 2.1 AA compliance

📚 Additional Resources

Happy Contributing! 🚀

For questions or support, please open an issue or start a discussion.