Quickstart Guide

This guide will walk you through creating your first Framefox application from scratch. You’ll have a working web app in just a few minutes.

Prerequisites

Before you begin, make sure you have:

Python 3.12 or higher installed
pip package manager
A terminal or command prompt

Step 1: Install Framefox

Install via pip

Install Framefox using pip:

pip install framefox

This will install Framefox and all its dependencies, including FastAPI, SQLModel, Uvicorn, and Jinja2.

Verify installation

Verify that Framefox is installed correctly:

framefox --version

Step 2: Initialize Your Project

Create a new project

Use the interactive CLI to create a new project:

framefox init

The CLI will prompt you for:

Project name: Enter your project name (e.g., “my-app”)
Database type: Choose between SQLite, PostgreSQL, or MySQL
Include examples: Choose whether to include example code

Navigate to project directory

Change into your project directory:

cd my-app

Step 3: Project Structure

After initialization, your project will have this structure:

my-app/
├── src/
│   ├── controllers/        # HTTP request handlers
│   │   └── home_controller.py
│   ├── entity/            # Database models
│   ├── form/              # Form definitions
│   └── repository/        # Data access layer
├── templates/             # Jinja2 templates
│   └── home/
│       └── index.html
├── public/               # Static files (CSS, JS, images)
│   ├── css/
│   └── js/
├── config/               # Configuration files
│   ├── application.yaml
│   ├── orm.yaml
│   └── security.yaml
├── main.py              # Application entry point
└── .env                 # Environment variables

Step 4: Start the Development Server

Run the server

Start the development server:

framefox run

You should see output like:

INFO:     Uvicorn running on http://127.0.0.1:8000
INFO:     Application startup complete.

Open in browser

Open your browser and navigate to:

http://localhost:8000

You’ll see your Framefox application running!

Step 5: Create Your First Controller

Let’s create a simple controller to display a “Hello World” page.

Generate a controller

Use the CLI to generate a new controller:

framefox create controller

When prompted:

Controller name: Enter “Hello”
Type: Choose “Templated” (for HTML views)

Edit the controller

Open src/controllers/hello_controller.py and add a route:

hello_controller.py

from framefox.core.controller.abstract_controller import AbstractController
from framefox.core.routing.decorator.route import Route

class HelloController(AbstractController):
    
    @Route("/hello", "hello.index", methods=["GET"])
    async def index(self):
        return self.render("hello/index.html", {
            "name": "World",
            "greeting": "Hello"
        })

Create the template

Create a new file templates/hello/index.html:

templates/hello/index.html

<!DOCTYPE html>
<html>
<head>
    <title>{{ greeting }} {{ name }}</title>
    <link href="{{ asset('css/app.css') }}" rel="stylesheet">
</head>
<body>
    <div class="container">
        <h1>{{ greeting }}, {{ name }}!</h1>
        <p>Welcome to your Framefox application.</p>
        <a href="{{ url_for('home.index') }}">Go to Home</a>
    </div>
</body>
</html>

Test your route

The development server automatically reloads. Visit:

http://localhost:8000/hello

You should see your “Hello, World!” page!

Step 6: Add a Database Model

Now let’s add a simple database model and perform CRUD operations.

Create an entity

Generate a new entity (database model):

framefox create entity

When prompted:

Entity name: Enter “Post”
Add properties: Add “title” (string) and “content” (text)

Review the entity

Check the generated file in src/entity/post.py:

post.py

from framefox.core.orm.abstract_entity import AbstractEntity
from sqlmodel import Field
from typing import Optional

class Post(AbstractEntity, table=True):
    __tablename__ = "post"
    
    id: Optional[int] = Field(default=None, primary_key=True)
    title: str = Field(max_length=255)
    content: str

Create a migration

Generate a database migration for your new entity:

framefox database create-migration

Enter a description like “Create post table”.

Run the migration

Apply the migration to create the table:

framefox database upgrade

Step 7: Create a Repository

Repositories provide a clean interface for database operations.

src/repository/post_repository.py

from framefox.core.orm.abstract_repository import AbstractRepository
from src.entity.post import Post

class PostRepository(AbstractRepository[Post]):
    def __init__(self, entity_manager):
        super().__init__(entity_manager, Post)

Step 8: Use the Repository in a Controller

Update your controller to work with the database:

src/controllers/post_controller.py

from framefox.core.controller.abstract_controller import AbstractController
from framefox.core.routing.decorator.route import Route
from src.repository.post_repository import PostRepository

class PostController(AbstractController):
    
    @Route("/posts", "post.index", methods=["GET"])
    async def index(self, post_repository: PostRepository):
        posts = await post_repository.find_all()
        return self.render("post/index.html", {"posts": posts})
    
    @Route("/posts/{id}", "post.show", methods=["GET"])
    async def show(self, id: int, post_repository: PostRepository):
        post = await post_repository.find(id)
        return self.render("post/show.html", {"post": post})

Notice how PostRepository is automatically injected into the controller methods through dependency injection!

Next Steps

Congratulations! You’ve created your first Framefox application. Here’s what to explore next:

Core Concepts

Learn about MVC architecture and how Framefox works

Controllers

Master routing, responses, and forms

Templates

Build dynamic views with Jinja2

Database & ORM

Work with entities, repositories, and migrations

Security

Add authentication and protect your app

CLI Reference

Explore all available CLI commands

Common Commands

Here are some commands you’ll use frequently:

Command	Description
`framefox run`	Start development server
`framefox create controller`	Generate a new controller
`framefox create entity`	Generate a new entity
`framefox create crud`	Generate full CRUD (controller + templates)
`framefox database create-migration`	Create a database migration
`framefox database upgrade`	Run pending migrations
`framefox debug router`	List all registered routes

Getting Help

Development server won't start

Check that port 8000 is not already in use
Verify your .env file has correct settings
Run framefox debug config to check configuration

Database connection errors

Verify database credentials in .env
Ensure the database server is running
Check config/orm.yaml for correct configuration

Import errors

Make sure you’re in the correct directory
Verify all dependencies are installed: pip install -r requirements.txt
Check Python version is 3.12 or higher

Templates not found

Ensure templates are in the templates/ directory
Check template path in your controller matches the file location
Template paths are relative to the templates/ directory

Resources

Installation Guide - Detailed installation instructions
Architecture Overview - Understand how Framefox works
GitHub Repository - Source code and examples

Getting Started

Core Concepts

Controllers

Templates

Database & ORM

Security

Advanced Features

Deployment

Quickstart

Quickstart Guide

Prerequisites

Step 1: Install Framefox

Step 2: Initialize Your Project

Step 3: Project Structure

Step 4: Start the Development Server

Step 5: Create Your First Controller

Step 6: Add a Database Model

Step 7: Create a Repository

Step 8: Use the Repository in a Controller

Next Steps

Core Concepts

Controllers

Templates

Database & ORM

Security

CLI Reference

Common Commands

Getting Help

Resources

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Controllers

Templates

Database & ORM

Security

Advanced Features

Deployment

​Quickstart Guide

​Prerequisites

​Step 1: Install Framefox

​Step 2: Initialize Your Project

​Step 3: Project Structure

​Step 4: Start the Development Server

​Step 5: Create Your First Controller

​Step 6: Add a Database Model

​Step 7: Create a Repository

​Step 8: Use the Repository in a Controller

​Next Steps

Core Concepts

Controllers

Templates

Database & ORM

Security

CLI Reference

​Common Commands

​Getting Help

​Resources

Build docs developers (and LLMs) love

Quickstart Guide

Prerequisites

Step 1: Install Framefox

Step 2: Initialize Your Project

Step 3: Project Structure

Step 4: Start the Development Server

Step 5: Create Your First Controller

Step 6: Add a Database Model

Step 7: Create a Repository

Step 8: Use the Repository in a Controller

Next Steps

Common Commands

Getting Help

Resources