Blueprint in Flask: A Practical Approach to Modular Application Development

When developing applications with Flask, as functionality grows, code files become longer and route management becomes chaotic. At this point, Flask’s Blueprint feature becomes invaluable. A blueprint acts like a “functional template,” helping you group routes and view functions of different modules, resulting in a clearer project structure and more maintainable code.

Why Use Blueprints?¶

Imagine writing all routes in a single app.py file: user registration, product listings, order management… As features multiply, the code becomes as tangled as spaghetti. Blueprints solve this by:

Modular Grouping: Split routes for different functionalities (e.g., user-related vs. product-related) into independent “blueprints,” each handling a specific feature.
Clear Code Structure: Isolate code for different modules, making team collaboration and division of labor easier.
Avoid Circular Imports: In large projects, inter-module dependencies often cause circular import errors; blueprints reduce this risk.
Reusability: Blueprints can be reused across multiple projects or registered multiple times within the same project.

Blueprint Practical Guide: Building a Modular Application from Scratch¶

Step 1: Project Structure Design¶

Plan a simple project structure with a main application and two blueprint modules (user and product):

myapp/
├── app.py          # Main application entry
├── user/           # User module blueprint
│   ├── __init__.py # Initialization file
│   └── routes.py   # User-related routes
└── product/        # Product module blueprint
    ├── __init__.py
    └── routes.py   # Product-related routes

app.py: Main application that registers all blueprints and starts the server.
user/routes.py: Defines routes for the user module.
product/routes.py: Defines routes for the product module.

Step 2: Create the User Module Blueprint¶

In user/routes.py, create a blueprint instance and define user-related routes:

# user/routes.py
from flask import Blueprint, render_template

# Create blueprint instance: first parameter is the unique name, second is the module name (__name__)
user_bp = Blueprint('user', __name__)

# Define user routes (use blueprint's route decorator, not app.route)
@user_bp.route('/profile')
def profile():
    return "User Profile Page"

@user_bp.route('/login')
def login():
    return "User Login Page"

Step 3: Create the Product Module Blueprint¶

Similarly, define product-related routes in product/routes.py:

# product/routes.py
from flask import Blueprint

# Create product module blueprint
product_bp = Blueprint('product', __name__)

# Product-related routes
@product_bp.route('/list')
def product_list():
    return "Product List Page"

@product_bp.route('/detail/<int:pid>')
def product_detail(pid):
    return f"Product Detail: ID={pid}"

Step 4: Register Blueprints in the Main Application (app.py)¶

In the main app.py, import and register the blueprints:

# app.py
from flask import Flask
from user.routes import user_bp  # Import user blueprint
from product.routes import product_bp  # Import product blueprint

app = Flask(__name__)

# Register blueprints: url_prefix adds a common prefix to all routes in the blueprint
app.register_blueprint(user_bp, url_prefix='/user')
app.register_blueprint(product_bp, url_prefix='/product')

if __name__ == '__main__':
    app.run(debug=True)

Step 5: Test the Routes¶

Run app.py and visit the following URLs to verify:
- User module: http://localhost:5000/user/profile (Profile), http://localhost:5000/user/login (Login)
- Product module: http://localhost:5000/product/list (Product List), http://localhost:5000/product/detail/123 (Product Detail, ID=123)

Advanced Blueprint Usage¶

Beyond route grouping, blueprints support:

1. Template Path Isolation¶

If a module has its own templates, specify template_folder when creating the blueprint:

# user/__init__.py (or in routes.py)
user_bp = Blueprint('user', __name__, template_folder='templates')

Place user module templates in user/templates/user/profile.html, while the main app’s templates go in templates/. Flask prioritizes blueprint-specific templates.

2. Static File Isolation¶

Similarly, use static_folder to manage static resources for a module:

product_bp = Blueprint('product', __name__, static_folder='static')

Place product static files in product/static/; access them via /product/static/xxx.js.

3. Blueprint Prefixes and Subdomains¶

Prefixes: As in Step 4, url_prefix='/user' adds a common prefix to all routes in the blueprint.
Subdomains: Use the subdomain parameter to restrict blueprints to specific subdomains (e.g., subdomain='admin').

Summary¶

Blueprints are the core tool for modular development in Flask, enabling:
- Splitting complex applications into independent modules, reducing maintenance costs.
- Making route management clearer and code structure more logical.
- Facilitating team collaboration and reusability in large projects.

It is recommended to start using blueprints in small projects to develop a “modular” mindset. As projects grow in complexity, blueprints will become an indispensable assistant for managing your code!