sbknext/forge-frappe-skill

frappe-app-development

Scaffold, architect, and build production-grade custom Frappe/ERPNext apps.

View source

How to use

  1. Copy the installation command and review the source package before installing it in your own agent environment.
  2. Check the source document for required tools, credentials and supported hosts.
  3. Describe your input and desired deliverable; review the output against the source material.
npx skills add https://github.com/sbknext/forge-frappe-skill --skill frappe-app-development

Before you start

  • Installation does not include a model subscription, API allowance or permission to access your files.
  • Repository stars and installation counts describe activity, not an independent quality or security test.
Original skill document

Rendered from the source repository. Headings, examples, code, tables, links, and referenced images are preserved.

Frappe App Development

Scaffold and build production-grade custom Frappe / ERPNext applications with correct separation of concerns and tested patterns.

When to use

  • Creating a new custom Frappe app from scratch (bench new-app)
  • Designing DocType structure (fields, child tables, naming series)
  • Writing hooks.py — doc_events, scheduler_events, override_whitelisted_methods
  • Implementing background jobs via frappe.enqueue
  • Building REST APIs with @frappe.whitelist()
  • Service-layer pattern: thin controllers, fat service modules
  • Adding caching, logging, error handling cross-cutting utilities
  • Permission checks with frappe.has_permission() / frappe.only_for()
  • Writing tests with frappe.tests.utils.FrappeTestCase
  • Deploying and migrating (bench migrate, bench build)

Inputs required

  • App name and purpose
  • Target Frappe version (v14, v15, v16+)
  • Module structure (which DocTypes, which APIs)
  • Site name

Core patterns

1. App scaffold

bash
bench new-app <app_name>
bench --site <site> install-app <app_name>

2. DocType conventions (Frappe way)

  • Use frappe.get_doc() / frappe.get_list() — never raw SQL unless parameterized
  • frappe.db.get_value() for single field reads
  • frappe.db.sql() ONLY with %s params, never f-strings
  • Naming: PascalCase for DocTypes, snake_case for Python, camelCase for JS

3. hooks.py — golden patterns

python
# doc_events — thin controller, delegate to service
doc_events = {
    "Sales Order": {
        "on_submit": "myapp.services.order_sync.on_submit",
        "on_cancel": "myapp.services.order_sync.on_cancel",
    }
}

# Scheduler events
scheduler_events = {
    "daily": ["myapp.tasks.daily_sync.run"],
    "cron": {
        "0 */2 * * *": ["myapp.tasks.monitor.run"],  # every 2h
    }
}

# Override whitelisted methods (use sparingly)
override_whitelisted_methods = {
    "frappe.client.get_list": "myapp.overrides.client.get_list"
}

4. Service layer pattern

myapp/
  myapp/
    services/
      order_sync.py   ← business logic (no frappe.form refs)
      external_api.py ← external API wrapper
    api/
      v1.py           ← @frappe.whitelist() endpoints (thin)
    utils/
      logger.py       ← frappe.logger() wrapper
      cache.py        ← frappe.cache() helpers
    tasks/
      daily_sync.py   ← scheduler entry points

5. Background jobs

python
# Enqueue (fire and forget)
frappe.enqueue(
    "myapp.services.order_sync.sync_order",
    order_name=doc.name,
    queue="long",       # short / default / long
    timeout=1800,
    job_id=f"sync_order_{doc.name}",  # dedup key
    is_async=True,
)

# Inside the job — always log, never raise silently
def sync_order(order_name):
    logger = frappe.logger("order_sync", allow_site=True)
    try:
        doc = frappe.get_doc("Sales Order", order_name)
        # ... work ...
        frappe.db.commit()
    except Exception:
        logger.error(frappe.get_traceback())
        raise

6. Whitelisted REST APIs

python
import frappe

@frappe.whitelist()
def get_order_status(order_name: str) -> dict:
    frappe.has_permission("Sales Order", "read", order_name, throw=True)
    doc = frappe.get_doc("Sales Order", order_name)
    return {
        "name": doc.name,
        "status": doc.status,
        "customer": doc.customer,
    }

7. Caching

python
# Per-site, TTL in seconds
cache_key = f"myapp:config:{frappe.local.site}"
config = frappe.cache().get_value(cache_key)
if not config:
    config = frappe.get_single("My App Settings").as_dict()
    frappe.cache().set_value(cache_key, config, expires_in_sec=300)

8. Permission pattern

python
# Role check
frappe.only_for(["System Manager", "My App Manager"])

# Document-level
frappe.has_permission("Sales Order", "write", order_name, throw=True)

9. Tests

python
import frappe
from frappe.tests.utils import FrappeTestCase

class TestOrderSync(FrappeTestCase):
    def test_sync_sets_status(self):
        doc = frappe.get_doc({
            "doctype": "Sales Order",
            "customer": "Test Customer",
            # ...
        }).insert()
        result = sync_order(doc.name)
        self.assertEqual(result["status"], "Synced")

10. Migrations (safe)

bash
# Run migrate after every schema change
bench --site <site> migrate
bench build --app <app_name>

11. Controller hooks and v15 type annotations

Frappe auto-generates Python type stubs in controllers (v15+). Enable with:

python
# hooks.py
export_python_type_annotations = True

The generated block between # begin: auto-generated types / # end: auto-generated types is overwritten on DocType update — put custom logic outside it.

Key lifecycle hooks: before_validate (set defaults), validate (throw to block save), before_save, on_update, on_submit, on_cancel, on_change (also fires on db_set — keep idempotent).

doc.insert() / doc.save() escape hatches (use sparingly, never in user-facing paths without audit):

python
doc.insert(ignore_permissions=True, ignore_links=True, ignore_mandatory=True)
doc.save(ignore_permissions=True, ignore_version=True)
doc.db_set("status", "Closed")  # skips validate/hooks — prefer doc.save()

Controller hooks & v15 type annotations

Put lifecycle logic in the DocType controller (before_save, validate, on_submit, etc.) — see the full hook matrix in the Controllers docs. Prefer controller methods over inline hooks.py doc_events when logic belongs to one DocType.

v15+ can auto-export Python type annotations in controllers:

python
# hooks.py
export_python_type_annotations = True

Annotations regenerate on DocType update — do not hand-edit the auto-generated block.

Security guardrails (HARD RULES)

  • NEVER frappe.db.sql("... WHERE name = '%s'" % name) — use %s params
  • NEVER disable CSRF (frappe.flags.ignore_csrf = True) in production
  • NEVER store secrets in DocType fields — use site_config.json + frappe.conf.get()
  • ALWAYS validate file uploads (type, size, extension) before save
  • ALWAYS use frappe.only_for() or frappe.has_permission() on sensitive APIs
  • ALWAYS run bench --site <site> migrate after schema changes — never touch the DB directly

Production patterns

  • Use frappe.enqueue with job_id for dedup on high-frequency events
  • Keep app hooks thin — delegate to a service layer that has no frappe.form references
  • Specify --site <site> explicitly in every bench command on multi-site benches
  • Prefer Frappe-native workflow + notification primitives over custom cron hacks

From Frappe docs

  • Controller hooks table (insert/save/submit/cancel columns): https://docs.frappe.io/framework/user/en/basics/doctypes/controllers
  • Document API (insert, save, db_set, queue_action): https://docs.frappe.io/framework/user/en/api/document
  • Tutorial — developer mode + DocType boilerplate: https://docs.frappe.io/framework/user/en/tutorial/create-a-doctype
  • Controller methods tutorial (before_save example): https://docs.frappe.io/framework/user/en/tutorial/controller-methods
from this repository

More skills

All skills
sbknext
Community

frappe-client-scripting

Customize Frappe desk forms and lists with client scripts — frappe.ui.form.on handlers, field events, setquery link filters, setdfproperty, custom buttons, frappe.call, and list view settings. Use when adding form interactivity, dynamic filters, validation, or buttons in the desk UI. Trigger on: "client script", "frappe.ui.form.on", "form event", "setquery", "custom button", "frappe.call", "list view settings", "curfrm".

1h installs
1
GitHub stars
18
Updated
Jun 7
sbknext
Community

frappe-database-orm

Query and mutate data in Frappe safely — getdoc/getall/getlist, frappe.db.getvalue/setvalue, parameterized frappe.db.sql, Query Builder (frappe.qb), transactions, bulk ops, and performance. Use when reading or writing data, optimizing slow queries, or avoiding SQL injection. Trigger on: "frappe.db.sql", "frappe.getall", "query builder", "frappe.qb", "bulk update", "N+1", "db transaction", "getvalue setvalue".

1h installs
1
GitHub stars
18
Updated
Jun 7
sbknext
Community

frappe-report-development

Build Frappe reports — Query Reports (SQL), Script Reports (Python), filters, columns, charts, formatters, and report permissions. Use when creating analytics/listing reports, dashboards, or exportable views in Frappe/ERPNext. Trigger on: "query report", "script report", "Frappe report", "report filters", "report chart", "columns formatter", "report builder".

1h installs
1
GitHub stars
18
Updated
Jun 7
sbknext
Community

frappe-testing

Write and run tests for Frappe/ERPNext apps — FrappeTestCase, test records, fixtures, mocking, permission tests, running with bench run-tests, and CI. Use when adding test coverage, doing TDD on a DocType or API, or setting up a test pipeline. Trigger on: "Frappe test", "FrappeTestCase", "bench run-tests", "unit test DocType", "test fixtures", "TDD frappe".

1h installs
1
GitHub stars
18
Updated
Jun 7