Frappe Framework and ERPNext

This section collects Avunu's development conventions, code recipes, and server procedures for Frappe Framework and ERPNext.

Getting Started

The Frappe official docs are a great starting point.

Avunu Conventions

Frappe is already quite featureful and opinionated, but we have our own (mostly-officially-undocumented) conventions.

Foundation

• Project Structure & Hooks — App layout, hooks.py configuration, bundle naming, and module organization.

• Type Annotations & Controller Overrides — Strong typing with DF.*, cast, TypedDict, and TYPE_CHECKING patterns.

Customizations

• Customizations API — Overriding doctypes from other apps via hand-crafted JSON + Python controller pairs.

• Doctype States & Status Fields — The undocumented correlation between status fields, workflow_state, and the states array.

Server-Side

• Query Builder & PyPika Extensions — Advanced PyPika usage: custom functions, JSON aggregation, nested set depth, correlated subqueries, and derived tables.

• Common Query Patterns — Everyday reads with frappe.get_all, the client-side frappe.db helpers, child table filters, and set_query for Link fields.

• Script Reports — Tree reports, editable reports, external SQL/columns, chart generation, conditional formatting, and toolbar actions.

• Testing on Live Databases — Integration tests with commit suppression, side-effect patching, and guaranteed rollback.

Client-Side

• Custom Field Controllers — Extending and overriding built-in field types (e.g., Fraction input for Float fields).

• Custom Views — Adding or replacing ListView implementations with entirely new interfaces.

• Quick Entry Forms — Custom dialog forms for efficient data entry with multi-document creation.

• Grandchild Table Fields — Rendering editable tables inside child table row forms using JSON storage.

• Customizing Grid Columns for Child Tables — Forcing custom column sets per parent doctype for shared child tables.

• Client-Side Recipes — Small desk snippets: filling a dialog Select from a query and pushing realtime messages from Python to the browser.

Frontend Integration

• Vite & TypeScript Compilation — Building Vue/TS applications with Vite and integrating compiled assets into Frappe endpoints.

• Custom Pages — Loading standalone applications (Declarative DOM, Vue, etc.) on Frappe Page doctypes.

Web & Portals

• Web Forms — Public data entry forms with custom server-side context loading, client-side validation, and payment integration.

• Portal Views — Authenticated list-mode web forms for displaying data history with sidebar navigation.

• Builder Page Scripts — URL-driven filters on Frappe Builder pages, backed by a Python data script.

Operations

• Bench Operations — Backup and restore, switching app remotes, branches, and major versions, bench console data fixes, and schema repair.