Skip to main content

Building FasCraft: My Journey Creating a FastAPI Project Generator CLI Tool

· 5 min read
Lex Lutor Iyornumbe
Lex Lutor Iyornumbe
Senior Software Developer @ Punch Agency

The Problem That Started It All​

As a developer who has worked on numerous FastAPI projects, I noticed a frustrating pattern: teams spending significant time setting up project structure and boilerplate code instead of focusing on business logic. Every new project meant:

  • Manually creating the same folder structure
  • Setting up database configurations
  • Configuring environment variables
  • Writing boilerplate models, schemas, and services
  • Setting up testing frameworks
  • Configuring CI/CD pipelines

This repetitive setup was eating into development time and often led to inconsistent project structures across teams.

The Solution: FasCraft 🚀​

I decided to build a CLI tool that would eliminate this boilerplate work. The result was FasCraft - a powerful command-line interface for generating modular FastAPI projects with domain-driven architecture.

What Makes FasCraft Special​

FasCraft isn't just another project generator. It's designed with several key principles:

  • 🚀 Zero Configuration: Gets you from idea to running API in seconds
  • 🏗️ Domain-Driven Design: Enforces clean architecture from day one
  • 🛡️ Safety First: Built-in confirmations, backups, and rollback capabilities
  • 🎨 Beautiful UX: Rich terminal output with progress indicators and color coding
  • 🧪 Production Ready: Comprehensive testing and error handling built-in

The Technology Stack​

Building a CLI tool requires careful consideration of the user experience. Here's what I chose and why:

Core Framework: Typer​

import typer

app = typer.Typer()

@app.command()
def new(project_name: str):
    """Create a new FastAPI project"""
    # Implementation here

Why Typer? It's built on top of Click but with modern Python type hints, making the code more maintainable and self-documenting.

Terminal Output: Rich​

from rich.console import Console
from rich.table import Table
from rich.progress import Progress

console = Console()

Why Rich? It provides beautiful tables, progress bars, and syntax highlighting that make the CLI feel professional and user-friendly.

Templating: Jinja2​

from jinja2 import Environment, FileSystemLoader

env = Environment(loader=FileSystemLoader('templates'))
template = env.get_template('main.py.j2')

Why Jinja2? It's powerful, well-documented, and perfect for generating code files with dynamic content.

Key Features That Developers Love​

1. Project Generation​

fascraft new my-awesome-api

This single command creates a complete FastAPI project with:

  • Domain-driven folder structure
  • Pre-configured database settings
  • Environment variable templates
  • Testing framework setup
  • CI/CD pipeline configuration

2. Module Management​

fascraft generate customers
fascraft generate products

Each module comes with:

  • SQLAlchemy models
  • Pydantic schemas
  • Business logic services
  • FastAPI routers
  • Comprehensive tests

3. Smart Configuration​

FasCraft automatically detects your project structure and provides intelligent defaults while allowing customization.

The Development Journey​

Phase 1: Core Functionality​

Started with basic project generation and simple templating. The goal was to get something working quickly.

Phase 2: User Experience​

Added progress indicators, beautiful tables, and comprehensive error handling. This is where Rich really shined.

Phase 3: Safety Features​

Implemented backup systems, rollback capabilities, and confirmation prompts to prevent accidental data loss.

Phase 4: Testing & Documentation​

Comprehensive test coverage and detailed documentation to ensure reliability.

Challenges and Lessons Learned​

1. Cross-Platform Compatibility​

Windows, macOS, and Linux handle paths differently. Solution: Use pathlib for consistent path handling.

2. Template Management​

Managing multiple template files while keeping them maintainable. Solution: Organized templates by feature and used Jinja2's inheritance system.

3. User Feedback​

Providing clear progress indicators and error messages. Solution: Rich library's progress bars and status displays.

4. Package Distribution​

Getting the tool on PyPI and ensuring smooth installation. Solution: Poetry for dependency management and automated CI/CD.

What's Next for FasCraft​

Short Term​

  • Advanced project detection for existing codebases
  • More database and service integrations
  • Enhanced error handling and recovery

Long Term​

  • 1000+ downloads on PyPI
  • Active community of FastAPI developers
  • Regular contributions and feature requests
  • Positive feedback from developers who've saved hours of setup time
  • Plugin system for custom generators
  • Cloud deployment integration
  • Team collaboration features
  • Template marketplace

Key Takeaways for CLI Tool Developers​

1. User Experience Matters​

Even command-line tools need to feel polished and professional. Invest in good UX libraries like Rich.

2. Safety First​

Always provide ways for users to undo actions or recover from mistakes.

3. Documentation is Crucial​

Good documentation can make the difference between adoption and abandonment.

4. Community Feedback is Gold​

Listen to your users and iterate based on their needs.

5. Testing is Essential​

CLI tools need comprehensive testing, especially for file operations and cross-platform compatibility.

Try FasCraft Today​

Ready to streamline your FastAPI development workflow?

pip install fascraft
fascraft new my-next-api
cd my-next-api
pip install -r requirements.txt
uvicorn main:app --reload

Visit the GitHub repository to contribute, report issues, or learn more about the project.

Conclusion​

Building FasCraft has been an incredible learning experience. It's taught me that even small tools can have a big impact on developer productivity. The key is identifying real pain points and solving them elegantly.

If you're thinking about building a CLI tool, my advice is simple: start small, focus on user experience, and iterate based on feedback. The developer tools ecosystem is always growing, and there's always room for tools that make developers' lives easier.

What CLI tools have made your development workflow more efficient? I'd love to hear about them in the comments or on Twitter!