Apps in Frappe Framework (Version 15): Complete Guide
Introduction & Context
In the Frappe Framework (Version 15), an App is the fundamental building block of all features, modules, DocTypes, pages, REST endpoints, scripts, and business logic. Every unit of functionality in ERPNext or any Frappe project exists inside an app. Apps are installed on sites through Bench, allowing a fully modular and scalable architecture.
Frappe apps act as containers for code, assets, UI components, and server logic—making the system highly extensible for custom development, ERPNext enhancements, and enterprise-grade workflows.
What Is an App in Frappe Framework?
A Frappe App is a Python package that contains one or more modules, each holding DocTypes, Pages, Reports, API endpoints, and configurations.
Apps allow developers to:
- Build new business modules
- Extend or override ERPNext features
- Add custom DocTypes & workflows
- Add REST APIs and Python controllers
- Add website/portal pages
- Serve assets like JS, CSS, Images
- Integrate third-party systems
Apps remain isolated, version-controlled packages that can be installed across multiple Frappe sites.
How Apps Work Inside Bench (v15)
Every Frappe bench environment has a directory:
frappe-bench/
└── apps/
├── frappe/
├── erpnext/
└── <custom_app>/
Each app:
- Lives in its own folder
- Has independent controllers, modules, and configuration
- Can be installed/uninstalled using bench commands
- Can be published as a separate open-source or private Python package
Creating a New App in Frappe v15
To create an app:
bench new-app my_app
You will be prompted for:
- App Title
- App Description
- App Publisher
- License
Then install the app on a site:
bench --site site1.local install-app my_app
After installation:
- DocTypes
- Modules
- Workspaces
- API endpoints
- Pages
- Report types
- Hooks
become available on that site.
Understanding the Structure of a Frappe App
A newly generated app follows this structure:
my_app/
│
├── my_app/
│ ├── config/
│ ├── modules.txt
│ ├── hooks.py
│ ├── public/
│ ├── templates/
│ ├── www/
│ └── <module folders>
│
├── setup.py
├── MANIFEST.in
└── README.md
Key components
| Component | Purpose |
| hooks.py | Extends events, APIs, scheduled tasks, DocType events |
| modules.txt | Lists all modules inside the app |
| config/ | Workspace, desktop icons, menu definitions |
| public/ | Static assets (JS, CSS, images) |
| templates/ | Jinja templates for web pages, emails, print formats |
| www/ | Website pages served at /my-page |
| setup.py | Python package details |
| MANIFEST.in | Includes non-Python files during packaging |
Each app can have multiple modules, each with multiple DocTypes.
Apps vs Sites in Frappe v15 — Relationship Explained
Frappe app ≠ Frappe site.
Apps contain:
- Code
- Features
- Metadata
- Controllers
Sites contain:
- Database
- Files
- Site config
- Installed apps
Relationship
A site installs one or more apps, and an app can be installed on many sites.
Example:
| Site | Installed Apps |
| site1.local | frappe, erpnext, my_custom_app |
| site2.com | frappe, my_custom_app |
This makes multi-tenant deployments easy and scalable.
Installing & Managing Frappe Apps
Install an app
bench --site site1.local install-app my_app
Uninstall an app
bench --site site1.local uninstall-app my_app
Get list of apps on a site
bench --site site1.local list-apps
Add app to all sites
bench install-app my_app
Update all apps
bench update
Types of Apps in Frappe
Frappe supports two primary types of apps:
1. Framework Apps
- Core functionality
- Not tied to business modules
Examples:
- frappe
- payments
2. Business Apps
Contain business logic like ERPNext.
Examples:
- erpnext
- healthcare
- education
- custom implementations
Most developers build business apps to extend ERPNext.
Why Apps Are Important in Frappe (v15)
Apps enable:
- Modular development
- Clear separation of concerns
- Reusable functionality across multiple sites
- Faster iteration and deployment
- Safe and stable customization
- Version-controlled updates via Git
Apps ensure organizations can scale without breaking the core framework.
Best Practices for Building Frappe Apps
1. Keep each app focused
Avoid putting unrelated modules in the same app.
2. Always use version control (Git)
Commit only the app, not the bench.
3. Use hooks instead of core modification
Never edit frappe or erpnext source code.
4. Use valid module naming
All module names in modules.txt must exist.
5. Keep dependencies clean
Avoid unnecessary Python packages.
6. Build UI components inside module folders
Maintain consistent folder hierarchy.
Troubleshooting Common App Issues
| Issue | Reason | Fix |
| App not appearing in Desk | Missing workspace definitions | Add config in config/desktop.py |
| ImportError | Missing __init__.py in module folder | Add file and restart bench |
| Hooks not triggering | Wrong dotted path | Correct Python path in hooks.py |
| Static files not loading | Assets not built | Run bench build |
| App fails to install | Missing patches or broken DocTypes | Run bench migrate after fixing |
Cross-References (Recommended Next Steps)
After understanding apps, read:
- Frappe Directory Structure (v15)
- Architecture Overview
- How to Create a DocType in Frappe
- Hooks and Events in Frappe (v15)
- Working with Form Scripts
- Portal Pages in Frappe
Conclusion
Apps form the backbone of the Frappe Framework in Version 15. Whether you’re developing a custom ERP module, integrating third-party services, or building a standalone business solution, mastering Frappe apps is essential. Their modular structure, clean architecture, and powerful event-driven design make Frappe one of the most flexible low-code frameworks available today.
Frappe Framework Apps (Version 15)
Based 100% on:
📘 Reference: https://docs.frappe.io/framework/user/en/basics/apps
📌 GitHub v15: https://github.com/frappe/frappe/tree/version-15
