Building custom apps with Frappe framework: a developer's guide

What is the Frappe framework?

Frappe is an open-source, full-stack web framework built with Python and JavaScript. It runs ERPNext, one of the most popular open-source ERP systems in the world, but you can build much more than ERP with it. It gives you what you need to build business applications quickly, without giving up flexibility or the ability to scale.

Frappe is metadata-driven. Instead of writing repetitive code for CRUD operations, forms and APIs, you define your data models (called DocTypes). The framework then generates the forms, REST APIs, database tables and more.

Why build on Frappe?

First, why consider Frappe for a custom business application?

• Quick development: Much less code to write, so a working app comes together faster
• Built-in features: Login, roles, permissions, email, print formats and reports are already there
• Full REST API: Every DocType automatically gets a complete REST API
• Real-time updates: WebSocket support for live data updates
• Multi-tenancy: Host multiple sites on a single instance
• Python + JavaScript: Use Python for server-side logic and JavaScript for client-side customisation
• Active community: A large open-source community and detailed documentation

Understanding DocTypes

DocTypes are the basic building block of any Frappe application. A DocType defines a data model. Think of it as a database table that comes with a form, an API and a place for business logic.

Types of DocTypes

Single DocType: Stores only one record, useful for settings. Example: a "Quality Settings" DocType that holds global configuration for an app.

Regular DocType: Stores multiple records. Example: an "Incoming Inspection" DocType where each record is one inspection of a material batch.

Child DocType: Exists only within a parent DocType as a table field. Example: "Inspection Checks" as a child table within an "Incoming Inspection" DocType.

Virtual DocType: Does not create a database table; pulls data from external sources. Useful for integrating with third-party systems.

Creating a DocType

DocTypes can be created through the Frappe UI or defined in code as JSON files within your custom app. A DocType definition includes:

• Fields: Field types such as Data, Text, Int, Currency, Link, Table, Select and many more
• Permissions: Role-based access control for read, write, create, delete, and submit operations
• Naming: How records are named (auto-increment, by field value, or custom format)
• Workflow: Optional workflow states and transitions

Building a custom app

Step 1: Set up your development environment

Install Frappe Bench, which is the CLI tool for managing Frappe sites and apps:

pip install frappe-bench
bench init my-bench
cd my-bench
bench new-site mysite.localhost

Step 2: Create your custom app

bench new-app my_custom_app
bench --site mysite.localhost install-app my_custom_app

This creates a standard app structure with directories for DocTypes, API endpoints, hooks, and more.

Step 3: Define your DocTypes

Create your data models either through the UI at /app/doctype or by defining JSON files in your app's module directory. Each DocType gets:

• A database table
• A form view
• A list view
• REST API endpoints
• Permission controls

Step 4: Add business logic

Frappe gives you several places to add custom logic:

Controller methods: Python classes that handle events on a DocType:

• before_insert: Before a new record is saved
• validate: Validation before save
• on_submit: After a record is submitted
• on_cancel: After a record is cancelled

Whitelisted API methods: Create custom API endpoints:

@frappe.whitelist()
def calculate_total(inspection_id):
    inspection = frappe.get_doc("Incoming Inspection", inspection_id)
    # Custom calculation logic
    return {"total": total}

Scheduled tasks: Run background jobs on a schedule:

# In hooks.py
scheduler_events = {
    "daily": ["my_app.tasks.daily_cleanup"],
    "hourly": ["my_app.tasks.sync_data"],
}

Working with the Frappe API

Server-side (Python)

Frappe has a full Python API for working with data:

Creating records:

doc = frappe.get_doc({
    "doctype": "Incoming Inspection",
    "supplier": "ABC Castings",
    "item_group": "Castings",
    "checks": [
        {"check_name": "Outer diameter", "method": "Vernier"},
        {"check_name": "Hardness", "method": "IS 1500"}
    ]
})
doc.insert()

Querying data:

inspections = frappe.get_all("Incoming Inspection",
    filters={"status": "Pending"},
    fields=["name", "supplier", "item_group"],
    order_by="creation desc",
    limit=20
)

Updating records:

frappe.db.set_value("Incoming Inspection", "INSP-001", "status", "Completed")

Client-side (JavaScript)

Frappe's client-side API mirrors the server-side patterns:

Making API calls:

frappe.call({
    method: "my_app.api.calculate_total",
    args: { inspection_id: "INSP-001" },
    callback: function(r) {
        console.log(r.message);
    }
});

Form customisation:

frappe.ui.form.on("Incoming Inspection", {
    refresh: function(frm) {
        if (frm.doc.status === "Pending") {
            frm.add_custom_button("Start Inspection", function() {
                frm.set_value("status", "In Progress");
                frm.save();
            });
        }
    }
});

Custom workflows

Frappe has a built-in workflow engine. You can define the states a document moves through for any DocType:

Defining a workflow

A workflow consists of:

• States: The possible states a document can be in (e.g., Draft, Pending Review, Approved, Rejected)
• Transitions: Allowed state changes with conditions and permissions
• Actions: What happens when a transition occurs

Example: inspection approval workflow

An incoming inspection might follow this workflow:

1. Draft: Material received, awaiting inspection
2. In Progress: Inspection underway
3. Pending Review: Results entered, awaiting review by the QC head
4. Approved: The QC head has approved the results
5. Released: Material released to stores

Each transition can require specific roles, trigger email notifications, and execute custom Python logic.

Integration capabilities

Connecting a Frappe app to other systems is straightforward:

REST API integration

Every DocType has auto-generated REST endpoints:

• GET /api/resource/Incoming Inspection: List inspections
• POST /api/resource/Incoming Inspection: Create an inspection
• GET /api/resource/Incoming Inspection/INSP-001: Get one inspection
• PUT /api/resource/Incoming Inspection/INSP-001: Update an inspection

Webhooks

Configure webhooks to notify external systems when events occur in your Frappe app. Webhooks can be triggered on document events like creation, update, submission, or cancellation.

Background jobs

For heavy processing or calls to outside APIs, use Frappe's background jobs, built on Redis Queue (RQ). Long tasks then run without blocking the web interface.

Print formats

Create custom print formats using HTML and Jinja templating. Print formats can generate PDFs for reports, invoices, labels, and any other document type your application needs.

Deployment and scaling

Frappe applications can be deployed on any Linux server. The production stack typically includes:

• Nginx as the reverse proxy
• Gunicorn for serving the Python application
• MariaDB/PostgreSQL for the database
• Redis for caching and background jobs
• Supervisor for process management

For scaling, Frappe supports:

• Multiple Gunicorn workers for handling concurrent requests
• Redis caching for frequently accessed data
• Read replicas for database scaling
• CDN integration for static assets

Getting started with Frappe development

If you plan to build a custom business application, Frappe lets you build quickly on a base that is ready for production. A quality module, an ERP add-on or a dealer portal are all good fits.

Talk to us about a custom app.