ERPNext Custom App Syntax Skill

Complete syntax for building Frappe custom apps in v14/v15, including build configuration, module organization, patches and fixtures.

When to Use This Skill

USE this skill when you:

• Create a new Frappe/ERPNext custom app

• Configure pyproject.toml or setup.py

• Organize modules within an app

• Write database migration patches

• Configure fixtures for data export/import

• Manage app dependencies

DO NOT USE for:

• DocType controllers (use erpnext-syntax-controllers)

• Client Scripts (use erpnext-syntax-clientscripts)

• Server Scripts (use erpnext-syntax-serverscripts)

• Hooks configuration (use erpnext-syntax-hooks)

App Structure Overview

v15 (pyproject.toml - Primary)

apps/my_custom_app/ ├── pyproject.toml # Build configuration ├── README.md ├── my_custom_app/ # Main package │ ├── init.py # MUST contain version! │ ├── hooks.py # Frappe integration │ ├── modules.txt # Module registration │ ├── patches.txt # Migration scripts │ ├── patches/ # Patch files │ ├── my_custom_app/ # Default module │ │ └── doctype/ │ ├── public/ # Client assets │ └── templates/ # Jinja templates └── .git/

See: references/structure.md for complete directory structure.

Critical Files

init.py (REQUIRED)

my_custom_app/init.py

version = "0.0.1"

CRITICAL: Without version the flit build fails!

pyproject.toml (v15)

[build-system] requires = ["flit_core >=3.4,<4"] build-backend = "flit_core.buildapi"

[project] name = "my_custom_app" authors = [ { name = "Your Company", email = "dev@example.com" } ] description = "Description of your app" requires-python = ">=3.10" readme = "README.md" dynamic = ["version"] dependencies = []

[tool.bench.frappe-dependencies] frappe = ">=15.0.0,<16.0.0" erpnext = ">=15.0.0,<16.0.0"

See: references/pyproject-toml.md for all configuration options.

Modules

modules.txt

My Custom App Integrations Settings Reports

Rules:

• One module per line

• Spaces in name → underscores in directory

• Every DocType MUST belong to a module

Module Directory

my_custom_app/ ├── my_custom_app/ # "My Custom App" module │ ├── init.py # REQUIRED │ └── doctype/ ├── integrations/ # "Integrations" module │ ├── init.py # REQUIRED │ └── doctype/ └── settings/ # "Settings" module ├── init.py # REQUIRED └── doctype/

See: references/modules.md for module organization.

Patches (Migration Scripts)

patches.txt with INI Sections

[pre_model_sync]

Before schema sync - old fields still available

myapp.patches.v1_0.backup_old_data

[post_model_sync]

After schema sync - new fields available

myapp.patches.v1_0.populate_new_fields myapp.patches.v1_0.cleanup_data

Patch Implementation

myapp/patches/v1_0/populate_new_fields.py

import frappe

def execute(): """Populate new fields with default values."""

batch_size = 1000
offset = 0

while True:
    records = frappe.get_all(
        "MyDocType",
        filters={"new_field": ["is", "not set"]},
        fields=["name"],
        limit_page_length=batch_size,
        limit_start=offset
    )
    
    if not records:
        break
    
    for record in records:
        frappe.db.set_value(
            "MyDocType",
            record.name,
            "new_field",
            "default_value",
            update_modified=False
        )
    
    frappe.db.commit()
    offset += batch_size

When Pre vs Post Model Sync?

Situation Section

Migrate data from old field [pre_model_sync]

Populate new fields [post_model_sync]

Data cleanup [post_model_sync]

See: references/patches.md for complete patch documentation.

Fixtures

hooks.py Configuration

fixtures = [ # All records "Category",

# With filter
{
    "dt": "Custom Field",
    "filters": [["module", "=", "My Custom App"]]
},

# Multiple filters
{
    "dt": "Property Setter",
    "filters": [
        ["module", "=", "My Custom App"],
        ["doc_type", "in", ["Sales Invoice", "Sales Order"]]
    ]
}

]

Exporting

bench --site mysite export-fixtures --app my_custom_app

Common Fixture DocTypes

DocType Usage

Custom Field

Custom fields on existing DocTypes

Property Setter

Modify field properties

Role

Custom roles

Workflow

Workflow definitions

See: references/fixtures.md for fixture configuration.

Minimal hooks.py

app_name = "my_custom_app" app_title = "My Custom App" app_publisher = "Your Company" app_description = "Description" app_email = "dev@example.com" app_license = "MIT"

required_apps = ["frappe"] # Or ["frappe", "erpnext"]

fixtures = [ {"dt": "Custom Field", "filters": [["module", "=", "My Custom App"]]} ]

Creating and Installing App

Create new app

bench new-app my_custom_app

Install on site

bench --site mysite install-app my_custom_app

Migrate (patches + fixtures)

bench --site mysite migrate

Build assets

bench build --app my_custom_app

Version Differences

Aspect v14 v15

Build config setup.py pyproject.toml

Dependencies requirements.txt In pyproject.toml

Build backend setuptools flit_core

Python minimum

=3.10 =3.10

INI patches ✅ ✅

Critical Rules

✅ ALWAYS

• Define version in init.py

• Add dynamic = ["version"] in pyproject.toml

• Register modules in modules.txt

• Include init.py in EVERY directory

• Put Frappe dependencies in [tool.bench.frappe-dependencies]

• Add error handling in patches

• Use batch processing for large datasets

❌ NEVER

• Put Frappe/ERPNext in project dependencies (not on PyPI)

• Create patches without error handling

• Include user/transactional data in fixtures

• Hardcode site-specific values

• Process large datasets without batching

Fixtures vs Patches

What Fixtures Patches

Custom Fields ✅ ❌

Property Setters ✅ ❌

Roles/Workflows ✅ ❌

Data transformation ❌ ✅

Data cleanup ❌ ✅

One-time migration ❌ ✅

Reference Files

File Contents

references/structure.md

Complete directory structure

references/pyproject-toml.md

Build configuration options

references/modules.md

Module organization

references/patches.md

Migration scripts

references/fixtures.md

Data export/import

references/examples.md

Complete app examples

references/anti-patterns.md

Mistakes to avoid

See Also

• erpnext-syntax-hooks

• For hooks.py configuration

• erpnext-syntax-controllers

• For DocType controllers

• erpnext-impl-customapp

• For implementation patterns