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?

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

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

Critical Rules

✅ ALWAYS

1. Define __version__ in __init__.py
2. Add dynamic = ["version"] in pyproject.toml
3. Register modules in modules.txt
4. Include __init__.py in EVERY directory
5. Put Frappe dependencies in [tool.bench.frappe-dependencies]
6. Add error handling in patches
7. Use batch processing for large datasets

❌ NEVER

1. Put Frappe/ERPNext in project dependencies (not on PyPI)
2. Create patches without error handling
3. Include user/transactional data in fixtures
4. Hardcode site-specific values
5. Process large datasets without batching

Fixtures vs Patches

Reference Files

See Also

• erpnext-syntax-hooks – For hooks.py configuration
• erpnext-syntax-controllers – For DocType controllers
• erpnext-impl-customapp – For implementation patterns