frappe-ops-app-lifecycle

アプリのライフサイクル管理

クイックリファレンス

コマンド	目的	使用するタイミング
bench new-app	新しいアプリのひな形を作成	新しいプロジェクトを始めるとき
bench get-app URL	Git からクローン	既存のアプリをインストールするとき
bench --site SITE install-app	サイトにインストール	get-app または new-app の後
bench --site SITE remove-app	サイトからアンインストール	サイトからアプリを削除するとき
bench remove-app	bench から削除	アプリを完全に削除するとき
bench --site SITE migrate	パッチの実行と同期	コードを変更した後
bench build	アセットをコンパイル	JS/CSS を変更した後
bench --site SITE console	Python REPL	デバッグ時
bench start	開発サーバーを起動	開発時
bench setup production	nginx+supervisor を設定	本番環境へデプロイするとき

1. ひな形の作成：bench new-app

bench new-app my_custom_app

対話形式のプロンプト：

• App Title → 人が読みやすい名前
• App Description → 1 行の概要
• App Publisher → 会社名／作者名
• App Email → 連絡先メールアドレス
• App Icon → デフォルト：octicon octicon-file-directory
• App Color → デフォルト：grey
• App License → デフォルト：MIT

生成されるディレクトリ構造

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)

各コアファイルの役割

ファイル	目的	絶対に忘れないこと
__init__.py	__version__ を定義	リリース前に必ず更新する
hooks.py	フレームワークとの連携をすべて定義	すべてのエントリーポイント
modules.txt	アプリのモジュールを宣言	新しいモジュールは必ずここに追加する
patches.txt	移行パッチのレジストリ	パッチは必ず順番どおりに追加する
requirements.txt	セットアップ時にインストールする Python 依存関係	pip パッケージをここに追加する
public/	nginx が配信する静的ファイル	/assets/app_name/ からアクセス可能
www/	ポータルページ	ファイル名が URL パスになる

2. 開発サイクル

Code → Migrate → Build → Test → Commit

手順

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

DocType JSON ファイルを変更した後は、必ず bench migrate を実行してください。 JS/CSS ファイルを変更した後は、必ず bench build を実行してください。

3. 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 [email protected]:org/private_app.git

# Private repo via token (v15+)
bench get-app https://[email protected]/org/private_app.git

get-app の後は、必ず対象サイトにインストールしてください：

bench --site mysite install-app my_app

get-app は apps/ にクローンし、apps.txt に追加します。 install-app はデータベーステーブルを作成し、after_install フックを実行します。

4. アプリのインストールと削除

インストール順序が重要です

アプリは apps.txt に記載された順序でインストールされます。App B が App A に依存する場合、App A を必ず先に記載してください。

# 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

アプリの依存関係（v14 以降）

hooks.py で宣言します：

required_apps = ["frappe", "erpnext"]

Frappe はインストール時に required_apps を必ず確認し、依存関係が不足している場合はインストールをブロックします。

5. bench console でデバッグする

bench --site mysite console

Frappe のコンテキストを持つ IPython REPL が開きます：

# 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

デバッグには必ず bench console を使用してください。生の SQL で本番データを変更してはいけません。

6. 開発モードと本番モード

開発モード

# Enable
bench set-config -g developer_mode 1

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

開発モードでは、次の機能が有効になります：

• Desk での DocType 編集
• レポート／スクリプトの「Is Standard」オプション
• Python ファイル変更時の自動再読み込み
• ブラウザーでの詳細なエラースタックトレース
• dev-requirements.txt の依存関係のインストール

本番モード

# 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

本番モードでは：

• nginx 経由で配信（ポート 80/443）
• バックグラウンドワーカーは supervisor 経由で動作
• 静的ファイルは nginx が直接配信
• エラーはブラウザーではなくファイルに記録
• 本番サイトでは developer_mode を絶対に有効にしないでください

7. アセットのビルド

v15 以降（esbuild）

# 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 では、アプリのルートにある build.json を使用して、ソースファイルをバンドルに対応付けます：

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

hooks.py でのアセットの指定

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

JS/CSS ファイルを変更した後は、必ず bench build を実行してください。 アセットが更新されない場合は、必ず bench clear-cache を実行してください。

8. アプリのバージョン管理

init.py のバージョン文字列

# my_custom_app/__init__.py
__version__ = "1.2.0"

必ずセマンティックバージョニングを使用してください：MAJOR.MINOR.PATCH

• MAJOR：互換性を破壊する変更
• MINOR：新機能（後方互換性あり）
• PATCH：バグ修正

バージョンは bench version で読み取られ、Desk に表示され、Marketplace で使用されます。

バージョンの確認

bench version
# frappe 15.23.0
# erpnext 15.18.0
# my_custom_app 1.2.0

9. パッチ：データ移行

パッチの作成

# 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()

patches.txt への登録

# 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

セクションのタイミング（v14 以降）：

• [pre_model_sync] — DocType のスキーマ変更が適用される前に実行されます
• [post_model_sync] — スキーマ変更後に実行されます（新しいフィールドを利用できます）
• セクションヘッダーなし — デフォルトで [pre_model_sync] で実行されます

パッチのルール

• 新しいパッチは必ずセクションの末尾に追加してください
• パッチは一度だけ実行されます。tabPatch Log で追跡されます
• パッチを再実行するには、コメントを追加します：my_app.patches.v1_2.fix #2025-03-20
• 新規または変更された DocType にアクセスする前に、必ず frappe.reload_doc() を呼び出してください
• 新しいフィールドが必要なパッチには、必ず [post_model_sync] を使用してください
• 1 行のパッチ：execute:frappe.delete_doc("Page", "old-page", ignore_missing=True)

パッチのテスト

# 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. Frappe Marketplace への公開

前提条件チェックリスト

1. アプリが公開 GitHub リポジトリでホストされている
2. 正しいメタデータを含む setup.py または pyproject.toml
3. __init__.py に有効な __version__ がある
4. インストール手順を記載した README.md
5. すべてのテストに合格している

setup.py（v14）

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="[email protected]",
    packages=find_packages(),
    zip_safe=False,
    include_package_data=True,
    install_requires=["frappe"],
)

pyproject.toml（v15 以降）

[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"

公開手順

1. https://frappecloud.com/marketplace でアカウントを作成します
2. GitHub リポジトリを追加します
3. 対応バージョン（v14、v15）を設定します
4. 審査に提出します
5. 承認後、アプリが Marketplace に表示されます

11. クライアントサイトでのアプリ更新ライフサイクル

# 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

bench update コマンドは、バックアップ → プル → 依存関係の取得 → マイグレーション → ビルド → 再起動を実行します。

本番環境で bench update を実行する前に、必ずバックアップを取得してください。 本番環境に適用する前に、必ずステージング環境で更新をテストしてください。

関連項目

• references/examples.md — アプリの完全なスキャフォールディング例
• references/anti-patterns.md — よくある間違い
• references/workflows.md — 手順ごとのワークフロー
• references/module-workspace-shipping.md — Module Def、modules.txt、ワークスペースの公開
• frappe-syntax-hooks — hooks.py の完全なリファレンス
• frappe-core-database — データベースとマイグレーションのパターン
• frappe-impl-workspace — ワークスペースビルダー、コンポーネント、カスタマイズ