/frappe-ops-app-lifecycle

name: frappe-ops-app-lifecycle
description: >
  Use when scaffolding a new Frappe app, configuring app settings, building assets, running tests, deploying, updating, or publishing to marketplace.
  Prevents broken app structure from incorrect scaffolding, missing setup.py fields, and failed builds.
  Covers bench new-app, app directory structure, setup.py/pyproject.toml, hooks.py config, bench build, bench run-tests, app publishing.
  Keywords: app lifecycle, new-app, scaffolding, setup.py, pyproject.toml, hooks.py, bench build, app publishing, marketplace, create app, publish app, app structure, how to start new app, app directory layout..
license: MIT
compatibility: "Claude Code, Claude.ai Projects, Claude API. Frappe v14-v16."
metadata:
  author: OpenAEC-Foundation
  version: "2.0"

App Lifecycle Management

Quick Reference

| Command | Purpose | When to Use | |---|---|---| | `bench new-app` | Scaffold new app | Starting a new project | | `bench get-app URL` | Clone from Git | Installing existing app | | `bench --site SITE install-app` | Install on site | After get-app or new-app | | `bench --site SITE remove-app` | Uninstall from site | Removing app from site | | `bench remove-app` | Remove from bench | Removing app entirely | | `bench --site SITE migrate` | Run patches + sync | After code changes | | `bench build` | Compile assets | After JS/CSS changes | | `bench --site SITE console` | Python REPL | Debugging | | `bench start` | Start dev server | Development | | `bench setup production` | Configure nginx+supervisor | Deploying to production |

1. Scaffolding: bench new-app

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

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

| File | Purpose | NEVER Forget | |---|---|---| | `__init__.py` | Defines `__version__` | ALWAYS update before release | | `hooks.py` | ALL framework integration | Entry point for everything | | `modules.txt` | Declares app modules | ALWAYS add new modules here | | `patches.txt` | Migration patch registry | ALWAYS add patches in order | | `requirements.txt` | Python deps installed on setup | Add pip packages here | | `public/` | Static files served by nginx | Accessible at `/assets/app_name/` | | `www/` | Portal pages | Filename = URL path |

2. Development Cycle

Code → Migrate → Build → Test → Commit

Step-by-Step

# 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

# 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:

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.

# 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`:

required_apps = ["frappe", "erpnext"]

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

5. Debugging with bench console

bench --site mysite console

Opens an IPython REPL with Frappe context:

# 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 --aut