Frappe App Development

Scaffold, structure, and architect custom Frappe applications with production-grade patterns.

When to use

• Creating a new custom Frappe app from scratch
• Setting up app architecture (modules, services, utils)
• Configuring hooks.py for events, scheduler, overrides
• Implementing background jobs and async processing
• Building service layers and domain logic patterns
• Adding caching, logging, error handling utilities
• Preparing apps for production deployment
• Managing translations, versioning, and packaging

Inputs required

• App name and purpose
• Target Frappe version (v13+, v15+, v16+)
• Module structure (which DocTypes, APIs, services)
• Whether hooks/overrides of other apps are needed
• Background job requirements
• Production readiness needs

Procedure

0) Scaffold the app

# Create the app
bench new-app my_app

# Install on site
bench --site mysite.local install-app my_app

# Verify developer mode
bench --site mysite.local console
>>> frappe.conf.developer_mode  # Must be True

1) Plan app structure

Follow the domain architecture pattern — keep DocType controllers thin and business logic in service modules:

my_app/
├── my_app/
│   ├── __init__.py
│   ├── hooks.py              # App hooks and configuration
│   ├── api.py                # Public API surface (RPC endpoints)
│   ├── services/             # Business logic modules
│   │   └── billing.py
│   ├── utils/                # Cross-cutting utilities
│   │   ├── cache.py
│   │   ├── errors.py
│   │   ├── logging.py
│   │   ├── permissions.py
│   │   └── validation.py
│   ├── background_jobs/      # Async job handlers
│   │   └── export_job.py
│   ├── integrations/         # External system connectors
│   │   └── payment_gateway.py
│   ├── my_module/
│   │   ├── doctype/
│   │   │   └── my_doc/
│   │   │       ├── my_doc.json
│   │   │       ├── my_doc.py
│   │   │       ├── my_doc.js
│   │   │       └── test_my_doc.py
│   │   ├── report/
│   │   └── dashboard/
│   └── translations/
│       ├── en.csv
│       └── fr.csv
├── setup.py
└── README.md

Use the mini-app-template in assets/mini-app-template/ as a starting scaffold.

2) Configure hooks.py

# hooks.py

app_name = "my_app"
app_title = "My App"
app_publisher = "My Company"

# DocType lifecycle events
doc_events = {
    "Sales Order": {
        "on_submit": "my_app.services.billing.on_order_submit",
        "on_cancel": "my_app.services.billing.on_order_cancel",
    },
    "*": {
        "after_insert": "my_app.utils.logging.log_creation",
    }
}

# Scheduled tasks
scheduler_events = {
    "daily": [
        "my_app.background_jobs.cleanup.run_daily_cleanup"
    ],
    "cron": {
        "0 */6 * * *": [
            "my_app.background_jobs.sync.sync_external_data"
        ]
    }
}

# Client-side script injection
doctype_js = {
    "Sales Order": "public/js/sales_order.js"
}

doctype_list_js = {
    "Sales Order": "public/js/sales_order_list.js"
}

# Override another app's controller (use sparingly)
# override_doctype_class = {
#     "ToDo": "my_app.overrides.custom_todo.CustomToDo"
# }

# Extend controller without full replacement (v16+, preferred)
# extend_doctype_class = {
#     "ToDo": "my_app.overrides.todo_extension.TodoExtension"
# }

# Override whitelisted methods
# override_whitelisted_methods = {
#     "frappe.client.get_list": "my_app.overrides.custom_get_list"
# }

3) Implement service layer

Keep DocType controllers thin — delegate business logic to services:

# my_app/services/billing.py
import frappe

def on_order_submit(doc, method):
    """Handle order submission — called via doc_events hook."""
    if doc.grand_total > 10000:
        create_approval_request(doc)
    generate_invoice(doc)

def generate_invoice(order):
    """Create invoice from submitted order."""
    invoice = frappe.get_doc({
        "doctype": "Sales Invoice",
        "customer": order.customer,
        "items": [
            {"item_code": i.item_code, "qty": i.qty, "rate": i.rate}
            for i in order.items
        ]
    })
    invoice.insert()
    invoice.submit()
    return invoice

4) Set up background jobs

# my_app/background_jobs/export_job.py
import frappe

def enqueue_export(filters):
    """Enqueue a long-running export job."""
    frappe.enqueue(
        "my_app.background_jobs.export_job.run_export",
        filters=filters,
        queue="long",
        timeout=600,
        is_async=True
    )

def run_export(filters):
    """Execute the export — runs in background worker."""
    data = frappe.get_all("Sales Order", filters=filters, fields=["*"])
    # Process data...
    frappe.publish_realtime("export_complete", {"count": len(data)})

5) Add cross-cutting utilities

# my_app/utils/cache.py
import frappe

def get_cached_settings(key):
    """Cache expensive settings lookups."""
    value = frappe.cache().get_value(f"my_app:{key}")
    if value is None:
        value = frappe.db.get_single_value("My Settings", key)
        frappe.cache().set_value(f"my_app:{key}", value)
    return value

def invalidate_cache(key):
    frappe.cache().delete_value(f"my_app:{key}")

# my_app/utils/errors.py
import frappe

def api_error(message, status_code=400, exc=None):
    """Consistent error response for API endpoints."""
    frappe.local.response["http_status_code"] = status_code
    frappe.throw(message, exc or frappe.ValidationError)

6) Handle translations

# In Python code
frappe._("Hello World")   # Mark string for translation

# In JavaScript
__("Hello World")         # Mark string for translation

# Translation CSV files go in my_app/translations/
# e.g., my_app/translations/fr.csv:
# Hello World,Bonjour le monde

7) Version compatibility

Feature	Minimum Version
extend_doctype_class	Frappe v16+
REST API v2 (/api/v2/)	Frappe v15+
Token-based auth	Frappe v11.0.3+

When targeting multiple versions, guard version-specific features:

import frappe

if hasattr(frappe, 'extend_doctype_class'):
    # v16+ pattern
    pass
else:
    # Fallback for older versions
    pass

Verification

• App installs without errors: bench --site <site> install-app my_app
• Hooks fire correctly (check scheduler logs, doc events)
• Background jobs enqueue and complete
• bench --site <site> migrate succeeds
• Tests pass: bench --site <site> run-tests --app my_app

Failure modes / debugging

• App not found: Check apps.txt and sites/<site>/site_config.json
• Hooks not firing: Verify hooks.py syntax; restart bench
• Background jobs stuck: Check worker status with bench doctor; verify Redis
• Import errors: Ensure module paths in hooks match actual Python paths
• Developer mode off: DocType changes won't export to files

Escalation

• For DocType creation details → frappe-doctype-development
• For API endpoint patterns → frappe-api-development
• For Desk UI customization → frappe-desk-customization
• For Frappe UI frontends → frappe-frontend-development
• For print formats and Jinja → frappe-printing-templates
• For reports → frappe-reports
• For web forms → frappe-web-forms
• For testing → frappe-testing
• For enterprise architecture → frappe-enterprise-patterns
• For Docker/FM environments → frappe-manager

References

• references/app-development.md — End-to-end app architecture
• references/version-compat.md — Version compatibility notes
• references/translations.md — Multi-language support

Cross-references (owned by specialized skills)

• hooks.py and extension points → frappe-doctype-development (hooks-extensions.md)
• Python API reference → frappe-api-development (python-api.md)

Guardrails

• Use Frappe UI for custom frontends: Never use vanilla JS, jQuery, or custom frameworks. Frappe UI (Vue 3 + TailwindCSS) is the ecosystem standard. See frappe-frontend-development for setup.
• Follow CRM/Helpdesk patterns for CRUD apps: Follow frappe-ui-patterns skill for app shell, navigation, list views, and form layouts derived from official Frappe apps.
• Follow naming conventions: App name must be lowercase with underscores, valid Python identifier
• Use hooks.py for integrations: Never monkey-patch; use doc_events, scheduler_events, boot_session hooks
• Keep hooks.py clean: Only configuration, no logic; import from modules
• Maintain backwards compatibility: Use frappe.version checks for cross-version support
• Export fixtures properly: Use fixtures in hooks.py for data that should sync with app

Common Mistakes

Mistake	Why It Fails	Fix
App not in installed_apps	App code not loaded	Run bench --site <site> install-app my_app
Wrong module path in hooks	Events don't fire	Verify path matches actual my_app/module/file.py structure
Duplicate hook registrations	Events fire multiple times	Check hooks.py for duplicates; use list not repeated keys
Editing hooks.py without restart	Changes not picked up	Run bench restart after hooks.py changes
Missing __init__.py files	Module import errors	Ensure every directory has __init__.py
Logic in hooks.py	Hard to test, import errors	Move logic to separate modules, import in hooks
Building frontend with vanilla JS/jQuery	Inconsistent with ecosystem	Use Frappe UI (Vue 3); see frappe-frontend-development
Custom app shell for CRUD apps	Inconsistent UX	Follow CRM/Helpdesk patterns for navigation and layouts