fastappkit 0.1.8

A toolkit for building FastAPI projects with apps - internal and external pluggable apps

fastappkit

A toolkit for building FastAPI projects with apps — internal and external pluggable apps

fastappkit brings Django-like app architecture to FastAPI, enabling modular development with both project-specific internal apps and reusable external pluggable apps.

What is fastappkit?

fastappkit is a toolkit for building FastAPI projects with a modular app architecture. It enables:

• Internal apps — project-specific feature modules (like Django apps)
• External apps — reusable, pluggable packages (like WordPress plugins)
• Unified migrations — coordinated database schema management
• Automatic router mounting — seamless integration of app routes
• App validation and isolation — ensure apps don't conflict with each other

✨ Key Features

• ✅ Clean project structure with automatic app discovery
• ✅ Shared migrations for internal apps, isolated migrations for external apps
• ✅ Automatic router mounting with configurable prefixes
• ✅ Fail-fast validation and error handling
• ✅ Support for both monorepo and multi-repo workflows
• ✅ Simple CLI for project and app management

📦 Installation

Install fastappkit using pip or poetry:

pip install fastappkit

or

poetry add fastappkit

🏃 Quick Start

1. Create a new project

fastappkit core new myproject
cd myproject

This creates a complete FastAPI project structure with:

• Core application setup (including core/models.py with SQLAlchemy Base class)
• Database configuration
• Migration system
• App directory structure

Note: Dependency versions in pyproject.toml are set to * by default. Update them according to your needs, especially for production deployments.

2. Create an internal app

fastappkit app new blog

This creates a new internal app in apps/blog/ with models, router, and registers it in fastappkit.toml.

3. Run migrations

fastappkit migrate all

This runs all migrations in the correct order: core → internal apps → external apps.

4. Start the development server

fastappkit core dev

Your FastAPI application is now running at http://127.0.0.1:8000!

📚 Documentation

Comprehensive documentation is available at Read the Docs (coming soon).

For now, see docs/Usage.md for detailed usage instructions.

🎯 Core Concepts

Internal Apps

Internal apps are project-specific modules that live in your project's apps/ directory. They share the same migration system and database connection.

fastappkit app new blog
# Creates apps/blog/ with models, router, etc.

Key points:

• Internal apps import Base from core.models for SQLAlchemy models
• The register() function can return Optional[APIRouter] - return a router for fastappkit to mount, or mount it yourself and return None

External Apps

External apps are reusable packages that can be installed via pip and plugged into any fastappkit project.

fastappkit app new payments --as-package
# Creates a standalone package structure

Key points:

• External apps must use their own Base class (isolated metadata) - cannot import from core
• The register() function can return Optional[APIRouter] - return a router for fastappkit to mount, or mount it yourself and return None
• External apps must have fastappkit.toml manifest in the package directory

Migrations

fastappkit provides unified migration management:

• Core migrations: Project-level schema changes
• Internal app migrations: Shared migration directory for all internal apps
• External app migrations: Isolated migrations per external app

# Create migrations for an internal app
fastappkit migrate app blog makemigrations -m "Add post model"

# Run all migrations
fastappkit migrate all

# Preview SQL before applying
fastappkit migrate preview

🛠️ CLI Commands

Project Management

fastappkit core new <name>          # Create a new project
fastappkit core dev                  # Run development server

App Management

fastappkit app new <name>            # Create an internal app
fastappkit app new <name> --as-package  # Create an external app
fastappkit app list                  # List all apps
fastappkit app validate <name>       # Validate an app

Migration Management

fastappkit migrate core -m "message"           # Create core migration
fastappkit migrate app <name> makemigrations -m "message"  # Create app migration (internal only)
fastappkit migrate app <name> upgrade [--revision <rev>]  # Upgrade app migrations (external only)
fastappkit migrate app <name> downgrade --revision <rev>  # Downgrade app migrations (external only, --revision required)
fastappkit migrate app <name> preview [--revision <rev>]  # Preview SQL for app migrations (external only)
fastappkit migrate all                        # Run all migrations
fastappkit migrate preview [--revision <rev>]  # Preview SQL for core + internal app migrations
fastappkit migrate upgrade [--revision <rev>]  # Upgrade core + internal app migrations
fastappkit migrate downgrade <rev>            # Downgrade core + internal app migrations (<rev> required)

📖 Example Project Structure

myproject/
├── core/
│   ├── config.py          # Settings (loads from .env)
│   ├── models.py          # SQLAlchemy Base class (DeclarativeBase)
│   ├── app.py             # create_app() factory
│   └── db/
│       └── migrations/    # Core migrations
├── apps/                   # Internal apps directory
│   └── blog/
│       ├── models.py       # Imports Base from core.models
│       └── router.py
├── fastappkit.toml        # Project configuration
├── .env                   # Environment variables
└── main.py                # Entry point

🔧 Configuration

fastappkit uses fastappkit.toml for project configuration:

[tool.fastappkit]
apps = [
    "apps.blog",
    "apps.users",
    "external_package_name"
]

🤝 Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

📄 License

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

🙏 Acknowledgments

• Inspired by Django's app system
• Built with FastAPI, SQLAlchemy, Alembic, and Typer

📞 Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

---

Made with ❤️ for the FastAPI community