Multi Crate Rust Template with xtask automation

This repository provides a template for starting robust, multi-crate Rust projects. It includes an xtask crate for automating common project tasks, and has served as the foundation for all my large Rust projects. The main features are:

• Pre-configured Cargo aliases: Shortcuts for common commands to speed up your workflow.
• Dependency budget: Enforces a maximum number of dependencies to help prevent bloat and keep your project maintainable.
• xtask crate: Contains custom scripts for managing your repository, including:
  • pre-commit: Runs formatting, linting, and tests before each commit.
  • install-hooks: Installs the pre-commit command as a Git hook for automatic checks.
• Strict Clippy settings: Ensures high code quality by catching more issues during linting.
• CONTRIBUTING.md for best practices and tips on writing high-quality Rust code.

This template is designed to help you start new Rust projects with best practices and automation already in place.

Setup

1. Clone the repository:

   git clone <repo-url>
   cd rust-template

2. Install git hooks (recommended):

   cargo x install-hooks

3. Update the project name:

   • Edit the Cargo.toml files and replace the package name with your project's name.

You're ready to start hacking!

Dependency Budget

Every dependency increases maintenance and security risk. To keep things manageable, this template enforces a "dependency budget" —a maximum number of unique (non-dev) dependencies allowed in the workspace.

• The budget is set in crates/xtask/src/cmds/core.rs as DEPENDENCY_BUDGET.
• Typical values:
  • Small projects: 100–150
  • Medium projects: 200–300
  • Large monorepos: 300–400 (higher only with strong justification)
• Lower budgets encourage careful selection and regular pruning of dependencies.
• Adjust the budget as the project grows, but review increases critically.

Best practices:

• Justify and document every new dependency in PRs.
• Prefer the standard library and well-maintained crates.
• Regularly remove unused or obsolete dependencies.

A disciplined dependency budget keeps the project lightweight, secure, and easy to maintain.

Cargo Aliases

The following cargo aliases are configured in .cargo/config.toml:

• cargo x - Run xtask commands
• cargo xp - Run xtask pre-commit checks
• cargo t - Run tests with nextest (default profile - unit tests only)
• cargo ti - Run integration tests with nextest
• cargo a - Run the main application binary

Testing with Nextest

This project uses nextest for running tests with different profiles configured in .config/nextest.toml:

Test Profiles

• default: Runs only unit tests (lib and bin tests), excludes integration tests

  cargo t  # or cargo nextest run

• vendor: Runs only unit tests for vendor packages

  cargo nextest run --profile vendor

  Note: You'll need to configure the filter in .config/nextest.toml to specify vendor packages, e.g., and (package(posthog) | package(openai))

• integration: Runs only integration tests

  cargo ti  # or cargo nextest run --profile integration

Limiting Tests to Specific Packages

To limit tests to vendor or non-vendor packages, modify the default-filter in the respective profile in .config/nextest.toml. Examples:

• To exclude vendor packages from default tests:

  default-filter = '(kind(lib) + kind(bin)) and not (package(posthog) | package(openai))'

• To run only vendor package tests:

  default-filter = '(kind(lib) + kind(bin)) and (package(posthog) | package(openai))'

Watch Mode for Rapid TDD

For rapid test-driven development, use cargo-watch to automatically run tests when files change:

# Install cargo-watch if not already installed
cargo install cargo-watch

# Watch and run tests on file changes
cargo watch -x t  # Runs unit tests (using the 't' alias)
cargo watch -x ti  # Runs integration tests (using the 'ti' alias)

# Watch with custom commands
cargo watch -x "nextest run --profile vendor"  # Run vendor tests on change
cargo watch -x check -x t  # Check compilation then run tests

# Watch specific paths
cargo watch -w src -x t  # Only watch src directory

# Clear screen before each run for better readability
cargo watch -c -x t