Skip to main content

​
Overview

The bench new-app command scaffolds a new Frappe application with the standard directory structure, boilerplate code, and configuration files needed to start developing a custom Frappe app.

​
Syntax

bench new-app [APP_NAME] [OPTIONS]

​
Arguments

​
APP_NAME
string
required
The name of the app to create. Should be lowercase and use underscores for spaces (e.g., my_custom_app).

​
Options

​
--no-git
boolean
default:"false"
Do not initialize a Git repository for the app. By default, a Git repository is created and an initial commit is made.
This option is only available in Frappe v14 and later versions.
bench new-app my_app --no-git

​
Usage Examples

​
Create a Basic App

Create a new app with default settings: 
bench new-app library_management
You’ll be prompted to enter:
  • App Title (displayed in UI)
  • App Description
  • App Publisher
  • App Email
  • App License

​
Create App Without Git

Create an app without initializing Git: 
bench new-app library_management --no-git

​
Non-Interactive Creation

While the command is interactive by default, you can prepare answers in advance by setting environment variables or using a script.

​
What Gets Created

When you run bench new-app, the following structure is created in apps/[app_name]/: 
my_app/
├── my_app/
│   ├── __init__.py
│   ├── hooks.py              # App hooks and configuration
│   ├── modules.txt           # List of modules
│   ├── patches.txt           # Database patches
│   ├── public/               # Static assets (JS, CSS, images)
│   ├── templates/            # Jinja templates
│   ├── www/                  # Web pages
│   └── config/               # App configuration
├── setup.py                  # Python package setup
├── requirements.txt          # Python dependencies
├── package.json              # Node.js dependencies
├── .gitignore
├── README.md
├── license.txt
└── .git/                     # Git repository (unless --no-git)

​
Interactive Prompts

During app creation, you’ll be asked for the following information:

​
App Title

The human-readable name displayed in the UI: 
App Title (default: My App):

​
App Description

A brief description of what your app does: 
App Description: A library management system for schools

​
App Publisher

Your name or organization name: 
App Publisher: Acme Corporation

​
App Email

Contact email for the app: 
App Email: [email protected]

​
App License

The software license (e.g., MIT, GPL-3.0, Proprietary): 
App License (default: MIT):

​
After Creation

After creating a new app, follow these steps:

​
1. Install the App on a Site

bench --site mysite.local install-app library_management

​
2. Start Development

Create your first DocType, Page, or Module: 
bench --site mysite.local add-to-module library_management
Or use the Desk UI to create DocTypes through the browser.

​
3. Version Control

If Git was initialized, make your first changes and commit: 
cd apps/library_management
git add .
git commit -m "Initial app structure"

​
Development Best Practices

​
Naming Conventions

  • App Name: Use lowercase with underscores (e.g., library_management)
  • Module Names: PascalCase (e.g., Library Management)
  • DocType Names: PascalCase with spaces (e.g., Library Member)

​
Directory Structure

Organize your app with clear module separation: 
library_management/
├── library_management/
│   ├── library_management/       # Core module
│   │   └── doctype/
│   ├── library_settings/         # Settings module
│   └── library_reports/          # Reports module

​
Dependencies

Add Python dependencies to requirements.txt: 
requests>=2.25.0
pandas>=1.2.0
Add JavaScript dependencies to package.json: 
{
  "dependencies": {
    "lodash": "^4.17.21"
  }
}

​
hooks.py Configuration

The hooks.py file is the central configuration file for your app. Key configurations include: 
# Scheduled Tasks
scheduler_events = {
    "daily": [
        "library_management.tasks.daily_reminders"
    ]
}

# Document Events
doc_events = {
    "Library Member": {
        "on_update": "library_management.api.send_welcome_email"
    }
}

# Website Route Rules
website_route_rules = [
    {"from_route": "/library/<path:name>", "to_route": "library/book"},
]

​
Common Patterns

​
Creating a Standalone App

For an app that will be distributed: 
bench new-app my_product
cd apps/my_product
git remote add origin [email protected]:yourusername/my_product.git
git push -u origin main

​
Creating a Site-Specific Customization

For client-specific customizations: 
bench new-app client_customizations --no-git

​
Troubleshooting

​
App Name Already Exists

If an app with the same name exists: 
bench remove-app existing_app
bench new-app existing_app

​
Permission Issues

Ensure you have write permissions in the bench directory: 
ls -la apps/
# Check ownership and permissions

Build docs developers (and LLMs) love

Get started for freeTalk to us