📘 cargo-setupx

Automate Rust project setup with modular configuration packs

A Rust-based CLI and library that automates the initial setup of new Rust projects. Provides modular configuration packs that can be selectively applied to standardize development environments.

🎯 Features

• Quality Pack - Code quality configuration files

  • rustfmt.toml - Code formatting rules
  • clippy.toml - Linting configuration
  • _typos.toml - Spell checking setup
  • Makefile - Common development commands

• Hooks Pack - Git hooks for automated quality checks

  • .githooks/pre-push - Pre-push quality gate
  • .githooks/setup.sh - Hooks installation script
  • Configures core.hooksPath automatically

• Architecture Pack - Project structure scaffolding

  • Clean Architecture (domain, application, infrastructure, presentation)
  • Additional patterns planned (hexagonal, onion - see Roadmap)

📦 Installation

cargo install cargo-setupx

Or install from source:

git clone https://github.com/ricardoferreirades/cargo-setupx.git
cd cargo-setupx
cargo install --path .

🚀 Quick Start

Apply All Packs

# In your Rust project directory
cargo setupx --all

Apply Specific Packs

# Quality pack only
cargo setupx --quality

# Hooks pack only
cargo setupx --hooks

# Architecture pack (clean)
cargo setupx --arch=clean

# Quality + Hooks
cargo setupx --quality --hooks

Force Overwrite

# Overwrite existing files
cargo setupx --all --force

# Skip confirmation prompt
cargo setupx --all --yes

📖 Usage

As a Cargo Subcommand

# Show help
cargo setupx --help

# Apply to current directory
cargo setupx --quality --hooks

# Apply to specific directory
cargo setupx --all /path/to/project

# Force overwrite with no prompts
cargo setupx --all --force --yes

As a Library

use cargo_setupx::{Config, apply_packs};
use std::path::Path;

let config = Config {
    quality: true,
    hooks: true,
    arch: Some("clean".to_string()),
    force: false,
    yes: false,
};

apply_packs(&config, Path::new(".")).expect("Failed to apply packs");

📋 What Gets Created

Quality Pack (--quality)

Creates the following files in your project root:

clippy.toml       # Clippy linter configuration
rustfmt.toml      # Rustfmt formatter settings
_typos.toml       # Typos spell checker config
Makefile          # Development commands

Makefile commands:

• make fmt - Format code (cargo fmt + taplo)
• make lint - Run clippy linter
• make lint-fix - Auto-fix linting issues
• make check - Type check without building
• make spell - Check spelling
• make spell-fix - Auto-fix spelling errors
• make quality - Run all quality checks
• make test - Run tests
• make run - Run the application

Hooks Pack (--hooks)

Creates Git hooks for automated quality checks:

.githooks/
├── pre-push       # Pre-push quality gate (executable)
├── setup.sh       # Hook installation script (executable)
└── README.md      # Hooks documentation

The pre-push hook runs:

1. ✅ Code formatting check (cargo fmt --check)
2. ✅ TOML formatting check (taplo format --check)
3. ✅ Linting (cargo clippy -- -D warnings)
4. ✅ Spell check (typos)
5. ✅ Type check (cargo check)
6. ✅ Tests (cargo test)

Push is blocked if any check fails!

Architecture Pack (--arch=clean)

Note: Currently only Clean Architecture is supported. Other patterns (hexagonal, onion) are planned.

Creates Clean Architecture folder structure:

src/
├── domain/
│   ├── entities/
│   ├── repositories/
│   └── services/
├── application/
│   ├── dto/
│   └── use_cases/
├── infrastructure/
│   ├── database/
│   ├── config/
│   └── http/
└── presentation/
    └── handlers/

Each directory includes:

• mod.rs with documentation
• Stub files for quick start

🔧 Prerequisites

For full functionality, install these tools:

# Taplo (TOML formatter)
cargo install taplo-cli

# Typos (spell checker)
cargo install typos-cli

🛠️ Development Workflow

After running cargo setupx --all, use these commands:

# Initial setup
make setup-hooks    # Configure git hooks

# Daily development
make quality        # Run all checks
make fmt           # Format code
make lint-fix      # Fix linting issues
make spell-fix     # Fix spelling

# Testing
make test          # Run tests
make check         # Quick type check

# Building
make build         # Build release
make clean         # Clean artifacts

⚙️ Configuration

Idempotent Setup

Running cargo setupx multiple times is safe. It will:

• Skip existing files (unless --force is used)
• Show clear status messages (Created, Skipped, Overwrote)
• Never corrupt existing files

Force Overwrite

Use --force to overwrite existing files:

cargo setupx --all --force

Skip Confirmation

Use --yes to skip confirmation prompts:

cargo setupx --all --yes

🎨 Examples

New Project Setup

# Create new Rust project
cargo new my-awesome-project
cd my-awesome-project

# Apply all packs
cargo setupx --all

# Setup git hooks
make setup-hooks

# Verify everything works
make quality

Existing Project Setup

# In your existing project
cd my-existing-project

# Apply quality + hooks (no architecture changes)
cargo setupx --quality --hooks --yes

# Setup hooks
make setup-hooks

Library Project

# Create library
cargo new --lib my-library
cd my-library

# Apply quality pack + clean architecture
cargo setupx --quality --arch=clean

# Verify
make quality

🧪 Testing

Run the test suite:

cargo test

Run specific tests:

cargo test quality
cargo test hooks
cargo test architecture

📚 Documentation

Generate and open documentation:

cargo doc --open

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feat/amazing-feature)
3. Make your changes
4. Run quality checks (make quality)
5. Commit your changes (git commit -m 'feat: add amazing feature')
6. Push to the branch (git push origin feat/amazing-feature)
7. Open a Pull Request

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Inspired by the need for consistent Rust project setups
• Built with Clap for CLI parsing
• Quality tools: Clippy, Rustfmt, Typos

🔗 Links

• Repository
• Issue Tracker
• Documentation

🚧 Roadmap

• Support for hexagonal architecture
• Support for onion architecture
• Custom pack definitions via .setupx.toml
• CI/CD configuration packs (GitHub Actions, GitLab CI)
• Docker configuration pack
• Plugin system for community packs
• Interactive mode for pack selection

Made with ❤️ by Ricardo Ferreira