⚒️ Cargo-Forge

A powerful, interactive Rust project generator with intelligent templates and enterprise features

Generate production-ready Rust projects in seconds with intelligent templates, best practices, and optional features

🚀 Quick Start

# Install cargo-forge
cargo install cargo-forge

# Create a new project interactively
cargo forge new

# Or specify project type directly
cargo forge new my-api --project-type api-server

# Initialize in current directory
cargo forge init --project-type library

📖 Detailed Installation Guide - Including shell completions, pre-built binaries, and platform-specific instructions.

✨ Features

🎯 Project Types

Cargo-Forge supports 7 specialized project types, each with tailored templates and best practices:

🛠️ Optional Features

Enable powerful features during project creation:

CI/CD Integration

• GitHub Actions: Automated testing, releases, and deployment
• GitLab CI: Complete pipeline configuration with caching
• Custom CI: Template for other CI systems

Database Support

• PostgreSQL: SQLx integration with migrations
• MySQL: Full MySQL/MariaDB support
• SQLite: Embedded database with migrations

Authentication

• JWT: JSON Web Token authentication
• OAuth: OAuth2 with popular providers
• Password: Bcrypt-based password authentication

Additional Features

• Docker: Multi-stage Dockerfile and docker-compose
• Testing Frameworks: Property testing, benchmarks, integration tests
• Documentation: Auto-generated docs with examples
• Logging: Structured logging with tracing

📋 Comparison with cargo-generate

🎮 Usage Examples

Interactive Mode (Recommended)

$ cargo forge new
⚒️ Welcome to Cargo-Forge!
? What's your project name? › my-awesome-api
? Select project type › API Server
? Add authentication? › JWT
? Include database? › PostgreSQL
? Add Docker support? › Yes
? Setup CI/CD? › GitHub Actions

✨ Project created successfully at ./my-awesome-api

Command-Line Mode

# Create an API server with PostgreSQL and JWT auth
cargo forge new my-api \
  --project-type api-server \
  --author "Jane Doe" \
  --description "My awesome API"

# Create a CLI tool in non-interactive mode (great for CI)
cargo forge new my-cli \
  --project-type cli-tool \
  --non-interactive

# Initialize a library in current directory
cargo forge init --project-type library

# Dry run to preview what will be created
cargo forge new my-project --dry-run

# Use saved configuration
cargo forge new my-project --from-config ~/.forge/defaults.toml

Advanced Usage

# Create a workspace with multiple crates
cargo forge new my-workspace --project-type workspace

# Generate a game with Bevy engine
cargo forge new my-game --project-type game-engine

# Create an embedded project for STM32
cargo forge new my-firmware --project-type embedded

📁 Generated Project Structure

Example: API Server

my-api/
├── src/
│   ├── main.rs           # Application entry point
│   ├── routes/           # HTTP route handlers
│   │   ├── mod.rs
│   │   ├── health.rs
│   │   └── users.rs
│   ├── models/           # Data models
│   │   ├── mod.rs
│   │   └── user.rs
│   ├── middleware/       # HTTP middleware
│   │   ├── mod.rs
│   │   └── auth.rs
│   └── utils/            # Utility functions
│       ├── mod.rs
│       └── config.rs
├── migrations/           # Database migrations
│   └── 001_initial.sql
├── tests/                # Integration tests
│   └── api_tests.rs
├── .github/              # GitHub Actions CI
│   └── workflows/
│       └── ci.yml
├── Dockerfile            # Multi-stage Docker build
├── docker-compose.yml    # Local development setup
├── .env.example          # Environment variables template
├── Cargo.toml            # Project manifest
└── README.md             # Project documentation

🔧 Configuration

Global Configuration

Save your preferences for future projects:

# ~/.config/cargo-forge/config.toml
[defaults]
author = "Your Name"
license = "MIT OR Apache-2.0"
vcs = "git"

[preferences]
always_add_ci = true
default_ci = "github"
prefer_workspace = false

Project Configuration

Each project type supports specific configuration:

# forge.toml in your project
[project]
type = "api-server"
features = ["database", "auth", "docker"]

[database]
type = "postgresql"
migrations_dir = "./migrations"

[auth]
type = "jwt"
expires_in = "24h"

📊 Template Syntax

Cargo-Forge uses Tera templates with custom helpers:

// Conditional compilation based on features
{% if database %}
use sqlx::{PgPool, postgres::PgPoolOptions};
{% endif %}

// Smart defaults with fallbacks
const PORT: u16 = {{ port | default(value=3000) }};

// Case transformations
mod {{ name | snake_case }};
struct {{ name | pascal_case }};

// Feature combinations
{% if auth and database %}
// Authentication with database backend
{% endif %}

🧪 Testing

Generated projects include comprehensive test setups:

# Run all tests
cargo test

# Run with coverage
cargo tarpaulin

# Benchmarks (if enabled)
cargo bench

# Property tests (if enabled)
cargo test --features proptest

🚢 CI/CD Integration

All project types can include CI/CD configuration:

GitHub Actions

• Multi-platform testing (Windows, Mac, Linux)
• Rust version matrix (stable, beta, nightly)
• Security audits and dependency checks
• Release automation with cargo-release
• Code coverage with Codecov

GitLab CI

• Cached dependencies for faster builds
• Parallel job execution
• Deploy stages for different environments
• Container registry integration

🐳 Docker Support

Generated Dockerfiles use multi-stage builds for optimal image size:

# Build stage
FROM rust:1.70 as builder
WORKDIR /app
COPY . .
RUN cargo build --release

# Runtime stage
FROM debian:bookworm-slim
COPY --from=builder /app/target/release/app /usr/local/bin/
CMD ["app"]

🔒 Security

Cargo-Forge follows security best practices:

• No hardcoded secrets in templates
• Secure default configurations
• Environment variable usage for sensitive data
• Security audit integration in CI
• OWASP compliance for web projects

🤝 Contributing

We love contributions! See CONTRIBUTING.md for guidelines.

Development Setup

# Clone the repository
git clone https://github.com/yourusername/cargo-forge
cd cargo-forge

# Run tests
cargo test

# Run with coverage
cargo tarpaulin

# Build for release
cargo build --release

📈 Performance

Cargo-Forge is optimized for speed:

• Project generation: ~1.5 seconds
• Template rendering: <100ms
• Feature validation: <50ms
• Cross-platform: Works on Windows, Mac, and Linux

🐛 Troubleshooting

Common Issues

Q: Command not found after installation

# Ensure cargo bin directory is in PATH
export PATH="$HOME/.cargo/bin:$PATH"

Q: Permission denied errors

# Check directory permissions
ls -la .
# Use sudo if needed (not recommended)

Q: Template rendering fails

# Validate your input
cargo forge new --dry-run
# Check for special characters in project name

Getting Help

• 📖 Documentation
• 💬 Discord Community (coming soon)
• 🐛 Issue Tracker
• 📧 Email Support (coming soon)

📚 Documentation

• Quick Reference - Command cheat sheet and quick examples
• Project Types Guide - Detailed guide for each project type
• Template Syntax - Tera template documentation
• FAQ - Frequently asked questions
• Troubleshooting - Common issues and solutions
• Contributing - Development guidelines
• Changelog - Version history and roadmap

📜 License

Licensed under either of:

• Apache License, Version 2.0 (LICENSE-APACHE)
• MIT license (LICENSE-MIT)

at your option.

🙏 Acknowledgments

• The Rust community for invaluable feedback
• Contributors who help make Cargo-Forge better
• Projects that inspired us: cargo-generate, create-react-app, Rails generators

Built with ❤️ by the Rust community

Documentation • Crates.io