How to Organize Flask App with Blueprints for Clean Structure

Use Flask Blueprints to split your app into smaller, reusable parts by defining routes and views in separate modules. Register these blueprints on the main Flask app to keep your project organized and scalable.

Syntax

A Blueprint is created by importing Blueprint from flask and instantiating it with a name and import path. You define routes on this blueprint like on a normal Flask app. Then, you register the blueprint on the main app using app.register_blueprint().

• Blueprint(name, import_name): Creates a blueprint object.
• @blueprint.route(): Defines routes inside the blueprint.
• app.register_blueprint(blueprint): Adds the blueprint routes to the main app.

python

from flask import Blueprint

simple_page = Blueprint('simple_page', __name__)

@simple_page.route('/hello')
def hello():
    return 'Hello from blueprint!'

# In main app file
from flask import Flask
app = Flask(__name__)
app.register_blueprint(simple_page)

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

Example

This example shows a Flask app organized with two blueprints: auth for authentication routes and blog for blog-related routes. Each blueprint is in its own file, keeping code clean and modular.

python

# project structure:
# /app.py
# /auth.py
# /blog.py

# auth.py
from flask import Blueprint

auth = Blueprint('auth', __name__, url_prefix='/auth')

@auth.route('/login')
def login():
    return 'Login Page'

# blog.py
from flask import Blueprint

blog = Blueprint('blog', __name__, url_prefix='/blog')

@blog.route('/')
def index():
    return 'Blog Home'

# app.py
from flask import Flask
from auth import auth
from blog import blog

app = Flask(__name__)
app.register_blueprint(auth)
app.register_blueprint(blog)

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

Output

Running the app and visiting /auth/login shows 'Login Page'. Visiting /blog/ shows 'Blog Home'.

Common Pitfalls

• Forgetting to register the blueprint on the main app causes routes not to work.
• Not using url_prefix can lead to route conflicts.
• Defining routes outside the blueprint or mixing app and blueprint routes can cause confusion.
• Importing blueprints incorrectly can cause circular imports.

python

from flask import Flask, Blueprint

# Wrong: defining route but not registering blueprint
bp = Blueprint('bp', __name__)

@bp.route('/test')
def test():
    return 'Test'

app = Flask(__name__)
# app.register_blueprint(bp)  # Missing registration causes 404

# Right:
app.register_blueprint(bp)

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

Quick Reference

Blueprints Cheat Sheet:

• Blueprint('name', __name__, url_prefix='/prefix'): Create blueprint with optional URL prefix.
• @blueprint.route('/path'): Define routes inside blueprint.
• app.register_blueprint(blueprint): Register blueprint on main app.
• Use separate files for each blueprint to keep code modular.
• Use url_prefix to avoid route conflicts.

Key Takeaways

Use Flask Blueprints to split your app into modular parts with their own routes.

Always register blueprints on the main Flask app to activate their routes.

Use url_prefix in blueprints to group related routes and avoid conflicts.

Keep blueprints in separate files for better organization and maintainability.

Avoid circular imports by careful blueprint and app structure.