Frappe Ops App Lifecycle

App Lifecycle Management

Quick Reference

1. Scaffolding: bench new-app

bashCopy code
bench new-app my_custom_app

Interactive prompts:

• App Title → Human-readable name
• App Description → One-line summary
• App Publisher → Company/author name
• App Email → Contact email
• App Icon → Default: octicon octicon-file-directory
• App Color → Default: grey
• App License → Default: MIT

Generated Directory Structure

Copy code
apps/my_custom_app/
├── MANIFEST.in              # Files included in Python package
├── README.md                # Project readme
├── license.txt              # License file
├── requirements.txt         # Python dependencies
├── dev-requirements.txt     # Dev-only Python deps (v15+)
├── package.json             # Node.js dependencies
├── setup.py                 # Python package config (v14)
├── pyproject.toml           # Python package config (v15+)
├── my_custom_app/
│   ├── __init__.py          # App version string
│   ├── hooks.py             # Framework integration hooks
│   ├── modules.txt          # List of app modules
│   ├── patches.txt          # Migration patches list
│   ├── config/
│   │   ├── __init__.py
│   │   ├── desktop.py       # Desktop/workspace config
│   │   └── docs.py          # Documentation config
│   ├── public/              # Static assets → /assets/my_custom_app/
│   │   ├── css/
│   │   └── js/
│   ├── templates/           # Jinja templates
│   └── www/                 # Portal pages (URL = path)

What Each Core File Does

2. Development Cycle

Copy code
Code → Migrate → Build → Test → Commit

Step-by-Step

bashCopy code
# 1. Make code changes (DocTypes, reports, APIs, etc.)

# 2. Migrate — sync DocType schema + run patches
bench --site mysite migrate

# 3. Build — compile JS/CSS assets
bench build --app my_custom_app

# 4. Test — run Python tests
bench --site mysite run-tests --app my_custom_app

# 5. Commit
git -C apps/my_custom_app add -A && git -C apps/my_custom_app commit -m "feat: add feature"

ALWAYS run bench migrate after modifying DocType JSON files. ALWAYS run bench build after modifying JS/CSS files.

3. Getting Apps from Git

bashCopy code
# Public repo
bench get-app https://github.com/org/my_app

# Specific branch
bench get-app https://github.com/org/my_app --branch develop

# Private repo via SSH
bench get-app git@github.com:org/private_app.git

# Private repo via token (v15+)
bench get-app https://TOKEN@github.com/org/private_app.git

After get-app, ALWAYS install on the target site:

bashCopy code
bench --site mysite install-app my_app

get-app clones to apps/ and adds to apps.txt. install-app creates database tables and runs after_install hooks.

4. Installing and Removing Apps

Installation Order Matters

Apps are installed in order listed in apps.txt. If App B depends on App A, App A MUST be listed first.

bashCopy code
# Install
bench --site mysite install-app my_app

# Verify
bench --site mysite list-apps
# Output: frappe, erpnext, my_app

# Remove from site (keeps code in apps/)
bench --site mysite remove-app my_app

# Remove from bench entirely (deletes code)
bench remove-app my_app

App Dependencies (v14+)

Declare in hooks.py:

pythonCopy code
required_apps = ["frappe", "erpnext"]

Frappe ALWAYS checks required_apps during installation and blocks if dependencies are missing.

5. Debugging with bench console

bashCopy code
bench --site mysite console

Opens an IPython REPL with Frappe context:

pythonCopy code
# Query data
frappe.db.sql("SELECT name, status FROM `tabSales Invoice` LIMIT 5", as_dict=True)

# Get a document
doc = frappe.get_doc("Sales Invoice", "SINV-00001")
print(doc.grand_total)

# Test a whitelisted method
from my_app.api import my_function
result = my_function(param="value")

# Check configuration
frappe.get_site_config()

# Auto-reload on code changes (v15+)
# Start with: bench --site mysite console --autoreload

ALWAYS use bench console for debugging — NEVER modify production data with raw SQL.

6. Development Mode vs Production Mode

Development Mode

bashCopy code
# Enable
bench set-config -g developer_mode 1

# Start dev server (Procfile: web + worker + redis + socketio)
bench start

Development mode enables:

• DocType editing in Desk
• "Is Standard" option for reports/scripts
• Auto-reload on Python file changes
• Detailed error tracebacks in browser
• dev-requirements.txt dependencies installed

Production Mode

bashCopy code
# Disable developer mode
bench set-config -g developer_mode 0

# Setup production (nginx + supervisor)
sudo bench setup production USERNAME

# Restart
sudo supervisorctl restart all
# or
sudo systemctl restart supervisor

Production mode:

• Serves via nginx (port 80/443)
• Background workers via supervisor
• Static files served directly by nginx
• Errors logged to files, not browser
• NEVER enable developer_mode on production sites

7. Asset Building

v15+ (esbuild)

bashCopy code
# Build all apps
bench build

# Build specific app
bench build --app my_custom_app

# Watch mode (auto-rebuild on changes)
bench watch

v14 (build.json)

v14 uses build.json in the app root to map source files to bundles:

jsonCopy code
{
    "css/my_app.css": [
        "public/css/style.css"
    ],
    "js/my_app.js": [
        "public/js/main.js"
    ]
}

Asset Include in hooks.py

pythonCopy code
# Desk (backend UI)
app_include_js = "my_app.bundle.js"      # v15+ bundle syntax
app_include_css = "my_app.bundle.css"

# Portal (website)
web_include_js = "my_app_web.bundle.js"
web_include_css = "my_app_web.bundle.css"

# v14 legacy syntax
app_include_js = "/assets/my_app/js/my_app.js"
app_include_css = "/assets/my_app/css/my_app.css"

ALWAYS run bench build after changing JS/CSS files. ALWAYS run bench clear-cache if assets are not updating.

8. App Versioning

Version String in init.py

pythonCopy code
# my_custom_app/__init__.py
__version__ = "1.2.0"

ALWAYS use semantic versioning: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes
• MINOR: New features (backward compatible)
• PATCH: Bug fixes

The version is read by bench version, displayed in Desk, and used by the Marketplace.

Checking Versions

bashCopy code
bench version
# frappe 15.23.0
# erpnext 15.18.0
# my_custom_app 1.2.0

9. Patches: Data Migrations

Writing a Patch

pythonCopy code
# my_app/patches/v1_2/update_customer_status.py
import frappe

def execute():
    frappe.reload_doc("module_name", "doctype", "customer_extension")

    frappe.db.sql("""
        UPDATE `tabCustomer Extension`
        SET status = 'Active'
        WHERE status IS NULL
    """)
    frappe.db.commit()

Registering in patches.txt

Copy code
# patches.txt — v14+ supports sections

[pre_model_sync]
my_app.patches.v1_1.fix_old_data
my_app.patches.v1_2.rename_field_before_schema

[post_model_sync]
my_app.patches.v1_2.update_customer_status
my_app.patches.v1_2.migrate_settings

Section timing (v14+):

• [pre_model_sync] — Runs BEFORE DocType schema changes are applied
• [post_model_sync] — Runs AFTER schema changes (new fields available)
• No section header — Runs in [pre_model_sync] by default

Patch Rules

• ALWAYS add new patches at the END of their section
• Patches run ONCE — tracked in tabPatch Log
• To re-run a patch, append a comment: my_app.patches.v1_2.fix #2025-03-20
• ALWAYS call frappe.reload_doc() before accessing new/modified DocTypes
• ALWAYS use [post_model_sync] for patches that need new fields
• One-liner patches: execute:frappe.delete_doc("Page", "old-page", ignore_missing=True)

Testing a Patch

bashCopy code
# Run all pending patches
bench --site mysite migrate

# Run a specific patch manually in console
bench --site mysite console
>>> from my_app.patches.v1_2.update_customer_status import execute
>>> execute()
>>> frappe.db.commit()

10. Publishing to Frappe Marketplace

Prerequisites Checklist

1. App hosted on public GitHub repository
2. setup.py or pyproject.toml with correct metadata
3. Valid __version__ in __init__.py
4. README.md with installation instructions
5. All tests passing

setup.py (v14)

pythonCopy code
from setuptools import setup, find_packages

setup(
    name="my_custom_app",
    version="1.0.0",
    description="My Custom App for ERPNext",
    author="Your Name",
    author_email="you@example.com",
    packages=find_packages(),
    zip_safe=False,
    include_package_data=True,
    install_requires=["frappe"],
)

pyproject.toml (v15+)

tomlCopy code
[project]
name = "my_custom_app"
dynamic = ["version"]
requires-python = ">=3.10,<3.13"
dependencies = ["frappe"]

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

Publishing Steps

1. Create account at https://frappecloud.com/marketplace
2. Add your GitHub repository
3. Configure supported versions (v14, v15)
4. Submit for review
5. After approval, app appears in Marketplace

11. App Update Lifecycle on Client Sites

bashCopy code
# Pull latest code
bench update --pull

# Or update specific app
cd apps/my_custom_app && git pull origin main && cd ../..

# Then migrate (runs patches + syncs schema)
bench --site mysite migrate

# Rebuild assets
bench build --app my_custom_app

# Restart workers
bench restart

The bench update command wraps: backup → pull → requirements → migrate → build → restart.

ALWAYS take a backup before running bench update on production. ALWAYS test updates on staging before applying to production.

See Also

• references/examples.md — Complete app scaffolding examples
• references/anti-patterns.md — Common mistakes
• references/workflows.md — Step-by-step workflows
• references/module-workspace-shipping.md — Module Def, modules.txt, and workspace shipping
• frappe-syntax-hooks — Complete hooks.py reference
• frappe-core-database — Database and migration patterns
• frappe-impl-workspace — Workspace builder, components, and customization