leptos-shadcn-ui/docs/contributing

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

• Leptos Documentation
• ShadCN UI Design System
• Rust Book
• Project Architecture

---

Happy Contributing! 🚀

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