An interactive Rust project generator with templates and common features
Generate Rust projects with templates and optional features
# 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.
Cargo-Forge supports 7 project types with templates:
| Type | Description | Key Features |
|---|---|---|
| cli-tool | Command-line applications | • Clap dependency setup • Basic project structure • Ready for CLI development |
| library | Rust library crates | • Library template • Examples directory • Documentation ready • Tests structure |
| api-server | REST API servers | • Axum web framework • Basic HTTP server setup • Route handlers structure • Ready for API development |
| wasm-app | WebAssembly applications | • wasm-bindgen setup • Web-sys integration • Build scripts • HTML template |
| game-engine | Game development | • Bevy engine • Asset pipeline structure • Basic game setup • Development ready |
| embedded | Embedded systems | • no_std setup • Memory configuration • HAL integration • Debug configs |
| workspace | Multi-crate projects | • Organized structure • Shared dependencies • Cross-crate testing • Unified configuration |
Current features available in v0.1.3:
- Clean Templates: Well-organized project structures for each type
- Dependency Management: Appropriate dependencies for each project type
- Documentation: README files with project-specific instructions
- Testing Setup: Basic test structure and configuration
- Dry Run Mode: Preview project structure before creation
- Non-interactive Mode: CI-friendly project generation
- Name Validation: Ensures valid Cargo package names
- Shell Completions: Bash, zsh, fish, and PowerShell support
- CI/CD Integration: GitHub Actions and GitLab CI templates
- Database Support: PostgreSQL, MySQL, and SQLite integration
- Authentication: JWT, OAuth, and password authentication
- Docker: Multi-stage Dockerfile and docker-compose setup
- Advanced Templates: Feature-rich project templates
| Feature | cargo-forge | cargo-generate |
|---|---|---|
| Interactive Mode | ❌ Planned for future | ❌ Requires manual input |
| Project Types | ✅ 7 specialized types | |
| Defaults | ✅ Pre-configured options | ❌ Manual configuration |
| Name Validation | ✅ Built-in validation | |
| Dry Run Mode | ✅ Preview before creation | ❌ Not available |
| Non-interactive Mode | ✅ CI-friendly with defaults | ✅ Available |
| Custom Templates | ✅ Tera templates | ✅ Various engines |
| Shell Completions | ✅ All major shells | |
| Error Recovery | ✅ Graceful handling | |
| Performance | ✅ <0.1s generation |
# 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# 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 embeddedmy-api/
├── src/
│ ├── main.rs # Application entry point
│ ├── handlers.rs # HTTP handlers (basic structure)
│ ├── routes.rs # Route definitions (basic structure)
│ └── models.rs # Data models (basic structure)
├── config/
│ └── default.toml # Configuration template
├── tests/ # Test directory
├── .gitignore # Git ignore file
├── Cargo.toml # Project manifest with Axum dependencies
└── README.md # Project documentation
Cargo-Forge supports various command-line options:
# Non-interactive mode (great for CI/CD)
cargo-forge new my-project --project-type api-server --non-interactive
# Dry run to preview what will be created
cargo-forge new my-project --project-type library --dry-run
# Initialize in current directory
cargo-forge init --project-type cli-toolAfter project creation, you can customize:
- Add dependencies to
Cargo.toml - Modify source files to fit your needs
- Update configuration files as needed
- Add additional features and integrations
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 %}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 proptestAll project types can include CI/CD configuration:
- 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
- Cached dependencies for faster builds
- Parallel job execution
- Deploy stages for different environments
- Container registry integration
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"]Cargo-Forge security features:
- No hardcoded secrets in templates
- Secure default configurations
- Environment variable usage for sensitive data
- Security audit integration in CI
- OWASP compliance for web projects
We love contributions! See CONTRIBUTING.md for guidelines.
# 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 --releaseCargo-Forge is optimized for speed:
- Project generation: <0.1 seconds (extremely fast!)
- Template rendering: <10ms
- Name validation: <1ms
- Cross-platform: Works on Windows, Mac, and Linux
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- 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
Licensed under either of:
- Apache License, Version 2.0 (LICENSE-APACHE)
- MIT license (LICENSE-MIT)
at your option.
- The Rust community for feedback
- Contributors who help make Cargo-Forge better
- Similar projects: cargo-generate, create-react-app
Built with ❤️ by the Rust community